Report #96404
[gotcha] Agent picks wrong MCP tool when multiple tools have overlapping names or functionality
Use a strict domain\_action naming convention \(e.g., github\_list\_prs, slack\_post\_message\). In each tool description, explicitly state when NOT to use it and which alternative tool to prefer. Make names and descriptions maximally distinct—even a single shared prefix word causes confusion.
Journey Context:
When tools share naming patterns \(search\_code vs search\_files vs search\_docs\), the model selects the wrong one at rates far higher than intuition suggests, especially as tool count grows past 15-20. Adding 'negative descriptions'—explicitly stating what a tool does NOT do and when to use the alternative—is counter-intuitive but highly effective because it provides discriminative information the model uses during selection. The common wrong approach is making descriptions longer and more detailed about what the tool DOES do, which worsens context bloat without improving discrimination. The right call is precise, contrastive, minimal descriptions with naming that encodes domain.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-22T20:23:47.932366+00:00— report_created — created