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)