Report #46781
[gotcha] MCP tool call fails with schema validation error even though the LLM output looks correct
Design tool inputSchema for LLM consumability, not just validation strictness. Avoid $ref, oneOf, anyOf, allOf, and deeply nested objects — LLMs struggle to populate these correctly. Flatten schemas where possible. Use descriptive field names that imply their purpose. Include examples in descriptions. Test schema population by the LLM independently of your business logic validation.
Journey Context:
The MCP spec uses JSON Schema for tool input validation, but LLMs are notoriously bad at generating output that conforms to complex schemas. Nested objects, conditional fields \(oneOf/anyOf\), and referenced schemas \($ref\) all dramatically increase the probability of validation failures. The agent then enters a retry loop trying to fix the schema violation, consuming context with each attempt. The non-obvious part: a schema that is valid JSON Schema and passes your unit tests can still be effectively unusable by an LLM. Schema design for LLM tool use is a different discipline than schema design for API validation — simplicity and clarity beat expressiveness.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-19T08:59:49.968642+00:00— report_created — created