openai 7.4.0 → 7.6.0

package/src/helpers/standard-schema.ts

@@ -1,14 +1,14 @@
 import { OpenAIError } from '../error';
+import type { AutoParseableResponseFormat, AutoParseableTextFormat, AutoParseableTool } from '../lib/parser';
 import {
-  AutoParseableResponseFormat,
-  AutoParseableTextFormat,
-  AutoParseableTool,
   makeParseableResponseFormat,
   makeParseableTextFormat,
   makeParseableTool,
+  parseResponseFormatContent,
 } from '../lib/parser';
-import { AutoParseableResponseTool, makeParseableResponseTool } from '../lib/ResponsesParser';
-import { type JSONSchema } from '../lib/jsonschema';
+import type { AutoParseableResponseTool } from '../lib/ResponsesParser';
+import { makeParseableResponseTool } from '../lib/ResponsesParser';
+import type { JSONSchema } from '../lib/jsonschema';
 import {
   assertNoNestedSchemaIds,
   forEachJSONSchemaChild,
@@ -18,55 +18,104 @@ import {
   rewriteLocalRefsIntoMovedOneOfBranches,
   toStrictJsonSchema,
 } from '../lib/transform';
-import { ResponseFormatJSONSchema } from '../resources/index';
-import { type ResponseFormatTextJSONSchemaConfig } from '../resources/responses/responses';
+import type { ResponseFormatJSONSchema } from '../resources/index';
+import type { ResponseFormatTextJSONSchemaConfig } from '../resources/responses/responses';
 
+/** Validation issue returned by a Standard Schema-compatible validator. */
 type StandardSchemaIssue = {
+  /** Human-readable explanation of the validation failure. */
   readonly message: string;
-  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined;
+
+  /** Optional path identifying the input property or array element that failed validation. */
+  readonly path?:
+    | readonly (
+        | PropertyKey
+        | {
+            /** Property name, symbol, or array index associated with this path segment. */
+            readonly key: PropertyKey;
+          }
+      )[]
+    | undefined;
 };
 
+/** Successful parsed output or validation issues produced by a Standard Schema validator. */
 type StandardSchemaResult<Output> =
   | {
+      /** Parsed and validated value returned by a successful validation. */
       readonly value: Output;
+
+      /** Validation issues are absent when parsing succeeds. */
       readonly issues?: undefined;
     }
   | {
-      readonly issues: ReadonlyArray<StandardSchemaIssue>;
+      /** Validation issues describing why the input could not be parsed. */
+      readonly issues: readonly StandardSchemaIssue[];
     };
 
+/** JSON Schema conversion settings passed to a Standard Schema implementation. */
 type StandardJSONSchemaOptions = {
+  /** JSON Schema dialect required by the SDK's structured-output helpers. */
   readonly target: 'draft-07';
+
+  /** Optional validator-specific JSON Schema conversion settings. */
   readonly libraryOptions?: Record<string, unknown> | undefined;
 };
 
+/** Minimal Standard Schema v1 validator contract accepted by the public parsing helpers. */
 type StandardSchemaLike<Input = unknown, Output = Input> = {
+  /** Standard Schema metadata, validation entrypoint, and optional JSON Schema conversion. */
   readonly '~standard': {
+    /** Standard Schema specification version supported by the validator. */
     readonly version: 1;
+
+    /** Identifier of the library that implements this Standard Schema validator. */
     readonly vendor: string;
+
+    /** Optional type-level input and output metadata used to infer parsed result types. */
     readonly types?:
       | {
+          /** Type accepted by the validator before parsing or transformation. */
           readonly input: Input;
+
+          /** Type produced after successful validation or transformation. */
           readonly output: Output;
         }
       | undefined;
+
+    /**
+     * Validates model output; SDK parsing helpers require this method to finish synchronously.
+     * Promise-returning validators are rejected when a response is parsed.
+     */
     readonly validate: (
       value: unknown,
     ) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+
+    /** Optional JSON Schema conversion methods; provide an explicit `schema` when absent. */
     readonly jsonSchema?:
       | {
+          /** Produces the model-facing input JSON Schema for the requested dialect. */
           readonly input: (options: StandardJSONSchemaOptions) => Record<string, unknown>;
+
+          /** Produces an optional output JSON Schema; structured-output helpers use `input` instead. */
           readonly output?: (options: StandardJSONSchemaOptions) => Record<string, unknown>;
         }
       | undefined;
   };
 };
 
-type InferStandardOutput<Schema extends StandardSchemaLike> =
-  [NonNullable<Schema['~standard']['types']>] extends [never] ? unknown
-  : NonNullable<Schema['~standard']['types']> extends { readonly output: infer Output } ? Output
-  : unknown;
+/** Extracts parsed Standard Schema output, falling back to `unknown` without type metadata. */
+type InferStandardOutput<Schema extends StandardSchemaLike> = [
+  NonNullable<Schema['~standard']['types']>,
+] extends [never]
+  ? unknown
+  : NonNullable<Schema['~standard']['types']> extends {
+        /** Parsed output type declared by the Standard Schema validator's type metadata. */
+        readonly output: infer Output;
+      }
+    ? Output
+    : unknown;
 
+/** Supplies a model-facing JSON Schema when a validator cannot generate one itself. */
 type StandardSchemaJSONSchemaProps = {
   /**
    * A JSON Schema override for Standard Schema implementations that do not
@@ -75,45 +124,62 @@ type StandardSchemaJSONSchemaProps = {
   schema?: JSONSchema | Record<string, unknown> | undefined;
 };
 
+/** Optional Chat Completions response-format metadata and explicit JSON Schema override. */
 type StandardResponseFormatProps = Omit<ResponseFormatJSONSchema.JSONSchema, 'schema' | 'strict' | 'name'> &
   StandardSchemaJSONSchemaProps;
 
+/** Optional Responses API text-format metadata and explicit JSON Schema override. */
 type StandardTextFormatProps = Omit<
   ResponseFormatTextJSONSchemaConfig,
   'schema' | 'type' | 'strict' | 'name'
 > &
   StandardSchemaJSONSchemaProps;
 
+/** Function callback invoked with arguments validated by a Standard Schema implementation. */
 type StandardToolFunction<Parameters extends StandardSchemaLike> = (
   args: InferStandardOutput<Parameters>,
 ) => unknown | Promise<unknown>;
 
+/** Model-facing function-tool settings and optional Standard Schema validation callback. */
 type StandardToolOptions<Parameters extends StandardSchemaLike> = {
+  /** Model-visible function name used to identify matching tool calls. */
   name: string;
+
+  /** Standard Schema validator used to describe and validate the function's arguments. */
   parameters: Parameters;
   /**
    * A JSON Schema override for Standard Schema implementations that do not
    * expose `~standard.jsonSchema.input()`.
    */
   schema?: JSONSchema | Record<string, unknown> | undefined;
+
+  /** Optional callback retained on the tool and invoked by compatible chat `runTools()` helpers. */
   function?: StandardToolFunction<Parameters> | undefined;
+
+  /** Optional model-visible explanation of when and how the function should be used. */
   description?: string | undefined;
 };
 
+/** Type-level function-tool metadata preserving validated arguments and callback availability. */
 type StandardToolReturnOptions<
   Parameters extends StandardSchemaLike,
-  Function extends StandardToolFunction<Parameters> | undefined,
+  ToolFunction extends StandardToolFunction<Parameters> | undefined,
 > = {
+  /** Inferred argument type returned by the Standard Schema validator. */
   arguments: InferStandardOutput<Parameters>;
+
+  /** Model-visible name used to match generated function calls. */
   name: string;
-  function: Function;
+
+  /** Callback type when supplied, or `undefined` for a parse-only function tool. */
+  function: ToolFunction;
 };
 
 function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
   return typeof value === 'object' && value !== null && 'then' in value && typeof value.then === 'function';
 }
 
-function formatStandardSchemaIssues(issues: ReadonlyArray<StandardSchemaIssue>): string {
+function formatStandardSchemaIssues(issues: readonly StandardSchemaIssue[]): string {
   return issues
     .map((issue) => {
       const path = issue.path
@@ -132,7 +198,9 @@ const JSON_SCHEMA_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'ob
 type JSONPrimitive = string | number | boolean | null;
 
 function getSchemaTypes(schema: unknown): Set<string> | undefined {
-  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return undefined;
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    return undefined;
+  }
 
   const type = (schema as Record<string, unknown>)['type'];
   if (type === undefined) {
@@ -159,7 +227,9 @@ function isJSONPrimitive(value: unknown): value is JSONPrimitive {
 }
 
 function getLiteralValues(schema: unknown): JSONPrimitive[] | undefined {
-  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return undefined;
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    return undefined;
+  }
 
   const record = schema as Record<string, unknown>;
   if ('const' in record && isJSONPrimitive(record['const'])) {
@@ -176,11 +246,15 @@ function getLiteralValues(schema: unknown): JSONPrimitive[] | undefined {
 
 function getLiteralSchemaTypes(schema: unknown): Set<string> | undefined {
   const literalValues = getLiteralValues(schema);
-  if (!literalValues) return undefined;
+  if (!literalValues) {
+    return undefined;
+  }
 
   return new Set(
     literalValues.map((value) => {
-      if (value === null) return 'null';
+      if (value === null) {
+        return 'null';
+      }
       return typeof value;
     }),
   );
@@ -189,7 +263,9 @@ function getLiteralSchemaTypes(schema: unknown): Set<string> | undefined {
 function haveDisjointLiteralValues(left: unknown, right: unknown): boolean {
   const leftValues = getLiteralValues(left);
   const rightValues = getLiteralValues(right);
-  if (!leftValues || !rightValues) return false;
+  if (!leftValues || !rightValues) {
+    return false;
+  }
 
   return leftValues.every((leftValue) => !rightValues.some((rightValue) => leftValue === rightValue));
 }
@@ -206,7 +282,9 @@ function isObjectOnlySchema(schema: unknown): boolean {
 }
 
 function haveDisjointObjectDiscriminator(left: unknown, right: unknown, root: JSONSchema): boolean {
-  if (!isObjectOnlySchema(left) || !isObjectOnlySchema(right)) return false;
+  if (!isObjectOnlySchema(left) || !isObjectOnlySchema(right)) {
+    return false;
+  }
 
   const leftRecord = left as Record<string, unknown>;
   const rightRecord = right as Record<string, unknown>;
@@ -246,7 +324,9 @@ function haveDisjointObjectDiscriminator(left: unknown, right: unknown, root: JS
 function getClosedObjectPropertySet(
   schema: unknown,
 ): { properties: Set<string>; required: string[] } | undefined {
-  if (!isObjectOnlySchema(schema)) return undefined;
+  if (!isObjectOnlySchema(schema)) {
+    return undefined;
+  }
 
   const record = schema as Record<string, unknown>;
   const properties = record['properties'];
@@ -277,7 +357,9 @@ function getClosedObjectPropertySet(
 function haveDisjointClosedObjectPropertySets(left: unknown, right: unknown): boolean {
   const leftShape = getClosedObjectPropertySet(left);
   const rightShape = getClosedObjectPropertySet(right);
-  if (!leftShape || !rightShape) return false;
+  if (!leftShape || !rightShape) {
+    return false;
+  }
 
   // If either closed branch requires a property the other branch does not
   // declare, every instance satisfying the first is rejected by the second as
@@ -312,9 +394,11 @@ function areMutuallyExclusive(left: unknown, right: unknown, root: JSONSchema):
 function resolveLocalRefForExclusivity(
   schema: unknown,
   root: JSONSchema,
-  seenRefs: Set<string> = new Set(),
+  seenRefs = new Set<string>(),
 ): unknown | undefined {
-  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return schema;
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    return schema;
+  }
 
   const record = schema as Record<string, unknown>;
   const ref = record['$ref'];
@@ -325,18 +409,26 @@ function resolveLocalRefForExclusivity(
     if (typeof ref !== 'string' || !hasOnlyRefAndAnnotations(record as JSONSchema)) {
       return undefined;
     }
-    if (seenRefs.has(ref)) return undefined;
+    if (seenRefs.has(ref)) {
+      return undefined;
+    }
 
     const resolved = resolveLocalRef(root, ref);
-    if (resolved === undefined) return undefined;
+    if (resolved === undefined) {
+      return undefined;
+    }
 
     return resolveLocalRefForExclusivity(resolved, root, new Set([...seenRefs, ref]));
   }
 
   if (record['allOf'] !== undefined) {
-    if (!Array.isArray(record['allOf'])) return undefined;
+    if (!Array.isArray(record['allOf'])) {
+      return undefined;
+    }
     const normalized = normalizeObjectAllOfForExclusivity(record as JSONSchema, root);
-    if (normalized === undefined) return undefined;
+    if (normalized === undefined) {
+      return undefined;
+    }
 
     // Flattening a singleton allOf can expose a bare local ref. Feed that
     // result through this same resolver so URI-fragment decoding and the
@@ -368,9 +460,13 @@ function normalizeStructuredOutputSchema(schema: JSONSchema): JSONSchema {
   const visitedSchemas = new Set<Record<string, unknown>>();
 
   const visitSchema = (value: unknown): void => {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return;
+    }
     const record = value as Record<string, unknown>;
-    if (visitedSchemas.has(record)) return;
+    if (visitedSchemas.has(record)) {
+      return;
+    }
     visitedSchemas.add(record);
 
     if (record['oneOf'] !== undefined) {
@@ -409,11 +505,30 @@ function normalizeStructuredOutputSchema(schema: JSONSchema): JSONSchema {
   return normalizedSchema;
 }
 
+type StandardSchemaBinding<Schema extends StandardSchemaLike> = {
+  standard: Schema['~standard'];
+  validate: Schema['~standard']['validate'];
+};
+
+function bindStandardSchema<Schema extends StandardSchemaLike>(standardSchema: Schema) {
+  let binding: StandardSchemaBinding<Schema> | undefined;
+
+  return (): StandardSchemaBinding<Schema> => {
+    if (!binding) {
+      const standard = standardSchema['~standard'];
+      binding = { standard, validate: standard.validate };
+    }
+    return binding;
+  };
+}
+
 function parseStandardSchema<Schema extends StandardSchemaLike>(
-  standardSchema: Schema,
+  getBinding: () => StandardSchemaBinding<Schema>,
   content: string,
 ): InferStandardOutput<Schema> {
-  const result = standardSchema['~standard'].validate(JSON.parse(content));
+  const parsed = parseResponseFormatContent({ type: 'json_schema', $parseRaw: undefined }, content);
+  const { standard, validate } = getBinding();
+  const result = Reflect.apply(validate, standard, [parsed]);
 
   if (isPromiseLike(result)) {
     void Promise.resolve(result).catch(() => undefined);
@@ -429,11 +544,11 @@ function parseStandardSchema<Schema extends StandardSchemaLike>(
   return result.value as InferStandardOutput<Schema>;
 }
 
-function resolveStandardJSONSchema(
-  standardSchema: StandardSchemaLike,
+function resolveStandardJSONSchema<Schema extends StandardSchemaLike>(
+  getBinding: () => StandardSchemaBinding<Schema>,
   schemaOverride?: JSONSchema | Record<string, unknown> | undefined,
 ): Record<string, unknown> {
-  const schema = (schemaOverride ?? standardSchema['~standard'].jsonSchema?.input({ target: 'draft-07' })) as
+  const schema = (schemaOverride ?? getBinding().standard.jsonSchema?.input({ target: 'draft-07' })) as
     | JSONSchema
     | undefined;
 
@@ -453,6 +568,19 @@ function resolveStandardJSONSchema(
  * The helper uses `~standard.jsonSchema.input()` for the model-facing schema
  * and `~standard.validate()` for parsed output. Validation must be
  * synchronous because the SDK's parse helpers are synchronous.
+ *
+ * Pass the returned format to `client.chat.completions.parse()` to populate
+ * `message.parsed`. Supply `props.schema` when the validator does not implement
+ * `~standard.jsonSchema.input()`.
+ *
+ * @param standardSchema Standard Schema v1 validator used to describe and parse output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional response-format metadata and explicit JSON Schema override.
+ * @throws {OpenAIError} If no JSON Schema is available or its `oneOf` branches
+ * cannot be represented safely.
+ * @throws {Error} If strict normalization rejects another unsupported or
+ * unrepresentable JSON Schema feature.
+ * @throws {TypeError} If malformed JSON Schema values have unexpected structural types.
  */
 export function standardResponseFormat<Schema extends StandardSchemaLike>(
   standardSchema: Schema,
@@ -460,6 +588,7 @@ export function standardResponseFormat<Schema extends StandardSchemaLike>(
   props?: StandardResponseFormatProps,
 ): AutoParseableResponseFormat<InferStandardOutput<Schema>> {
   const { schema, ...formatProps } = props ?? {};
+  const getBinding = bindStandardSchema(standardSchema);
 
   return makeParseableResponseFormat<InferStandardOutput<Schema>>(
     {
@@ -468,16 +597,29 @@ export function standardResponseFormat<Schema extends StandardSchemaLike>(
         ...formatProps,
         name,
         strict: true,
-        schema: resolveStandardJSONSchema(standardSchema, schema),
+        schema: resolveStandardJSONSchema(getBinding, schema),
       },
     },
-    (content) => parseStandardSchema(standardSchema, content),
+    (content) => parseStandardSchema(getBinding, content),
   );
 }
 
 /**
  * Creates a Responses API `json_schema` text format from a Standard Schema
  * validator.
+ *
+ * Pass the returned format as `text.format` to `client.responses.parse()` to
+ * populate `response.output_parsed`. Validation must be synchronous. Supply
+ * `props.schema` when the validator cannot generate its own input JSON Schema.
+ *
+ * @param standardSchema Standard Schema v1 validator used to describe and parse output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional text-format metadata and explicit JSON Schema override.
+ * @throws {OpenAIError} If no JSON Schema is available or its `oneOf` branches
+ * cannot be represented safely.
+ * @throws {Error} If strict normalization rejects another unsupported or
+ * unrepresentable JSON Schema feature.
+ * @throws {TypeError} If malformed JSON Schema values have unexpected structural types.
  */
 export function standardTextFormat<Schema extends StandardSchemaLike>(
   standardSchema: Schema,
@@ -485,6 +627,7 @@ export function standardTextFormat<Schema extends StandardSchemaLike>(
   props?: StandardTextFormatProps,
 ): AutoParseableTextFormat<InferStandardOutput<Schema>> {
   const { schema, ...formatProps } = props ?? {};
+  const getBinding = bindStandardSchema(standardSchema);
 
   return makeParseableTextFormat<InferStandardOutput<Schema>>(
     {
@@ -492,79 +635,173 @@ export function standardTextFormat<Schema extends StandardSchemaLike>(
       ...formatProps,
       name,
       strict: true,
-      schema: resolveStandardJSONSchema(standardSchema, schema),
+      schema: resolveStandardJSONSchema(getBinding, schema),
     },
-    (content) => parseStandardSchema(standardSchema, content),
+    (content) => parseStandardSchema(getBinding, content),
   );
 }
 
 /**
  * Creates a chat completion `function` tool from a Standard Schema
- * validator.
+ * validator and a callback that can be invoked by `chat.completions.runTools()`.
+ *
+ * The generated tool uses strict JSON Schema, and arguments are validated
+ * synchronously before the callback receives them. Supply `options.schema`
+ * when the validator cannot generate an input JSON Schema.
+ *
+ * @param options Model-visible function details, synchronous parameter validator,
+ * optional schema override, and required execution callback.
+ * @throws {OpenAIError} If no JSON Schema is available or its `oneOf` branches
+ * cannot be represented safely.
+ * @throws {Error} If strict normalization rejects another unsupported or
+ * unrepresentable JSON Schema feature.
+ * @throws {TypeError} If malformed JSON Schema values have unexpected structural types.
  */
 export function standardFunction<
   Parameters extends StandardSchemaLike,
-  Function extends StandardToolFunction<Parameters>,
+  ToolFunction extends StandardToolFunction<Parameters>,
 >(
-  options: StandardToolOptions<Parameters> & { function: Function },
-): AutoParseableTool<StandardToolReturnOptions<Parameters, Function>>;
+  options: StandardToolOptions<Parameters> & {
+    /** Callback invoked with synchronously validated arguments by chat `runTools()`. */
+    function: ToolFunction;
+  },
+): AutoParseableTool<StandardToolReturnOptions<Parameters, ToolFunction>>;
+
+/**
+ * Creates a parse-only Chat Completions function tool without an execution callback.
+ *
+ * Arguments are validated synchronously by `chat.completions.parse()` or
+ * `.stream()`. Callback-free tools cannot be executed by `runTools()`.
+ *
+ * @throws {OpenAIError} If no JSON Schema is available or its `oneOf` branches
+ * cannot be represented safely.
+ * @throws {Error} If strict normalization rejects another unsupported or
+ * unrepresentable JSON Schema feature.
+ * @throws {TypeError} If malformed JSON Schema values have unexpected structural types.
+ */
 export function standardFunction<Parameters extends StandardSchemaLike>(
-  options: StandardToolOptions<Parameters> & { function?: undefined },
+  options: StandardToolOptions<Parameters> & {
+    /** No execution callback is attached to this parse-only function tool. */
+    function?: undefined;
+  },
 ): AutoParseableTool<StandardToolReturnOptions<Parameters, undefined>>;
+
+/**
+ * Creates a strict Chat Completions function tool with an optionally available callback.
+ * The validator must support synchronous validation and provide or receive a JSON Schema.
+ *
+ * @throws {OpenAIError} If no JSON Schema is available or its `oneOf` branches
+ * cannot be represented safely.
+ * @throws {Error} If strict normalization rejects another unsupported or
+ * unrepresentable JSON Schema feature.
+ * @throws {TypeError} If malformed JSON Schema values have unexpected structural types.
+ */
 export function standardFunction<Parameters extends StandardSchemaLike>(
   options: StandardToolOptions<Parameters>,
 ): AutoParseableTool<StandardToolReturnOptions<Parameters, StandardToolFunction<Parameters> | undefined>>;
+
+/** Builds a strict Chat Completions function tool from a synchronous Standard Schema validator. */
 export function standardFunction<Parameters extends StandardSchemaLike>(
   options: StandardToolOptions<Parameters>,
 ) {
+  const name = options.name;
+  const parameters = options.parameters;
+  const getBinding = bindStandardSchema(parameters);
+
   return makeParseableTool<any>(
     {
       type: 'function',
       function: {
-        name: options.name,
-        parameters: resolveStandardJSONSchema(options.parameters, options.schema),
+        name,
+        parameters: resolveStandardJSONSchema(getBinding, options.schema),
         strict: true,
         ...(options.description ? { description: options.description } : undefined),
       },
     },
     {
       callback: options.function,
-      parser: (args) => parseStandardSchema(options.parameters, args),
+      parser: (args) => parseStandardSchema(getBinding, args),
     },
   );
 }
 
 /**
- * Creates a Responses API `function` tool from a Standard Schema validator.
+ * Creates a strict Responses API function tool from a Standard Schema validator and callback.
+ *
+ * `client.responses.parse()` validates matching function-call arguments and
+ * exposes them as `parsed_arguments`; it does not execute the attached callback
+ * or submit tool results. Validation must complete synchronously.
+ *
+ * @param options Model-visible function details, synchronous parameter validator,
+ * optional schema override, and callback metadata.
+ * @throws {OpenAIError} If no JSON Schema is available or its `oneOf` branches
+ * cannot be represented safely.
+ * @throws {Error} If strict normalization rejects another unsupported or
+ * unrepresentable JSON Schema feature.
+ * @throws {TypeError} If malformed JSON Schema values have unexpected structural types.
  */
 export function standardResponsesFunction<
   Parameters extends StandardSchemaLike,
-  Function extends StandardToolFunction<Parameters>,
+  ToolFunction extends StandardToolFunction<Parameters>,
 >(
-  options: StandardToolOptions<Parameters> & { function: Function },
-): AutoParseableResponseTool<StandardToolReturnOptions<Parameters, Function>>;
+  options: StandardToolOptions<Parameters> & {
+    /** Callback retained on the tool; `responses.parse()` does not execute it. */
+    function: ToolFunction;
+  },
+): AutoParseableResponseTool<StandardToolReturnOptions<Parameters, ToolFunction>>;
+
+/**
+ * Creates a parse-only Responses API function tool without an execution callback.
+ * `responses.parse()` exposes synchronously validated arguments as `parsed_arguments`.
+ *
+ * @throws {OpenAIError} If no JSON Schema is available or its `oneOf` branches
+ * cannot be represented safely.
+ * @throws {Error} If strict normalization rejects another unsupported or
+ * unrepresentable JSON Schema feature.
+ * @throws {TypeError} If malformed JSON Schema values have unexpected structural types.
+ */
 export function standardResponsesFunction<Parameters extends StandardSchemaLike>(
-  options: StandardToolOptions<Parameters> & { function?: undefined },
+  options: StandardToolOptions<Parameters> & {
+    /** No execution callback is attached to this parse-only function tool. */
+    function?: undefined;
+  },
 ): AutoParseableResponseTool<StandardToolReturnOptions<Parameters, undefined>>;
+
+/**
+ * Creates a strict Responses API function tool with an optionally available callback.
+ * Argument validation is synchronous; `responses.parse()` does not execute callbacks.
+ *
+ * @throws {OpenAIError} If no JSON Schema is available or its `oneOf` branches
+ * cannot be represented safely.
+ * @throws {Error} If strict normalization rejects another unsupported or
+ * unrepresentable JSON Schema feature.
+ * @throws {TypeError} If malformed JSON Schema values have unexpected structural types.
+ */
 export function standardResponsesFunction<Parameters extends StandardSchemaLike>(
   options: StandardToolOptions<Parameters>,
 ): AutoParseableResponseTool<
   StandardToolReturnOptions<Parameters, StandardToolFunction<Parameters> | undefined>
 >;
+
+/** Builds a strict Responses API function tool from a synchronous Standard Schema validator. */
 export function standardResponsesFunction<Parameters extends StandardSchemaLike>(
   options: StandardToolOptions<Parameters>,
 ) {
+  const name = options.name;
+  const parameters = options.parameters;
+  const getBinding = bindStandardSchema(parameters);
+
   return makeParseableResponseTool<any>(
     {
       type: 'function',
-      name: options.name,
-      parameters: resolveStandardJSONSchema(options.parameters, options.schema),
+      name,
+      parameters: resolveStandardJSONSchema(getBinding, options.schema),
       strict: true,
       ...(options.description ? { description: options.description } : undefined),
     },
     {
       callback: options.function,
-      parser: (args) => parseStandardSchema(options.parameters, args),
+      parser: (args) => parseStandardSchema(getBinding, args),
     },
   );
 }