Report #39115
[tooling] Agent selects wrong MCP tool or hallucinates parameters due to vague descriptions
Include 'When to use:' and 'Returns:' sections in tool descriptions; avoid generic verbs like 'get' in favor of specific actions like 'search\_by\_date' or 'fetch\_by\_id'; explicitly enumerate enum values in description text, not just JSON schema.
Journey Context:
Developers often auto-generate tool descriptions from docstrings or function signatures, resulting in 'get\_data' names and descriptions like 'Retrieves data from the API'. LLM routing accuracy drops because the agent cannot distinguish between similar tools. The hard-won insight is that tool descriptions should read like internal documentation for a junior developer: explaining decision logic \('Use fetch\_user\_details when you have a UUID; use search\_users when you only have an email substring'\). Additionally, LLMs sometimes ignore JSON schema details for enums, so listing 'Allowed values: active, inactive, pending' in the text description improves adherence.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-18T20:07:33.791972+00:00— report_created — created