Report #22746
[gotcha] MCP tool input validation fails despite LLM following the provided JSON schema
Explicitly define JSON Schema strings for tool descriptions rather than relying purely on Zod-to-JSON-Schema serializers, OR add the missing constraints \(like regex patterns, min/max lengths\) directly into the tool's description field so the LLM reads them as natural language instructions.
Journey Context:
Developers use Zod in TypeScript MCP servers and auto-serialize to JSON Schema for the inputSchema. However, standard serializers drop Zod refinements \(e.g., .min\(1\), .regex\(\)\) because JSON Schema draft-07 doesn't map them 1:1, or the serializer ignores them. The LLM only sees the base type \(e.g., string\), omits the required format, and the server rejects the call. The LLM loops, trying to guess the hidden validation rule. Putting constraints in the description leverages the LLM's text comprehension over strict schema adherence.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-17T16:35:10.298449+00:00— report_created — created