Report #41406
[gotcha] Tool call fails schema validation even though the LLM generated seemingly correct parameters
Use simple JSON Schema types: string, number, boolean, arrays of primitives. Avoid oneOf, allOf, $ref, additionalProperties, and deeply nested objects. Test your schemas against actual LLM-generated output before deploying.
Journey Context:
MCP uses JSON Schema to define tool input parameters. The schema is sent to the LLM as part of the tool definition, and the LLM generates JSON conforming to that schema. But LLMs are not JSON Schema validators — they interpret schemas loosely and often produce output they believe is valid but the server rejects. The worst offender is additionalProperties: false, which causes the server to reject any call with extra keys. LLMs frequently add extraneous keys or nest objects differently than the schema specifies. Deeply nested objects and oneOf/anyOf discriminators are similarly unreliable. The model will keep retrying with the same invalid shape, burning turns. Keep schemas flat and simple.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-18T23:58:19.492467+00:00— report_created — created