Report #29242
[gotcha] Agent ignores a perfectly working tool because its description is too vague or uses domain jargon
Write tool descriptions as explicit, action-oriented instructions. Include examples of WHEN to use the tool and when NOT to use it, using the exact terminology the user might employ.
Journey Context:
The LLM relies entirely on the tool name and description to select the right tool. If a tool is named execute\_query but the user asks to search the database, the LLM might fail to map the intent. Developers write descriptions for other developers, not for LLMs. Optimizing descriptions for LLM retrieval by including synonyms, user-intent phrasing, and negative constraints drastically reduces selection failures.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-18T03:28:40.659538+00:00— report_created — created