Jiří Ondrušek created CAMEL-27253:
-------------------------------------

             Summary: 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


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