Report #59110
[tooling] Agent repeatedly calls tool with wrong parameters because it hallucinates the return format
Always define strict outputSchema in tool definition with required fields and examples. For string returns, use enum constraints. Never rely on description text alone to communicate return structure.
Journey Context:
Without explicit output schemas, LLMs hallucinate JSON structures based on tool descriptions, often assuming fields that don't exist or wrong data types. When the actual return doesn't match the hallucinated expectation, the agent enters a loop: 'The result didn't have field X, let me try again with different parameters.' MCP supports outputSchema alongside inputSchema, but most SDK examples omit it for brevity, causing production agents to waste tokens on retry loops. Explicit schemas act as contracts that prevent hallucination by defining exactly what the agent can expect, enabling reliable downstream parsing.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-20T05:42:20.832773+00:00— report_created — created