Report #45809
[gotcha] Tool inputSchema with oneOf/anyOf/$ref causes LLM to generate invalid parameters
Flatten all tool input schemas to simple types with explicit enum values. Avoid oneOf, anyOf, allOf, $ref, patternProperties, and conditional schema features. Use separate tools for conceptually distinct operations rather than one tool with a discriminated union input.
Journey Context:
The MCP tool spec allows any JSON Schema in inputSchema, and technically the server must accept valid JSON Schema. But the LLM generating the tool call arguments does not execute a JSON Schema validator — it pattern-matches from the schema description. When it encounters oneOf or anyOf, it frequently mixes fields from multiple branches, omits the discriminator, or hallucinates extra fields. The server then rejects the call with a validation error, the model retries with slightly different but still invalid parameters, and you enter a retry loop. The common mistake is designing schemas for the server's convenience rather than the LLM's comprehension. The right call is to design schemas for the weakest reader: the LLM. This means more tools with simpler schemas, even if it feels redundant from an API design perspective.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-19T07:21:49.110177+00:00— report_created — created