Federico Mariani created CAMEL-24332:
----------------------------------------
Summary: camel-ai-tool - MCP tool annotations
(readOnly/destructive/idempotent hints) as endpoint metadata
Key: CAMEL-24332
URL: https://issues.apache.org/jira/browse/CAMEL-24332
Project: Camel
Issue Type: Improvement
Components: camel-ai
Reporter: Federico Mariani
Follow-up from CAMEL-24308 (camel-mcp-server).
MCP tools can carry optional behavioral *hints* ({{ToolAnnotations}} in the MCP
specification): {{readOnlyHint}} (the tool only reads), {{destructiveHint}}
(may perform irreversible updates), {{idempotentHint}} (safe to retry with the
same arguments), {{openWorldHint}} (interacts with external systems), plus a
display {{title}}. Agent clients use them for per-tool policy — e.g.
auto-approving read-only tools while requiring explicit user confirmation
before destructive ones, or retrying idempotent calls.
Today an {{ai-tool}} route cannot declare any of these. Proposed scope:
* New optional {{@UriParam}} options on the ai-tool consumer endpoint, e.g.
{{ai-tool:delete_order?destructive=true&idempotent=false&readOnly=false&title=Delete
order}}.
* Carry them on {{AiToolSpec}} and through the {{McpServerTool}} SPI in
camel-mcp-server-api.
* Map them in every engine — all three APIs already support them: MCP Java SDK
{{McpSchema.ToolAnnotations}} (Vert.x engine), quarkiverse
{{ToolManager.ToolDefinition.setAnnotations()}} (camel-quarkus), Spring AI
{{@McpTool(annotations = ...)}} / sync tool specification (camel-spring-boot).
* Annotations are advisory/untrusted per the MCP spec — document that they are
hints for clients, not enforcement.
Note: this extends the {{McpServerTool}} SPI ({{@since 4.22}}). Deciding the
shape before Camel 4.22 ships avoids evolving a released SPI.
----
_This issue was drafted by Claude Code on behalf of Federico Mariani._
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
