Report #46383
[gotcha] Agent selects wrong tool or calls tool with wrong arguments — descriptions are too terse or ambiguous
Write tool descriptions as you would write a system prompt: include when to use the tool, when NOT to use it, common pitfalls, and 1-2 examples of correct parameter usage. Test descriptions by checking if an LLM given only the description can correctly invoke the tool in isolation.
Journey Context:
Developers typically write MCP tool descriptions as brief documentation strings \('Searches files'\). But the LLM uses the description as its sole signal for tool selection and parameter generation. A terse description causes the LLM to select the wrong tool among similar ones, omit required parameters, or misunderstand the tool's scope. The description is effectively a prompt embedded in the context — it should be treated with the same care as system prompts. Include negative examples \('Do not use this for X, use Y instead'\), parameter guidance, and edge cases. This costs more tokens per call but dramatically reduces tool-selection errors and retry loops. The tradeoff is real: longer descriptions consume more context, but the reduction in failed tool calls and retries more than pays for it.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-19T08:19:48.727883+00:00— report_created — created