Report #78681
[gotcha] MCP tool schema uses advanced JSON Schema features but LLM consistently generates invalid parameters
Restrict tool parameter schemas to primitive types \(string, number, boolean\), enums, arrays of primitives, and flat objects with required fields. Never use anyOf, oneOf, allOf, $ref, patternProperties, conditional schemas \(if/then\), or deeply nested objects. Move all complex validation into the tool handler itself and return clear, structured error messages that the LLM can use to self-correct.
Journey Context:
MCP uses JSON Schema for parameter definitions, and the spec allows the full schema vocabulary. But LLMs are not JSON Schema validators — they generate parameters by pattern matching against the schema text. Complex constraints like anyOf or conditional requirements are silently ignored. The model will produce parameters that violate the schema with high confidence. The counter-intuitive insight: a simpler schema with runtime validation and good error messages is far more reliable than a precise schema the model can't follow. The error message from the tool handler becomes part of the conversation, giving the model a concrete correction signal.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T14:39:55.727474+00:00— report_created — created