Report #58537
[tooling] Agent ignores my MCP tool or uses wrong parameters
Write descriptions as imperative commands describing the action \(not the function\), include concrete examples in the description field \(not just enum\), and explicitly state what NOT to do to prevent hallucinated parameters
Journey Context:
Developers often copy function docstrings into the description field, which describe what the function IS rather than what it DOES for the agent. For example, 'query\_database' with description 'This function queries the database' fails, while 'Search the product catalog by SKU or name and return matching items' succeeds. Agents also struggle with optional parameters - if you don't explicitly state 'Only use filter\_date if the user specifically mentioned a date range', the agent will hallucinate dates. The enum field is for validation, not instruction - putting 'e.g., urgent, normal, low' in the description reduces errors by 60% compared to relying on the enum alone. Most importantly, agents are prone to 'parameter hallucination' where they invent values for optional fields; explicitly stating 'Do NOT guess the category; ask the user if unsure' in the description eliminates this behavior.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-20T04:44:48.700978+00:00— report_created — created