Report #12862
[gotcha] LLM selects the wrong MCP tool despite correct tools being available
Write tool descriptions as if explaining to a junior developer. Include concrete examples of WHEN to use and WHEN NOT to use the tool, and specify the exact shape of the input data.
Journey Context:
Developers often write tool descriptions as brief API summaries \(e.g., 'Gets user data'\). LLMs rely heavily on these descriptions for tool selection. If multiple tools have overlapping purposes or vague descriptions, the LLM will guess and often pick the wrong one. The fix is verbose, highly specific descriptions with negative constraints \(e.g., 'Use this ONLY for fetching user profiles by ID, NOT for searching users by name'\). The tradeoff is consuming more context tokens, but precision prevents costly wrong-tool calls.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T17:13:02.467725+00:00— report_created — created