Federico Mariani created CAMEL-25646:
----------------------------------------
Summary: camel-jbang-mcp - ship MCP server instructions: the rules
an agent needs before its first call, front-loaded, version-aware
Key: CAMEL-25646
URL: https://issues.apache.org/jira/browse/CAMEL-25646
Project: Camel
Issue Type: Improvement
Components: camel-jbang-mcp
Reporter: Federico Mariani
camel-jbang-mcp returns no {{instructions}} in its MCP {{initialize}} response:
{{quarkus.mcp.server.server-info.instructions}} is unset and no
{{io.quarkiverse.mcp.server.InitialResponseInfo}} bean exists
(quarkus-mcp-server 2.0.2 supports both;
{{McpMessageHandler.buildInstructions}} asks the beans first, then the
property).
Agent hosts read that field before the first tool call, and on the hosts that
defer tool schemas it is the only text of the server the model sees at session
start:
|| Host || Tool schemas at session start || How the model reaches a tool ||
Server {{instructions}} ||
| Claude Code 2.1.29x | deferred: tool names only ({{ENABLE_TOOL_SEARCH}} unset
= always defer; {{auto}} = defer above 10% of the context) | ToolSearch
{{select:<name>}}: 113 such calls in the evaluation, every one by name | loaded
at session start, up to 4096 characters |
| Codex CLI (main, 2026-10-14) | deferred: tool search is on by default
({{core/tests/suite/search_tool.rs}}, {{mcp_tool_exposure.rs:84}}) |
tool_search | read from {{initialize}}, used as server-wide guidance; the first
512 characters matter most; {{enabled_tools}}/{{disabled_tools}} per server on
the client side |
| OpenCode (main, 2026-10-14) | code mode by default: tools are not declared,
the prompt carries one catalog line per tool | an {{execute}} script calling
{{tools["<server>"]}} | full text in an {{<mcp_instructions>}} block, re-sent
when it changes |
| Pi (main, 2026-10-14) | {{codemode}} by default (scripts use
{{searchTools()}}), {{deferred}} via tool_search, {{direct}} per tool | scripts
or tool_search | only the FIRST LINE reaches the system prompt; the full text
through {{describeNamespace()}} in scripts |
| Bob Shell 2.0.5 | all schemas up front (995 evaluation calls, no search step)
| direct | not documented |
h3. Why it matters: the evaluation
In an evaluation of coding agents (Claude Code with Haiku 5.5 and Sonnet 5.5,
IBM Bob) on ten legacy-to-Camel migration tasks with camel-jbang-mcp 4.22.1
(419 trials), the measured gain of the camel-kit arm came from its generated
AGENTS.md rules and the .mcp.json, not from its skills, and the task prompt had
to carry a note on how to call the server (components by scheme, the three
version arguments, validate before finishing). The waste that remained came
from questions no tool answers and the agents went hunting for:
* {{camel.server.port}} under {{camel run}} needs
{{camel.server.enabled=true}}: 30 knowledge searches, 12
{{camel_component_properties platform-http}} calls and jar archaeology
({{Run.class}} disassembled in 35 plain-arm trials), 5 of 10 Bob trials on one
task bound 8080 after 15-47 calls each.
* extra jars: {{camel.jbang.dependencies}} in a properties file passed on the
command line is ignored; agents grepped camel-jbang-core and camel-main jars
for it in both plain and MCP arms (Sonnet in the MCP arm included, which made
0-2 MCP calls per trial).
* mail: the Subject/From/To headers are ignored unless {{useHeader*=true}}; 11
sessions sent a mail with an empty subject; plain arms disassembled
{{MailConfiguration}} (31), {{MailBinding}} (15), {{MailConstants}} (11).
* onException/errorHandler/routeConfiguration are top-level entries and
{{handled}} is an expression: 44 of 53 {{camel_validate_yaml_dsl}} calls were
invalid, placement 10 and the handled shape 3 of them.
* {{smtp}} not {{mail}}, {{platform-http}} for the HTTP server: "Component not
found: mail" and {{optionsFilter: tls}} hunts.
None of this needs a tool call. Instructions reach every host above with zero
calls, which is the one change that helps a small model (fewer unanswerable
hunts) and a large one (Sonnet digs jars instead of calling tools) alike.
h3. Proposal
An {{InitialResponseInfo}} bean in camel-jbang-mcp (programmatic, so the text
can carry the CLI's own Camel version and, later, the active profile of
CAMEL-25537), under 4096 characters, front-loaded:
# One summary line first: Pi shows only that line, Codex weights the first 512
characters. Something like: "Apache Camel <version> catalog, validation and run
tools. Look components up by URI scheme (smtp, platform-http); validate with
camel_validate_source before finishing."
# The rules, in order of what they cost in the evaluation: components by
scheme; onException/errorHandler/routeConfiguration/intercept/onCompletion are
top-level entries beside {{route}}, never steps, and {{handled}}/{{continued}}
are expressions ({{handled: {constant: "true"}}}); under {{camel run}}:
{{camel.server.enabled=true}} + {{camel.server.port}}, extra jars with
{{--dep}} or a {{//DEPS}} line, not in a properties file passed on the command
line; mail: Subject/From/To headers ignored unless
{{useHeaderSubject}}/{{useHeaderFrom}}/{{useHeaderRecipients}}; strip
{{Camel*}} headers ({{removeHeaders}}) before an http or mail producer; xslt
gets headers and variables as parameters; a YAML schema pass is not a runtime
pass, run the app and read the log.
# A question-to-tool map by tool name, since the deferred hosts pick a tool by
its name before reading any description: options and URI rules of a component
({{camel_catalog_doc}}), which component for a protocol
({{camel_catalog_find}}), a validated YAML sample and where it goes
({{camel_catalog_sample}}), the Maven/{{--dep}} coordinates of a class
({{camel_dependency_for_class}}), validate ({{camel_validate_source}}), run and
read the log ({{camel_run}}, {{camel_get_log}}, {{camel_get_errors}}).
# Keep it versioned with the release: the mail defaults changed in 4.21, the
YAML shape rules with the DSL.
# Document the text in camel-jbang-mcp.adoc, and a test that the initialize
response carries it and that it stays under 4096 characters.
Not part of this issue: the same rules for the TUI ({{camel tui --mcp}} shares
the registry but not the Quarkus server), and the eval-side probe of whether
Bob shows the text to its model.
Related: CAMEL-25537 (profiles; the instructions should name the tools of the
active profile), CAMEL-25639 (consolidation; tool names chosen for name-level
discovery), CAMEL-25541, CAMEL-25539, CAMEL-25534, CAMEL-25533.
_Claude Code on behalf of Croway_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
