Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs(providers): clarify strict schema behavior

jkomynoa93e8df547d9
diff --git a/docs/content/docs/providers/mastra.mdx b/docs/content/docs/providers/mastra.mdx
index 9166f5ce0..702938c12 100644
--- a/docs/content/docs/providers/mastra.mdx
+++ b/docs/content/docs/providers/mastra.mdx
@@ -62,7 +62,7 @@ console.log(text);
## Provider specifics
-**Strict mode.** Pass `strict: true` to normalize each tool's input schema for OpenAI structured outputs before Mastra compiles it: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` the model sends for an optional parameter is dropped before the tool runs. Tools whose schema cannot be expressed in strict mode (objects that accept arbitrary keys, `allOf`, `prefixItems`) keep their original schema and log a warning:
+**Strict mode.** Pass `strict: true` to normalize each tool's input schema for OpenAI structured outputs before Mastra compiles it: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the tool's own schema accepts `null` for that parameter, so nullable fields still receive an explicit `null`. Tools whose schema cannot be expressed in strict mode, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, keep their original schema and log a warning:
```typescript
// @noErrors
diff --git a/docs/content/docs/providers/openai.mdx b/docs/content/docs/providers/openai.mdx
index dc62bb3a2..4c2b09825 100644
--- a/docs/content/docs/providers/openai.mdx
+++ b/docs/content/docs/providers/openai.mdx
@@ -406,6 +406,30 @@ The OpenAI integration ships three providers, one per API surface:
- **`OpenAIProvider`** for the Chat Completions API. This is the SDK default, so `new Composio()` with no provider uses it. You keep the full message list and append each assistant message plus its `tool` results yourself.
- **`OpenAIAgentsProvider`** for the Agents SDK. Tools come with execution wired in, so the SDK runs the loop for you.
+**Strict mode.** Pass `strict: true` or `strict=True` to `OpenAIResponsesProvider`, or pass `strict: true` to `OpenAIAgentsProvider`, to normalize each tool's input schema for [structured outputs](https://platform.openai.com/docs/guides/structured-outputs). Every object lists all of its properties in `required` and is closed, while optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the tool's own schema accepts `null` for that parameter. Tools whose schema strict mode cannot express, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, are sent without strict mode and log a warning.
+
+<Tabs items={["TypeScript", "Python"]}>
+<Tab value="TypeScript">
+```typescript
+// @noErrors
+import { Composio } from "@composio/core";
+import { OpenAIResponsesProvider } from "@composio/openai";
+
+const composio = new Composio({
+ provider: new OpenAIResponsesProvider({ strict: true }),
+});
+```
+</Tab>
+<Tab value="Python">
+```python
+from composio import Composio
+from composio_openai import OpenAIResponsesProvider
+
+composio = Composio(provider=OpenAIResponsesProvider(strict=True))
+```
+</Tab>
+</Tabs>
+
<Callout type="info">
Pass the session to `handleToolCalls` / `handle_tool_calls` when the model received tools from `session.tools()`. The helper preserves the provider's argument normalization and executes every call through that session. For tools fetched via [`tools.get`](/docs/tools-direct/executing-tools), pass the user ID instead.
</Callout>
diff --git a/docs/content/docs/providers/vercel.mdx b/docs/content/docs/providers/vercel.mdx
index d8766b056..caaf96efb 100644
--- a/docs/content/docs/providers/vercel.mdx
+++ b/docs/content/docs/providers/vercel.mdx
@@ -57,7 +57,7 @@ console.log(text);
## Provider specifics
-**Strict mode.** Some models reject tool schemas that contain optional parameters. Pass `strict: true` to the provider to normalize each tool's input schema for OpenAI structured outputs before it reaches the AI SDK: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` the model sends for an optional parameter is dropped before the tool runs. Tools whose schema cannot be expressed in strict mode (objects that accept arbitrary keys, `allOf`, `prefixItems`) keep their original schema and log a warning:
+**Strict mode.** Some models reject tool schemas that contain optional parameters. Pass `strict: true` to the provider to normalize each tool's input schema for OpenAI structured outputs before it reaches the AI SDK: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the tool's own schema accepts `null` for that parameter, so nullable fields still receive an explicit `null`. Tools whose schema cannot be expressed in strict mode, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, keep their original schema and log a warning:
```typescript
// @noErrors
diff --git a/ts/packages/providers/mastra/README.md b/ts/packages/providers/mastra/README.md
index 82aa46f07..c2614727d 100644
--- a/ts/packages/providers/mastra/README.md
+++ b/ts/packages/providers/mastra/README.md
@@ -51,7 +51,7 @@ Each tool gets both an input and an output schema, so Mastra can validate tool r
## Strict mode
-Pass `strict: true` to normalize each tool's input schema for OpenAI structured outputs before Mastra compiles it: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` the model sends for an optional parameter is dropped before the tool runs. Tools whose schema cannot be expressed in strict mode (objects that accept arbitrary keys, `allOf`, `prefixItems`) keep their original schema and log a warning:
+Pass `strict: true` to normalize each tool's input schema for OpenAI structured outputs before Mastra compiles it: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the tool's own schema accepts `null` for that parameter, so nullable fields still receive an explicit `null`. Tools whose schema cannot be expressed in strict mode, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, keep their original schema and log a warning:
```typescript
const composio = new Composio({
diff --git a/ts/packages/providers/openai-agents/README.md b/ts/packages/providers/openai-agents/README.md
index ec341cc87..4510622db 100644
--- a/ts/packages/providers/openai-agents/README.md
+++ b/ts/packages/providers/openai-agents/README.md
@@ -43,7 +43,7 @@ For multi-turn conversations, store `session.sessionId` and reuse it with `compo
## Strict mode
-Pass `strict: true` to register tools with strict JSON schema validation (see the [Agents SDK options reference](https://openai.github.io/openai-agents-js/guides/tools/#options-reference)). Each tool's input schema is normalized for OpenAI structured outputs: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`; a `null` the model sends for an optional parameter is dropped before the tool runs. Tools whose schema cannot be expressed in strict mode (objects that accept arbitrary keys, `allOf`, `prefixItems`) are registered without strict mode and log a warning:
+Pass `strict: true` to register tools with strict JSON schema validation (see the [Agents SDK options reference](https://openai.github.io/openai-agents-js/guides/tools/#options-reference)). Each tool's input schema is normalized for OpenAI structured outputs: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the tool's own schema accepts `null` for that parameter, so nullable fields still receive an explicit `null`. Tools whose schema cannot be expressed in strict mode, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, are registered without strict mode and log a warning:
```typescript
const provider = new OpenAIAgentsProvider({ strict: true });
diff --git a/ts/packages/providers/openai/README.md b/ts/packages/providers/openai/README.md
index edfd0d15a..c54907362 100644
--- a/ts/packages/providers/openai/README.md
+++ b/ts/packages/providers/openai/README.md
@@ -63,7 +63,7 @@ for (const item of response.output) {
The package exports one provider per API surface:
-- `OpenAIResponsesProvider` targets the Responses API. `handleToolCalls(session, response.output)` returns `function_call_output` items keyed by `call_id`; pair it with `previous_response_id` so you only resend new outputs each turn. Pass a user ID instead of a session for tools fetched with `tools.get()`. The constructor accepts `{ strict?: boolean }` to enforce strict function schemas (default `false`).
+- `OpenAIResponsesProvider` targets the Responses API. `handleToolCalls(session, response.output)` returns `function_call_output` items keyed by `call_id`; pair it with `previous_response_id` so you only resend new outputs each turn. Pass a user ID instead of a session for tools fetched with `tools.get()`. Set `{ strict: true }` to normalize tool schemas for OpenAI structured outputs: every object becomes closed and lists every property in `required`, while optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the source schema accepts it. Tools whose schema strict mode cannot express, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, are sent without strict mode and log a warning.
- `OpenAIProvider` targets the Chat Completions API and is the Composio SDK default, so `new Composio()` with no provider uses it. `handleToolCalls(session, chatCompletion)` returns ready-to-append `tool` messages; you keep the full message list yourself.
Use the Responses provider for new agentic flows; reach for Chat Completions when extending an existing Chat Completions codebase. See the [docs page](https://docs.composio.dev/docs/providers/openai) for the Chat Completions loop.
diff --git a/ts/packages/providers/vercel/README.md b/ts/packages/providers/vercel/README.md
index 373156c1b..5cd2150f0 100644
--- a/ts/packages/providers/vercel/README.md
+++ b/ts/packages/providers/vercel/README.md
@@ -45,7 +45,7 @@ For multi-turn conversations, store `session.sessionId` and reuse it with `compo
## Strict mode
-Some models reject tool schemas that contain optional parameters. Pass `strict: true` to normalize each tool's input schema for OpenAI structured outputs before it reaches the AI SDK: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` the model sends for an optional parameter is dropped before the tool runs. Tools whose schema cannot be expressed in strict mode (objects that accept arbitrary keys, `allOf`, `prefixItems`) keep their original schema and log a warning:
+Some models reject tool schemas that contain optional parameters. Pass `strict: true` to normalize each tool's input schema for OpenAI structured outputs before it reaches the AI SDK: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the tool's own schema accepts `null` for that parameter, so nullable fields still receive an explicit `null`. Tools whose schema cannot be expressed in strict mode, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, keep their original schema and log a warning:
```typescript
const composio = new Composio({ provider: new VercelProvider({ strict: true }) });