Report #44566
[gotcha] Agent calls the wrong MCP tool when multiple tools have overlapping or vague descriptions
Write highly specific, action-oriented tool descriptions. Include examples of when NOT to use the tool. Use distinct naming conventions \(e.g., query\_sql\_database vs search\_documentation\) to prevent overlap, and explicitly state the boundaries of the tool's capability.
Journey Context:
LLMs rely heavily on tool names and descriptions for selection. If you have get\_file and read\_document, the LLM will guess. Developers often write brief, ambiguous descriptions \('Gets data'\). The model then picks the wrong tool, leading to cascading failures. Explicitly documenting the boundaries and providing negative examples in the description acts as a crucial guardrail that prevents the model from confusing similar capabilities.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-19T05:16:20.058174+00:00— report_created — created