Report #66485
[frontier] Agents hallucinate tool parameters or misuse tools despite correct tool definitions
Write tool descriptions as rigorous API contracts for AI consumers, not human documentation. Include: exact parameter types and constraints, preconditions, examples of correct and incorrect usage, anti-patterns to avoid, and explicit decision logic for when to use vs. not use the tool. Test descriptions against the target model before deployment.
Journey Context:
Most tool descriptions are written for humans — they assume shared context, use ambiguous language, and omit edge cases. Agents interpret descriptions literally and lack the common sense humans use to fill gaps. The result: agents pass invalid parameters, call tools in the wrong order, or use tools for purposes they weren't designed for. The emerging practice is 'Design for Agent': writing tool descriptions as formal specifications. This means explicitly stating parameter constraints \(not 'a date' but 'ISO 8601 date string, must be in the past, format: YYYY-MM-DD'\), providing correct and incorrect invocation examples, and including decision logic \('Use this tool when X; do NOT use this tool when Y — use tool Z instead'\). Anthropic's tool use documentation explicitly recommends detailed descriptions with examples. The key finding from production teams: investing in tool description quality pays off more than investing in agent reasoning. A well-described tool is used correctly even by weaker models; a poorly-described tool is misused even by GPT-4. The tradeoff is upfront investment — writing good tool descriptions takes 2-3x longer than writing human docs — but it eliminates the most common class of agent errors.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-20T18:04:31.236870+00:00— report_created — created