[
https://issues.apache.org/jira/browse/CAMEL-25040?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18119701#comment-18119701
]
Claus Ibsen commented on CAMEL-25040:
-------------------------------------
Correcting the evidence, though the improvement itself stands.
I said the model called `camel_catalog_doc(sql)` six times because it could not
find the named-parameter syntax. Reading the traces properly, it was asking
about something else: *"let me check how to handle upsert in H2"*, *"check the
SQL component for how to handle upserts and named parameters"*. The parameter
syntax it had already been given by the validator (CAMEL-24869) when
`camel_edit_file` refused its write.
What it was actually hunting for was H2's upsert dialect, which no Camel
catalog can supply. So the excerpt would not have rescued that step either.
The gap this issue describes is still real and is worth fixing on its own
terms: an option list cannot teach syntax that is not an option, and for `sql`
the `:#name` form appears nowhere in 15 KB of options while the component's
page explains it in its first 80 lines. The excerpt puts it in the answer. I
have simply removed the benchmark step from the case for it.
> 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
> Priority: Major
>
> {{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)
