fix(openai): emit strict:false for function tools whose schema is outside OpenAI's strict subset (#786)

* fix(openai): emit strict:false for tools whose schema is outside OpenAI's strict subset

The Responses and Chat Completions tool converters forced `strict: true` on
every function tool. When a tool's schema uses keywords OpenAI's strict
Structured Outputs subset doesn't support (oneOf/allOf/not/$ref/$defs —
routinely emitted by MCP servers such as Notion), the API rejected the entire
request with `400 Invalid schema for function '…'`, breaking every run that
included such a tool.

Detect schemas outside the strict subset (`isStrictModeCompatible`) and emit
those tools with `strict: false` — the schema is passed through (only
unsupported `format` keywords stripped) so the tool stays callable. Schemas
that fit the strict subset keep `strict: true` and the existing coercion.

* ci: apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: AlemTuzlak

.changeset/openai-strict-schema-fallback.md

@@ -0,0 +1,19 @@
+---
+'@tanstack/openai-base': patch
+---
+
+fix(openai): emit `strict: false` for function tools whose JSON Schema is outside OpenAI's strict subset
+
+The Responses and Chat Completions tool converters forced `strict: true` on
+every function tool. When a tool's schema uses keywords OpenAI's strict
+Structured Outputs subset doesn't support (`oneOf`/`allOf`/`not`/`$ref`/
+`$defs` — routinely emitted by MCP servers such as Notion), the API rejected
+the **entire** request with `400 Invalid schema for function '…'`, breaking
+every run that included such a tool.
+
+These converters now detect schemas outside the strict subset
+(`isStrictModeCompatible`) and emit those tools with `strict: false` — the
+schema is passed through (only unsupported `format` keywords are stripped) so
+the tool stays callable. Schemas that fit the strict subset keep `strict: true`
+and the existing structured-output coercion, so well-behaved tools are
+unaffected.

packages/openai-base/src/adapters/chat-completions-tool-converter.ts

@@ -1,4 +1,8 @@
-import { makeStructuredOutputCompatible } from '../utils/schema-converter'
+import {
+  isStrictModeCompatible,
+  makeStructuredOutputCompatible,
+  stripUnsupportedFormats,
+} from '../utils/schema-converter'
 import type { ChatCompletionTool } from 'openai/resources/chat/completions/completions'
 import type { JSONSchema, Tool } from '@tanstack/ai'
 
@@ -22,7 +26,14 @@ export type ChatCompletionFunctionTool = Extract<
  * - Optional fields made nullable
  * - additionalProperties: false
  *
- * This enables strict mode for all tools automatically.
+ * This enables strict mode for tools whose schemas fit OpenAI's strict subset.
+ *
+ * Schemas using keywords outside that subset (`oneOf`/`allOf`/`not`/`$ref`/
+ * `$defs` — common with MCP servers like Notion) can't be coerced to a
+ * strict-valid shape, and `strict: true` would make the API reject the ENTIRE
+ * request with a 400. Such tools are emitted with `strict: false` (their schema
+ * passed through, only unsupported `format` keywords stripped) so they stay
+ * callable.
  */
 export function convertFunctionToolToChatCompletionsFormat(
   tool: Tool,
@@ -37,6 +48,20 @@ export function convertFunctionToolToChatCompletionsFormat(
     required: [],
   }) as JSONSchema
 
+  // Schema outside OpenAI's strict subset: send non-strict so the tool still
+  // works instead of 400-ing the whole request.
+  if (!isStrictModeCompatible(inputSchema)) {
+    return {
+      type: 'function',
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: stripUnsupportedFormats(inputSchema),
+        strict: false,
+      },
+    } satisfies ChatCompletionFunctionTool
+  }
+
   // Shallow-copy the converter's result before mutating: a subclass-supplied
   // schemaConverter has no contract requirement to return a fresh object,
   // and a passthrough `(s) => s` would otherwise have its caller's schema

packages/openai-base/src/adapters/responses-tool-converter.ts

@@ -1,4 +1,8 @@
-import { makeStructuredOutputCompatible } from '../utils/schema-converter'
+import {
+  isStrictModeCompatible,
+  makeStructuredOutputCompatible,
+  stripUnsupportedFormats,
+} from '../utils/schema-converter'
 import type { JSONSchema, Tool } from '@tanstack/ai'
 
 /**
@@ -28,7 +32,14 @@ export interface ResponsesFunctionTool {
  * - Optional fields made nullable
  * - additionalProperties: false
  *
- * This enables strict mode for all tools automatically.
+ * This enables strict mode for tools whose schemas fit OpenAI's strict subset.
+ *
+ * Schemas using keywords outside that subset (`oneOf`/`allOf`/`not`/`$ref`/
+ * `$defs` — common with MCP servers like Notion) can't be coerced to a
+ * strict-valid shape, and `strict: true` would make the Responses API reject
+ * the ENTIRE request with a 400. Such tools are emitted with `strict: false`
+ * (their schema passed through, only unsupported `format` keywords stripped) so
+ * they stay callable.
  */
 export function convertFunctionToolToResponsesFormat(
   tool: Tool,
@@ -43,6 +54,18 @@ export function convertFunctionToolToResponsesFormat(
     required: [],
   }) as JSONSchema
 
+  // Schema outside OpenAI's strict subset: send non-strict so the tool still
+  // works instead of 400-ing the whole request.
+  if (!isStrictModeCompatible(inputSchema)) {
+    return {
+      type: 'function',
+      name: tool.name,
+      description: tool.description,
+      parameters: stripUnsupportedFormats(inputSchema),
+      strict: false,
+    }
+  }
+
   // Shallow-copy the converter's result before mutating — a subclass-supplied
   // schemaConverter has no contract requirement to return a fresh object;
   // mutating in place could corrupt the caller's tool definition.

packages/openai-base/src/utils/schema-converter.ts

@@ -27,7 +27,7 @@ const SUPPORTED_STRING_FORMATS = new Set([
  * a bare string, so it is preserved and recursed into; only the `format`
  * *keyword* (whose value is a string) is subject to removal.
  */
-function stripUnsupportedFormats(node: any): any {
+export function stripUnsupportedFormats(node: any): any {
   if (Array.isArray(node)) return node.map(stripUnsupportedFormats)
   if (node === null || typeof node !== 'object') return node
 
@@ -64,6 +64,55 @@ export function makeStructuredOutputCompatible(
   return stripUnsupportedFormats(coerceStrictSchema(schema, originalRequired))
 }
 
+/**
+ * JSON-Schema keywords outside OpenAI's strict Structured Outputs subset. A
+ * schema using any of these can't be coerced into a strict-valid shape, and
+ * sending it with `strict: true` makes the API reject the ENTIRE request
+ * (e.g. `400 Invalid schema ... 'additionalProperties' is required to be ...`).
+ * Tools with such schemas are emitted with `strict: false` instead (see the
+ * tool converters) so they remain callable. MCP servers (e.g. Notion) routinely
+ * emit these.
+ *
+ * - `oneOf` / `allOf` / `not` — combinator keywords strict mode rejects
+ * - `$ref` / `$defs` / `definitions` — references and definition pools whose
+ *   object subschemas escape the `additionalProperties: false` normalization
+ *   strict mode requires
+ */
+const STRICT_UNSUPPORTED_KEYWORDS: ReadonlyArray<string> = [
+  'oneOf',
+  'allOf',
+  'not',
+  '$ref',
+  '$defs',
+  'definitions',
+]
+
+/**
+ * Returns `false` when `schema` (anywhere in the tree) uses a JSON-Schema
+ * keyword outside OpenAI's strict Structured Outputs subset — i.e. it cannot be
+ * made strict-compatible and must be sent with `strict: false`.
+ *
+ * Conservative by design: keywords are matched as object keys, so a property
+ * literally named e.g. `oneOf` also trips it. That only costs that one tool its
+ * strict mode, which is strictly safer than a false "compatible" verdict that
+ * 400s the whole request.
+ */
+export function isStrictModeCompatible(schema: unknown): boolean {
+  return !containsStrictUnsupportedKeyword(schema)
+}
+
+function containsStrictUnsupportedKeyword(node: unknown): boolean {
+  if (Array.isArray(node)) {
+    return node.some(containsStrictUnsupportedKeyword)
+  }
+  if (node === null || typeof node !== 'object') return false
+  for (const [key, value] of Object.entries(node)) {
+    if (STRICT_UNSUPPORTED_KEYWORDS.includes(key)) return true
+    if (containsStrictUnsupportedKeyword(value)) return true
+  }
+  return false
+}
+
 /**
  * Strict-mode structural rewrite (required widening, nullability,
  * additionalProperties). Kept private so the public entry point can apply the

packages/openai-base/tests/schema-converter.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import { makeStructuredOutputCompatible } from '../src/utils/schema-converter'
+import {
+  isStrictModeCompatible,
+  makeStructuredOutputCompatible,
+} from '../src/utils/schema-converter'
 
 describe('makeStructuredOutputCompatible', () => {
   it('should add additionalProperties: false to object schemas', () => {
@@ -334,3 +337,82 @@ describe('makeStructuredOutputCompatible', () => {
     expect(schema.properties.data.format).toBe('uri')
   })
 })
+
+describe('isStrictModeCompatible', () => {
+  it('returns true for a plain object schema in the strict subset', () => {
+    expect(
+      isStrictModeCompatible({
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      }),
+    ).toBe(true)
+  })
+
+  it('returns true for nested objects, arrays, and anyOf (all strict-supported)', () => {
+    expect(
+      isStrictModeCompatible({
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                v: { anyOf: [{ type: 'string' }, { type: 'number' }] },
+              },
+            },
+          },
+        },
+      }),
+    ).toBe(true)
+  })
+
+  it.each(['oneOf', 'allOf', 'not'])(
+    'returns false when a combinator keyword (%s) appears anywhere',
+    (keyword) => {
+      expect(
+        isStrictModeCompatible({
+          type: 'object',
+          properties: {
+            value: { [keyword]: [{ type: 'string' }] },
+          },
+        }),
+      ).toBe(false)
+    },
+  )
+
+  it('returns false for schemas using $ref / $defs (references escape strict normalization)', () => {
+    expect(
+      isStrictModeCompatible({
+        type: 'object',
+        properties: { user: { $ref: '#/$defs/user' } },
+        $defs: {
+          user: { type: 'object', properties: { id: { type: 'string' } } },
+        },
+      }),
+    ).toBe(false)
+  })
+
+  it('detects unsupported keywords nested deep in the tree', () => {
+    expect(
+      isStrictModeCompatible({
+        type: 'object',
+        properties: {
+          a: {
+            type: 'object',
+            properties: {
+              b: { type: 'array', items: { oneOf: [{ type: 'string' }] } },
+            },
+          },
+        },
+      }),
+    ).toBe(false)
+  })
+
+  it('handles non-object input without throwing', () => {
+    expect(isStrictModeCompatible(undefined)).toBe(true)
+    expect(isStrictModeCompatible(null)).toBe(true)
+    expect(isStrictModeCompatible('x')).toBe(true)
+  })
+})

packages/openai-base/tests/tool-converter-strict-fallback.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import { convertFunctionToolToResponsesFormat } from '../src/adapters/responses-tool-converter'
+import { convertFunctionToolToChatCompletionsFormat } from '../src/adapters/chat-completions-tool-converter'
+import type { Tool } from '@tanstack/ai'
+
+/** A schema fully inside OpenAI's strict Structured Outputs subset. */
+const strictSafeTool: Tool = {
+  name: 'get_user',
+  description: 'Get a user',
+  inputSchema: {
+    type: 'object',
+    properties: { query: { type: 'string' } },
+    required: ['query'],
+  },
+}
+
+/**
+ * Mirrors a Notion-style MCP schema: uses `$defs` + `oneOf` (outside the strict
+ * subset) plus an unsupported `format`. With `strict: true` OpenAI 400s the
+ * whole request, so the converter must fall back to `strict: false`.
+ */
+const gnarlyTool: Tool = {
+  name: 'API-get-user',
+  description: 'Notion get user',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      user_id: { type: 'string', format: 'uuid' },
+      site: { type: 'string', format: 'uri' },
+    },
+    required: ['user_id'],
+    $defs: {
+      parent: {
+        oneOf: [
+          { type: 'object', properties: { page_id: { type: 'string' } } },
+        ],
+      },
+    },
+  } as unknown as Tool['inputSchema'],
+}
+
+describe('responses tool converter — strict fallback', () => {
+  it('uses strict:true for strict-subset schemas', () => {
+    const out = convertFunctionToolToResponsesFormat(strictSafeTool)
+    expect(out.strict).toBe(true)
+    expect(
+      (out.parameters as Record<string, unknown>).additionalProperties,
+    ).toBe(false)
+  })
+
+  it('falls back to strict:false for schemas with unsupported keywords', () => {
+    const out = convertFunctionToolToResponsesFormat(gnarlyTool)
+    expect(out.strict).toBe(false)
+    // Schema is preserved (not corrupted) so the tool stays callable...
+    const params = out.parameters as any
+    expect(params.$defs.parent.oneOf).toBeDefined()
+    // ...but unsupported `format` keywords are still stripped.
+    expect(params.properties.site.format).toBeUndefined()
+    expect(params.properties.user_id.format).toBe('uuid')
+  })
+})
+
+describe('chat-completions tool converter — strict fallback', () => {
+  it('uses strict:true for strict-subset schemas', () => {
+    const out = convertFunctionToolToChatCompletionsFormat(strictSafeTool)
+    expect(out.function.strict).toBe(true)
+  })
+
+  it('falls back to strict:false for schemas with unsupported keywords', () => {
+    const out = convertFunctionToolToChatCompletionsFormat(gnarlyTool)
+    expect(out.function.strict).toBe(false)
+    const params = out.function.parameters as any
+    expect(params.$defs.parent.oneOf).toBeDefined()
+    expect(params.properties.site.format).toBeUndefined()
+  })
+})