Claus Ibsen created CAMEL-25040:
-----------------------------------
Summary: camel-jbang-mcp - camel_catalog_doc returns only the
option list, not the syntax a component's documentation explains
Key: CAMEL-25040
URL: https://issues.apache.org/jira/browse/CAMEL-25040
Project: Camel
Issue Type: Improvement
Components: camel-jbang
Reporter: Claus Ibsen
{{camel_catalog_doc}} of a component returns the catalog entry: description,
syntax, usage line, and the option list. For {{sql}} that is about 15 KB. What
it does not carry is the part of the component's documentation that is not an
option -- and for several components that is exactly the part an author needs.
The {{sql}} component is the clearest case. Its named-parameter syntax
{{:#name}} (and {{:#${simple}}}) appears nowhere in the 15 KB:
* {{allowNamedParameters}} -- "Whether to allow using named parameters in the
queries."
* under another option -- "Notice if you use named parameters, then a Map type
is used instead."
Neither says what a named parameter looks like. The AsciiDoc page
{{sql-component.adoc}} explains it fully in its first 80 lines, with the lookup
precedence and the simple-expression form, but that page is only reachable
through {{camel_catalog_docs}} / {{camel_catalog_doc}} by page name, which an
author who does not already know the answer has no reason to ask for.
Observed: in a 10-pass measurement of a local model writing this route, one
pass called {{camel_catalog_doc(sql)}} six times in a row -- the same call, the
same 15 KB back -- and reached its first file write on its last available tool
call. All 10 passes of that step exhausted their tool-call budget, and 6 of the
10 never wrote anything at all.
Suggestions, either would help:
* include a short usage excerpt from the component's AsciiDoc page in
{{camel_catalog_doc}} when one exists (the prose before the first option table
is usually the syntax and the essentials);
* or at minimum end the answer with a pointer: which AsciiDoc page documents
this component and that it covers what the option list does not.
Filed from the benchmark of the camel-jbang-mcp server's tools; see the sibling
camel-sql issue for the other half of the same failure.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
