Support MCP tool annotations for composite tools

deploy/charts/operator-crds/files/crds/toolhive.stacklok.dev_virtualmcpcompositetooldefinitions.yaml

@@ -68,6 +68,57 @@ spec:
               This embeds the CompositeToolConfig from pkg/vmcp/config to share the configuration model
               between CLI and operator usage.
             properties:
+              annotations:
+                description: |-
+                  Annotations declares MCP tool annotations for the composite tool.
+
+                  Annotation derivation runs at ADVERTISE TIME (when tools/list is served
+                  and the backend tools are aggregated), not at CRD admission — thv vmcp
+                  validate does NOT check annotation contradictions. The derived floor is
+                  fail-closed: when the workflow has one or more tool steps the floor is
+                  always non-nil, and any step whose annotations are nil/unknown taints the
+                  floor conservatively (readOnly=false, destructive=true, openWorld=true).
+                  A workflow with no tool steps (e.g. only elicitation) has no floor.
+
+                  When nil, annotations are derived from the annotations of the backend tools
+                  referenced by the workflow's steps (e.g. readOnlyHint is true only when every
+                  step tool is read-only). When set, the values are an explicit author
+                  declaration merged over the derived floor — subject to a safety-floor
+                  guardrail that drops the composite tool (with a warning naming the offending
+                  step tools) if an explicit hint would make the tool look safer than its
+                  steps allow.
+                properties:
+                  destructiveHint:
+                    description: |-
+                      DestructiveHint sets the destructive hint annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: boolean
+                  idempotentHint:
+                    description: |-
+                      IdempotentHint sets the idempotent hint annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: boolean
+                  openWorldHint:
+                    description: |-
+                      OpenWorldHint sets the open-world hint annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: boolean
+                  readOnlyHint:
+                    description: |-
+                      ReadOnlyHint sets the read-only hint annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: boolean
+                  title:
+                    description: |-
+                      Title sets the human-readable title annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: string
+                type: object
               description:
                 description: Description describes what the workflow does.
                 type: string
@@ -467,6 +518,57 @@ spec:
               This embeds the CompositeToolConfig from pkg/vmcp/config to share the configuration model
               between CLI and operator usage.
             properties:
+              annotations:
+                description: |-
+                  Annotations declares MCP tool annotations for the composite tool.
+
+                  Annotation derivation runs at ADVERTISE TIME (when tools/list is served
+                  and the backend tools are aggregated), not at CRD admission — thv vmcp
+                  validate does NOT check annotation contradictions. The derived floor is
+                  fail-closed: when the workflow has one or more tool steps the floor is
+                  always non-nil, and any step whose annotations are nil/unknown taints the
+                  floor conservatively (readOnly=false, destructive=true, openWorld=true).
+                  A workflow with no tool steps (e.g. only elicitation) has no floor.
+
+                  When nil, annotations are derived from the annotations of the backend tools
+                  referenced by the workflow's steps (e.g. readOnlyHint is true only when every
+                  step tool is read-only). When set, the values are an explicit author
+                  declaration merged over the derived floor — subject to a safety-floor
+                  guardrail that drops the composite tool (with a warning naming the offending
+                  step tools) if an explicit hint would make the tool look safer than its
+                  steps allow.
+                properties:
+                  destructiveHint:
+                    description: |-
+                      DestructiveHint sets the destructive hint annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: boolean
+                  idempotentHint:
+                    description: |-
+                      IdempotentHint sets the idempotent hint annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: boolean
+                  openWorldHint:
+                    description: |-
+                      OpenWorldHint sets the open-world hint annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: boolean
+                  readOnlyHint:
+                    description: |-
+                      ReadOnlyHint sets the read-only hint annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: boolean
+                  title:
+                    description: |-
+                      Title sets the human-readable title annotation.
+                      For tool overrides this replaces the backend value; for composite tools
+                      it is an explicit declaration merged over the derived safety floor.
+                    type: string
+                type: object
               description:
                 description: Description describes what the workflow does.
                 type: string