[ 
https://issues.apache.org/jira/browse/CAMEL-27253?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
 ]

Claus Ibsen updated CAMEL-27253:
--------------------------------
    Fix Version/s: 4.24.0

> camel-ai-tool: documentation and error message inaccuracies (tags default 
> pool, langchain4j-tools hint, mcp-server hints)
> -------------------------------------------------------------------------------------------------------------------------
>
>                 Key: CAMEL-27253
>                 URL: https://issues.apache.org/jira/browse/CAMEL-27253
>             Project: Camel
>          Issue Type: Bug
>          Components: camel-ai
>            Reporter: Jiří Ondrušek
>            Assignee: Jiří Ondrušek
>            Priority: Minor
>             Fix For: 4.24.0
>
>
> h3. Problem
> A review of the camel-ai-tool documentation (4.22.2) against the 
> implementation found three statements that do not match the code.
> h3. Inaccuracies
> # The {{tags}} option description says: "When omitted, the tool goes into a 
> default pool available to all producers". The default pool is only merged 
> into a query for a tag ({{AiToolRegistry.getToolsByTag}}). A producer without 
> {{tags}} gets no registry tools. Checked with small tests on 4.22.2: 
> langchain4j-agent ({{LangChain4jAgentProducer}} L288), openai 
> ({{OpenAIRouteToolSupport}} L42) and spring-ai-chat ({{SpringAiChatProducer}} 
> L979, debug log "No tags configured, skipping tool discovery") offer no tools 
> without {{tags}}, and the default pool with {{tags=foo}}. The MCP server 
> bridge never exposes the default pool, not even with {{tags=*}} 
> ({{McpServerBridge}}). Suggested wording: "Comma-separated tags used to group 
> tools. When omitted, the tool goes into a default pool that is added to the 
> tools of every tag a producer selects with its own tags option; producers 
> without tags receive no registry tools, and the MCP server never exposes the 
> default pool." The text is generated into the component docs, the catalog and 
> the endpoint DSL javadoc.
> # The endpoint error message tells users to use {{langchain4j-tools}}, 
> {{spring-ai-chat}} or {{openai}}. {{langchain4j-tools}} is deprecated since 
> 4.22 and does not read {{AiToolRegistry}}. Suggested: name 
> {{langchain4j-agent}}.
> # {{mcp-server.adoc}}, "Tool annotation hints", lists title, readOnly, 
> destructive, idempotent and openWorld. The bridge also passes 
> {{returnDirect}}. Suggested: add it.
> h3. Behaviour that is not documented (optional)
> * Argument names starting with {{camel}} or {{org.apache.camel.}} 
> (case-insensitive) are silently dropped, which also hits names such as 
> {{cameraId}}.
> * Undeclared arguments are dropped with a warning; a tool that declares no 
> parameters accepts none; a missing required argument is returned to the model 
> as an error.
> * A duplicate tool name under the same tag (or in the default pool) throws 
> {{IllegalArgumentException}}; the same name under different tags is fine.
> * Type aliases (int, long, double, float, bool) and the silent fallback to 
> {{string}}; an unknown {{parameter.x.foo}} only logs a warning.
> * {{argSchema}} rules: at least one property, {{type}} must be {{object}}, 
> {{required}} must be a subset of {{properties}}, placeholders are resolved, 
> validation happens at route start.
> * {{tags=*}} is a wildcard only in the MCP server bridge; the producers 
> (langchain4j-agent, openai, spring-ai-chat) treat {{*}} as a literal tag.
> * The openai endpoint snapshots the route tools when it starts and ignores 
> default-pool registry events, so a default-pool tool registered after the 
> producer started is not offered.
> * Registration timing: early at route warm-up; suspend deregisters and resume 
> registers again.
> _Generated with [Claude Code|https://claude.com/claude-code] on behalf of 
> [~jondruse]_



--
This message was sent by Atlassian Jira
(v10.3.26#10030026)

Reply via email to