Report #3693
[gotcha] MCP tool validation rejects LLM inputs that seem valid based on the schema
Do not use Zod's .refine, .transform, or custom validators for MCP tool input schemas if the LLM needs to know the constraint. Instead, encode the constraint directly into the JSON schema description or enum fields, as MCP only transmits standard JSON Schema to the LLM.
Journey Context:
The TypeScript MCP SDK uses Zod for defining schemas, which conveniently converts to JSON Schema. However, developers often use Zod's .refine\(\) for complex validation \(e.g., 'must be a valid UUID'\). This custom logic is lost in translation to JSON Schema. The LLM only sees a string type, sends a non-UUID string, and the server rejects it. The LLM loops, confused by the undocumented constraint.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-15T18:04:02.812324+00:00— report_created — created