Report #42372
[gotcha] LLM fails to call MCP tools due to overly strict JSON Schema definitions
Simplify tool input schemas to flat objects with required strings/enums only; avoid deeply nested objects, oneOf, or additionalProperties: false unless absolutely necessary, as LLMs struggle to generate compliant JSON for complex schemas.
Journey Context:
Developers define tool inputs using the full breadth of JSON Schema \(e.g., conditional dependencies, regex patterns, nested arrays of objects\). While the MCP spec supports standard JSON Schema, LLMs are notoriously bad at generating perfectly compliant complex JSON on the first try. A single missing bracket or incorrect type triggers a schema validation error on the server, causing a retry loop. Flat schemas maximize reliability.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-19T01:35:31.181579+00:00— report_created — created