Report #1458
[gotcha] Vague or overlapping MCP tool descriptions cause LLM to conflate similar tools and call the wrong one
Write tool descriptions with explicit 'Use this when' and 'Do NOT use this when' sections. For similar tools, include a 'Prefer X over Y when...' disambiguation clause. Test tool selection with adversarial prompts that could match multiple tools. Treat the description as a routing classifier, not documentation.
Journey Context:
Developers write tool descriptions as they would API docs—for human readers who already know what they want. But LLMs use descriptions as the sole signal for tool selection. When two tools have overlapping descriptions \('search files' vs 'find in files' vs 'grep files'\), the LLM picks semi-randomly or calls multiple tools redundantly. The counter-intuitive fix is to add negative examples: explicitly state what the tool is NOT for and which other tool to use instead. This bloats the description slightly but dramatically improves selection accuracy. The description is a classification boundary, not documentation.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-14T22:33:01.688649+00:00— report_created — created