[v2] Unnecessary zod schema conversion #3132

Activity

1. phawxby

   added

   v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixesIdeas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

   on Oct 30, 2026
2. media-ctrl commented on Nov 3, 2026

   

   media-ctrl

   on Nov 3, 2026

   More actions

   I measured the mechanism on zod 4.6.7, the version you linked, and one detail both explains why this is easy to miss and prescribes the fix.

   toJSONSchema() attaches ~standard as an own property that is NOT enumerable. So Object.keys(schema) does not show it, hasOwnProperty('~standard') returns true, and neither object spread nor destructuring carries it across.

   Two consequences follow.

   For the SDK: any "is this already JSON Schema?" predicate written against enumerable keys can never see the marker, which is likely how a pre-converted object ends up being treated as a Zod schema again. A correct predicate has to test with '~standard' in schema or hasOwnProperty, not by inspecting keys.

   For a workaround today: JSON.parse(JSON.stringify(schema)) strips it, because stringify serialises only enumerable properties. The SDK then receives plain JSON Schema and skips the converter. I verified the marker is gone after the round-trip. The cost is one deep clone per schema at registration, so at your 1000-tool scale that is 1000 clones rather than 1000 converter invocations. That should be cheaper, though it is worth measuring on your repro rather than trusting the estimate.

   On whether this belongs in the SDK or in zod: the non-enumerability is an argument for zod. If the JSON Schema output carried no marker at all, no consumer would need to know it exists, and every consumer that spreads the object or enumerates its keys would stop being subtly wrong without knowing it was. A ~standard-aware predicate in registerTool is still worth having as a guard, since other converters attach similar metadata, but it fixes this one caller rather than the class.

   One adjacent effect worth benchmarking while you are in there: the conversion is per registerTool call, so the 1000-tool loop pays it at registration, and whatever toolInputSchemaJson caches may still be recomputed on list. If both paths convert, the clone workaround helps registration only.
3. SalyyS1 commented on Nov 12, 2026

   

   SalyyS1

   on Nov 12, 2026

   More actions

   One subtlety if the SDK distinguishes raw Zod v4 schemas from pre-converted z.toJSONSchema() objects:

   In Zod v4, both z.object({}) and z.object({}).toJSONSchema() have schema.type === "object" and '~standard' in schema === true! So checking 'type' in schema && schema.type === 'object' is not sufficient on its own to tell a plain JSON Schema apart from a Zod v4 schema instance.

   Instead, you can distinguish them reliably by checking for Zod's internal marker ('_zod' in schema or '_def' in schema) or checking whether '~standard' is only a non-enumerable own property attached to a plain JSON Schema object (Object.getPrototypeOf(schema) === Object.prototype && !('_zod' in schema)):

   function isAlreadyJsonSchema(schema: unknown): boolean {
     return (
       typeof schema === 'object' &&
       schema !== null &&
       Object.getPrototypeOf(schema) === Object.prototype &&
       !('_zod' in schema) &&
       !('_def' in schema) &&
       ('$schema' in schema || 'properties' in schema || 'type' in schema)
     );
   }

   As a zero-cost workaround for callers on v2.3.0 today, shallow-spreading the result (registerTool(name, { inputSchema: { ...z.object({}).toJSONSchema() } }, cb)) drops the non-enumerable ~standard property in O(1) so the SDK skips re-conversion.

   (Also worth noting for z.toJSONSchema() users: Zod v4's JSON Schema output includes "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, and #/$defs/... pointers on every tool. If you are exposing a large tool catalog to LLM clients, running mcp-slim in front of the server strips redundant $schema/title metadata and inlines $defs/$ref pointers, cutting tools/list token size by ~49%.)
4. PromptShield21 commented on Nov 14, 2026

   

   PromptShield21

   on Nov 14, 2026

   More actions

   A use case and numbers for this, from a server with 130 tools (SDK 1.32.2 today, zod 4.6.7).

   z.uuid() lists as "format": "uuid" plus a 190-byte pattern. In our tools/list answer that pattern appears 85 times. Removing it from the listing takes the answer from 103,656 to 88,441 bytes (14.7%). Validation does not change, because the server still parses arguments with the original Zod schema.

   Zod already has the switch for this:

   z.toJSONSchema(schema, {
     override: ctx => { if (ctx.jsonSchema.format === 'uuid') delete ctx.jsonSchema.pattern; },
   });

   The SDK calls toJSONSchema with fixed options (target, io), so a server cannot pass override or reused. That leaves two routes:

   1. Convert the schema ourselves with those options and pass the result to registerTool. That is the path this issue is about: it only pays off once a pre-converted schema is used as given and not converted again.
   2. An option on the server or on registerTool that is passed through to the conversion, for example jsonSchema: { override, reused }.

   Either one would let us drop a workaround. On v1 we wrap the tools/list handler that McpServer.setToolRequestHandlers registers and post-process each inputSchema, which depends on where the SDK registers that handler.

   So +1 for fixing the re-conversion, and if route 2 is of interest I can open a separate issue for it.