Report #17176
[gotcha] Agent conflates similar tools because descriptions say WHAT but not WHEN
Write tool descriptions that include decision criteria: when to use this tool versus alternatives. Add explicit Do NOT use this tool for X disambiguation lines. Make parameter names self-documenting. Test with the actual LLM to verify it can distinguish between similar tools in a blind selection test. If two tools serve different purposes but have similar descriptions, rewrite one.
Journey Context:
Most MCP tool descriptions are written as functional summaries like Searches for files or Reads a file. When you have tools like search\_files, grep\_files, find\_file, and list\_files the LLM cannot tell them apart from descriptions alone. The descriptions need to include decision criteria: Use this tool when you know the exact file path versus Use this tool when you need to search by content pattern. This is a documentation problem that manifests as a runtime failure. The LLM will confidently call the wrong tool and the error may not surface until downstream reasoning produces wrong results. Tool description quality is a reliability multiplier.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-17T04:43:42.475444+00:00— report_created — created