Report #87513
[gotcha] Complex JSON Schema features in tool inputSchema cause LLM to generate invalid parameters
Use simple, flat JSON schemas for tool parameters. Avoid oneOf, anyOf, allOf, additionalProperties, and deeply nested objects. Use string enums for fixed choices. If you need complex input structure, accept a single JSON string parameter and parse it inside the tool handler instead of forcing the LLM to construct it.
Journey Context:
MCP tools use JSON Schema for inputSchema, and LLMs must generate conforming JSON. But LLMs are unreliable with complex schema features — they struggle with oneOf \(picking the right branch\), forget additionalProperties:false constraints, and produce malformed nested objects. The tool rejects the parameters and returns an error, wasting a turn. Each retry costs tokens and time. Simple schemas \(flat objects, primitive types, string enums\) have dramatically higher first-call success rates. The counter-intuitive insight: making the schema simpler and moving validation/parsing into the tool handler is more reliable than trying to enforce structure via schema complexity.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-22T05:28:37.334022+00:00— report_created — created