fix(core-internal): address review findings on zod conversion options

- Keep user annotations (.describe()/.meta()) on rewritten z.date()
  fields: under unrepresentable: 'any' the node carries only annotation
  keywords, so the previous wipe loop deleted exactly the user's
  metadata and nothing else.
- Key the output required-filter on the zod shape instead of the
  emitted default keyword: a registered .default() hides its default
  behind a $ref (and stayed required), a .meta({default}) annotation on
  a genuinely-required field was wrongly dropped, and undefined-
  accepting fields (z.any(), z.unknown(), z.undefined()) stayed
  required even though JSON.stringify drops undefined-valued keys from
  the wire. A field is now dropped from required iff validating
  undefined succeeds (missing key semantics).
- Opt the elicitation path out of the graceful-degradation options via
  a new unrepresentable: 'throw' conversion option: a z.date()
  rewritten to string/date-time would pass the wire checks, but the
  accepted response could never satisfy z.date() on handler re-entry,
  so acceptedContent() would silently discard the user's answer.
  z.date() keeps throwing the documented TypeError before anything is
  sent.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: claude

packages/core-internal/src/shared/elicitation.ts

@@ -28,7 +28,12 @@ function isJsonObject(value: unknown): value is Record<string, unknown> {
 
 function convertStandardElicitationSchema(schema: StandardSchemaWithJSON): Record<string, unknown> {
     try {
-        return standardSchemaToJsonSchema(schema, 'input');
+        // `unrepresentable: 'throw'`: the restricted form grammar must reject shapes it
+        // cannot round-trip. A `z.date()` rewritten to `string`/`date-time` would pass the
+        // wire checks, but the accepted response (a JSON string) could never satisfy the
+        // same `z.date()` schema on handler re-entry — keep the documented loud failure
+        // (`z.iso.date()`/`z.iso.datetime()` are the supported ways to elicit dates).
+        return standardSchemaToJsonSchema(schema, 'input', { unrepresentable: 'throw' });
     } catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
         throw new ProtocolError(

packages/core-internal/src/util/standardSchema.ts

@@ -194,7 +194,8 @@ function zodConversionOptions(io: 'input' | 'output'): Pick<z.core.ToJSONSchemaP
         override: ctx => {
             const def = ctx.zodSchema._zod.def;
             if (def.type === 'date') {
-                for (const key of Object.keys(ctx.jsonSchema)) delete ctx.jsonSchema[key];
+                // Under `unrepresentable: 'any'` the node carries only user annotations
+                // (`.describe()` / `.meta()`) — keep them and stamp the wire shape beside them.
                 ctx.jsonSchema.type = 'string';
                 ctx.jsonSchema.format = 'date-time';
                 return;
@@ -204,13 +205,13 @@ function zodConversionOptions(io: 'input' | 'output'): Pick<z.core.ToJSONSchemaP
             if (!isStrict && ctx.jsonSchema.additionalProperties === false) {
                 delete ctx.jsonSchema.additionalProperties;
             }
-            const properties = ctx.jsonSchema.properties;
             const required = ctx.jsonSchema.required;
-            if (properties && Array.isArray(required)) {
-                const filtered = required.filter(name => {
-                    const property = properties[name];
-                    return typeof property !== 'object' || property.default === undefined;
-                });
+            if (Array.isArray(required)) {
+                // Keyed on the zod shape, not the emitted JSON: a registered `.default()`
+                // hides its `default` keyword behind a `$ref`, and undefined-accepting
+                // fields (`z.any()`, `z.unknown()`, …) never emit one yet may be dropped
+                // from the wire payload by JSON.stringify.
+                const filtered = required.filter(name => !fieldAcceptsMissingKey(def.shape[name]));
                 if (filtered.length !== required.length) {
                     if (filtered.length === 0) delete ctx.jsonSchema.required;
                     else ctx.jsonSchema.required = filtered;
@@ -220,6 +221,19 @@ function zodConversionOptions(io: 'input' | 'output'): Pick<z.core.ToJSONSchemaP
     };
 }
 
+/**
+ * Whether a raw payload that omits this field still passes validation (zod treats a
+ * missing key as `undefined` — true for `.default()`/`.prefault()`, `z.any()`,
+ * `z.unknown()`, `z.undefined()`, and unions with them), so the wire schema must not
+ * advertise the field as `required`. Async validation cannot be awaited here; such
+ * fields conservatively stay required.
+ */
+function fieldAcceptsMissingKey(field: z.core.$ZodType | undefined): boolean {
+    if (field === undefined) return false;
+    const result = field['~standard'].validate(undefined);
+    return !(result instanceof Promise) && result.issues === undefined;
+}
+
 /**
  * Converts a StandardSchema to JSON Schema for use as an MCP tool/prompt schema.
  *
@@ -231,14 +245,36 @@ function zodConversionOptions(io: 'input' | 'output'): Pick<z.core.ToJSONSchemaP
  * `io: 'output'` a non-object root is returned as-is; the `"object"` default is
  * applied only when the root is provably object-shaped.
  */
-export function standardSchemaToJsonSchema(schema: StandardJSONSchemaV1, io: 'input' | 'output' = 'input'): Record<string, unknown> {
+export interface StandardSchemaToJsonSchemaOptions {
+    /**
+     * How types JSON Schema cannot represent (`z.date()`, `z.bigint()`, …) are handled
+     * for zod schemas:
+     *
+     * - `'wire'` (default) — degrade gracefully: `z.date()` becomes
+     *   `{type: 'string', format: 'date-time'}` (the shape `JSON.stringify` puts on the
+     *   wire for a `Date`) and other unrepresentable types become an unconstrained
+     *   schema, so one field cannot fail an entire `tools/list` response (#2464).
+     * - `'throw'` — surface zod's conversion error. The elicitation path uses this: its
+     *   restricted form grammar must reject shapes it cannot round-trip, and a silently
+     *   rewritten `string`/`date-time` request would elicit a string that the original
+     *   `z.date()` schema can never re-validate on handler re-entry.
+     */
+    unrepresentable?: 'wire' | 'throw';
+}
+
+export function standardSchemaToJsonSchema(
+    schema: StandardJSONSchemaV1,
+    io: 'input' | 'output' = 'input',
+    options?: StandardSchemaToJsonSchemaOptions
+): Record<string, unknown> {
     const std = schema['~standard'];
+    const zodOptions = options?.unrepresentable === 'throw' ? undefined : zodConversionOptions(io);
     let result: Record<string, unknown>;
     if (std.jsonSchema) {
         result = std.jsonSchema[io]({
             target: JSON_SCHEMA_CONVERSION_TARGET,
             // Non-zod vendors receive no libraryOptions, so their behavior is unchanged.
-            libraryOptions: std.vendor === 'zod' ? zodConversionOptions(io) : undefined
+            libraryOptions: std.vendor === 'zod' ? zodOptions : undefined
         });
     } else if (std.vendor === 'zod') {
         // zod 4.0–4.1 implements StandardSchemaV1 but not StandardJSONSchemaV1 (`~standard.jsonSchema`).
@@ -261,7 +297,7 @@ export function standardSchemaToJsonSchema(schema: StandardJSONSchemaV1, io: 'in
         result = z.toJSONSchema(schema as unknown as z.ZodType, {
             target: JSON_SCHEMA_CONVERSION_TARGET,
             io,
-            ...zodConversionOptions(io)
+            ...zodOptions
         }) as Record<string, unknown>;
     } else {
         throw new Error(

packages/core-internal/test/shared/inputRequired.test.ts

@@ -160,6 +160,18 @@ describe('inputRequired() builder', () => {
                 requestedSchema: z.object({ role: z.union([z.literal('admin'), z.literal('member')]) })
             })
         ).toThrow(TypeError);
+
+        // z.date() must keep failing loudly even though the tools-path conversion rewrites
+        // it to string/date-time (#2464): the accepted response (a JSON string) could never
+        // satisfy z.date() on handler re-entry, so acceptedContent() would silently return
+        // undefined. z.iso.date()/z.iso.datetime() are the supported ways to elicit dates.
+        const rejectDate = () =>
+            inputRequired.elicit({
+                message: 'When?',
+                requestedSchema: z.object({ when: z.date() })
+            });
+        expect(rejectDate).toThrow(TypeError);
+        expect(rejectDate).toThrow(/Date cannot be represented/);
     });
 
     test.each([

packages/core-internal/test/util/standardSchema.test.ts

@@ -60,6 +60,22 @@ describe('zod conversion options (#2464)', () => {
         expect((result.properties as Record<string, unknown>).big).toEqual({});
     });
 
+    test('z.date() keeps user annotations alongside the rewritten wire shape', () => {
+        const result = standardSchemaToJsonSchema(z.object({ when: z.date().describe('event timestamp') }), 'input');
+
+        expect((result.properties as Record<string, unknown>).when).toEqual({
+            type: 'string',
+            format: 'date-time',
+            description: 'event timestamp'
+        });
+    });
+
+    test("unrepresentable: 'throw' restores zod's conversion error (elicitation contract)", () => {
+        expect(() => standardSchemaToJsonSchema(z.object({ when: z.date() }), 'input', { unrepresentable: 'throw' })).toThrow(
+            /Date cannot be represented/
+        );
+    });
+
     test('defaulted fields are not advertised as required in output schemas', () => {
         const schema = z.object({ counted: z.number().default(0), name: z.string() });
         const result = standardSchemaToJsonSchema(schema, 'output');
@@ -69,6 +85,34 @@ describe('zod conversion options (#2464)', () => {
         expect(result.required).toEqual(['name']);
     });
 
+    test('a registered .default() (emitted as $ref) is still dropped from output required', () => {
+        const schema = z.object({ counted: z.number().default(0).meta({ id: 'StandardSchemaTestCounted' }), name: z.string() });
+        const result = standardSchemaToJsonSchema(schema, 'output');
+
+        // The `default` keyword hides inside $defs behind a bare $ref; the filter must
+        // key on the zod shape, not the emitted JSON.
+        expect((result.properties as Record<string, Record<string, unknown>>).counted?.$ref).toBeDefined();
+        expect(result.required).toEqual(['name']);
+    });
+
+    test('a required field annotated with .meta({default}) stays required in output schemas', () => {
+        const schema = z.object({ label: z.string().meta({ default: 'n/a' }), other: z.number() });
+        const result = standardSchemaToJsonSchema(schema, 'output');
+
+        // The annotation carries a `default` keyword, but validation still requires the
+        // field, so every shipped payload carries it.
+        expect(result.required).toEqual(['label', 'other']);
+    });
+
+    test('undefined-accepting fields are not advertised as required in output schemas', () => {
+        const schema = z.object({ a: z.any(), u: z.unknown(), v: z.undefined(), name: z.string() });
+        const result = standardSchemaToJsonSchema(schema, 'output');
+
+        // A raw payload with an undefined-valued key passes validation, and
+        // JSON.stringify drops the key from the wire entirely.
+        expect(result.required).toEqual(['name']);
+    });
+
     test('plain z.object() output schemas do not advertise additionalProperties:false', () => {
         const result = standardSchemaToJsonSchema(z.object({ name: z.string() }), 'output');