@devries-cameron20 / composio-1 / commits / ac6bbabd3
Fork 0

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

fix(claude-agent-sdk): register complete tool schemas

The provider registered tools through jsonSchemaToZodShape, which returns only the per-property map. Root-level constraints -- `additionalProperties`, boolean or schema-valued, and `patternProperties` -- are structurally unrepresentable in a raw shape, so they were dropped before the Claude Agent SDK ever saw them: free-form object arguments lost their content, and an unknown key was silently stripped from tool input rather than rejected. Registering the complete object schema fixes both. A tool with no input parameters keeps its closed root explicitly, since a bare `properties: {}` is now an open object. Proven at the real SDK boundary rather than against a mocked `tool()`: the new suite drives createSdkMcpServer over an in-memory MCP transport and asserts on the advertised inputSchema and on real tools/call results.

jkomyno committed Aug 6, 2026 at 21:59 UTC ac6bbabd313b6e7d1c021888dc68ca970afd2a3d
7 files changed +220 -24
.changeset/claude-agent-sdk-complete-schema-registration.md new
+9
@@ -0,0 +1,9 @@
1 +---
2 +'@composio/claude-agent-sdk': minor
3 +---
4 +
5 +Register tools with their complete Zod object schema instead of a raw property shape, so root-level constraints survive registration.
6 +
7 +A raw shape is only the per-property map, so `additionalProperties` — boolean or schema-valued — and `patternProperties` were structurally unrepresentable and dropped before the Claude Agent SDK ever saw them. Free-form object arguments lost the content they exist to carry, and unknown keys were silently stripped from tool input rather than rejected.
8 +
9 +Behavior change: a tool whose schema names properties and omits `additionalProperties` is strict, so an argument the model invents now fails validation with an MCP invalid-params error instead of being quietly removed before execution. Tools with no input parameters stay closed for the same reason.
docs/content/changelog/08-06-26-free-form-tool-arguments.mdx
+24 -6
@@ -1,7 +1,7 @@
1 ---
2 -title: "Free-Form Object Arguments Are Preserved Across SDKs"
3 -description: "Tool arguments declared as bare objects are no longer rejected or silently emptied, and Python now enforces the same unknown-key rules as TypeScript"
4 -date: "2026-08-06"
2 +title: 'Free-Form Object Arguments Are Preserved Across SDKs'
3 +description: 'Tool arguments declared as bare objects are no longer rejected or silently emptied, and Python now enforces the same unknown-key rules as TypeScript'
4 +date: '2026-08-06'
5 ---
6
7 ## Version Information
@@ -13,8 +13,8 @@ date: "2026-08-06"
13
14 ### TypeScript/JavaScript
15
16 -- Packages: `@composio/core`, `@composio/json-schema-to-zod`
17 -- Versions: `0.15.0`+, `0.3.0`+
16 +- Packages: `@composio/core`, `@composio/json-schema-to-zod`, `@composio/claude-agent-sdk`
17 +- Versions: `0.15.0`+, `0.3.0`+, `0.11.0`+
18
19 ---
20
@@ -65,6 +65,7 @@ Root-level `patternProperties` and boolean- or schema-valued `additionalProperti
65 In the Python SDK, an object schema that **does** name properties and omits `additionalProperties` now rejects unknown keys instead of silently dropping them.
66
67 This affects the providers that build a Pydantic `args_schema` from a tool schema: `composio_langchain`, `composio_langgraph`, and `composio_crewai`. If a model emits an argument the tool does not declare, the call now raises a `ValidationError` instead of executing with that argument removed.
68 +
69 </Callout>
70
71 **Before:**
@@ -89,8 +90,25 @@ This brings Python in line with the TypeScript SDK, where the Zod converter has
90 - **`composio_openai`, `composio_anthropic`, `composio_gemini`, and the other non-agentic providers.** These hand the raw JSON schema to the model API and pass the returned arguments straight through, so they never build a Pydantic model from a tool schema.
91 - **Declared field behavior, aliases for reserved Python keywords, `skip_default`, combiners, and references.** All unchanged.
92
93 +## Behavior Change for the Claude Agent SDK Provider
94 +
95 +<Callout type="warn">
96 +**Behavior change**
97 +
98 +`@composio/claude-agent-sdk` now registers each tool with its complete object schema rather than a raw property shape.
99 +
100 +A raw shape carries only the per-property map, so root-level `additionalProperties` and `patternProperties` were dropped before the Claude Agent SDK ever saw them. An unknown key was stripped from the arguments and the tool executed anyway. It is now rejected with an MCP invalid-params error, matching every other TypeScript provider.
101 +
102 +</Callout>
103 +
104 +This is also what makes free-form object arguments reach execution intact through this provider: the content of a bare `{"type": "object"}` argument survives registration instead of being discarded with the rest of the root constraints.
105 +
106 +### Not affected
107 +
108 +- **`@composio/vercel`, `@composio/langchain`, and `@composio/llamaindex`.** These already registered complete schemas, so they picked the fix up with no change.
109 +
110 ## Backward Compatibility
111
112 Accepting and preserving free-form object content is backward compatible: payloads that previously failed now succeed, and payloads that previously arrived empty now arrive complete.
113
96 -The Python unknown-key rejection described above is the one behavior change. Tools whose schemas set `additionalProperties: true`, or whose objects declare no properties, are unaffected.
114 +The two unknown-key rejections described above — Python agentic providers, and the Claude Agent SDK provider — are the behavior changes. Tools whose schemas set `additionalProperties: true`, or whose objects declare no properties, are unaffected.
pnpm-lock.yaml
+4 -1
@@ -1532,6 +1532,9 @@ importers:
1532 '@composio/core':
1533 specifier: workspace:*
1534 version: link:../../core
1535 + '@modelcontextprotocol/sdk':
1536 + specifier: 'catalog:'
1537 + version: 1.30.0(@cfworker/json-schema@4.1.1)(zod@4.4.3)
1538 tsdown:
1539 specifier: 'catalog:'
1540 version: 0.22.14(@arethetypeswrong/core@0.18.5)(publint@0.3.22)(tsx@4.23.1)(typescript@7.0.2)(unrun@0.2.27(@emnapi/core@1.11.2)(@emnapi/runtime@1.11.2))
@@ -8606,7 +8609,7 @@ snapshots:
8609 debug: 4.4.3(supports-color@10.2.2)
8610 openai: 6.49.0(@aws-sdk/credential-provider-node@3.972.71)(@smithy/signature-v4@5.6.9)(ws@8.21.1)(zod@4.4.3)
8611 optionalDependencies:
8609 - '@modelcontextprotocol/sdk': 1.29.0(@cfworker/json-schema@4.1.1)(zod@4.4.3)
8612 + '@modelcontextprotocol/sdk': 1.30.0(@cfworker/json-schema@4.1.1)(zod@4.4.3)
8613 zod: 4.4.3
8614 transitivePeerDependencies:
8615 - '@aws-sdk/credential-provider-node'
ts/packages/providers/claude-agent-sdk/package.json
+1
@@ -56,6 +56,7 @@
56 },
57 "devDependencies": {
58 "@anthropic-ai/claude-agent-sdk": "^0.3.220",
59 + "@modelcontextprotocol/sdk": "catalog:",
60 "@composio/core": "workspace:*",
61 "tsdown": "catalog:",
62 "typescript": "catalog:",
ts/packages/providers/claude-agent-sdk/src/index.ts
+20 -9
@@ -15,8 +15,8 @@ import {
15 McpUrlResponse,
16 McpServerGetResponse,
17 normalizeToolArguments,
18 + jsonSchemaToZodSchema,
19 } from '@composio/core';
19 -import { jsonSchemaToZodShape } from '@composio/core/utils/json-schema';
20 import {
21 tool as sdkTool,
22 type Options as ClaudeAgentOptions,
@@ -102,18 +102,29 @@ export class ClaudeAgentSDKProvider extends BaseAgenticProvider<
102 * ```
103 */
104 wrapTool(composioTool: Tool, executeTool: ExecuteToolFn): ClaudeAgentTool {
105 - const inputZodShape = jsonSchemaToZodShape(
106 - composioTool.inputParameters ?? { type: 'object', properties: {} }
105 + // Register the complete object schema rather than its raw property shape. A raw shape is only
106 + // the per-property map, so every root-level constraint — `additionalProperties`, whether
107 + // boolean or schema-valued, and `patternProperties` — is structurally unrepresentable and gets
108 + // dropped at registration. The SDK then silently strips unknown keys instead of rejecting them,
109 + // and free-form roots lose the content they exist to carry.
110 + //
111 + // A tool with no input parameters stays closed: the fallback spells out
112 + // `additionalProperties: false`, because a bare `properties: {}` is now an open object.
113 + const inputZodSchema = jsonSchemaToZodSchema(
114 + composioTool.inputParameters ?? {
115 + type: 'object',
116 + properties: {},
117 + additionalProperties: false,
118 + }
119 );
120
109 - // The SDK types tool() generically over its zod raw shape, which makes the handler argument
110 - // instantiate excessively deep against the v3 shape returned here (TS2589). Narrow tool() to a
111 - // concrete, monomorphic signature once — this sidesteps the deep instantiation and lets the
112 - // handler keep a precise argument type, instead of scattering `as never` casts at the call.
121 + // The SDK runtime accepts a complete schema, but `tool()` only exposes the raw-shape type, and
122 + // that generic signature also makes the handler argument instantiate excessively deep (TS2589).
123 + // Narrow it to a concrete, monomorphic signature once, instead of scattering casts at the call.
124 const defineTool = sdkTool as unknown as (
125 name: string,
126 description: string,
116 - inputShape: ReturnType<typeof jsonSchemaToZodShape>,
127 + inputSchema: ReturnType<typeof jsonSchemaToZodSchema>,
128 handler: (
129 args: Record<string, unknown>
130 ) => Promise<{ content: Array<{ type: 'text'; text: string }> }>
@@ -122,7 +133,7 @@ export class ClaudeAgentSDKProvider extends BaseAgenticProvider<
133 return defineTool(
134 composioTool.slug,
135 composioTool.description ?? `Execute ${composioTool.slug}`,
125 - inputZodShape,
136 + inputZodSchema,
137 async args => {
138 try {
139 // Models occasionally emit tool input as a JSON string rather than an object (issue #2406).
ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk.registration.test.ts new
+146
@@ -0,0 +1,146 @@
1 +/**
2 + * Registration boundary tests for the Claude Agent SDK provider.
3 + *
4 + * The sibling suite mocks `tool()`, which proves what the provider *passes* but not what the SDK
5 + * *does* with it. Root object constraints are precisely the part a mock cannot check: they survive
6 + * or vanish inside `createSdkMcpServer`, when the registered Zod schema is projected to the JSON
7 + * Schema the model sees and used to validate incoming arguments.
8 + *
9 + * These tests therefore drive the real SDK over an in-memory MCP transport and assert on the
10 + * emitted `inputSchema` and on real `tools/call` results.
11 + */
12 +import { describe, it, expect, vi } from 'vitest';
13 +import { Client } from '@modelcontextprotocol/sdk/client/index.js';
14 +import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
15 +import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
16 +import type { Tool, GlobalExecuteToolFn } from '@composio/core';
17 +import { ClaudeAgentSDKProvider } from '../src';
18 +
19 +type ToolCallResult = {
20 + isError?: boolean;
21 + content?: Array<{ type: string; text?: string }>;
22 +};
23 +
24 +const buildTool = (inputParameters: Tool['inputParameters']): Tool =>
25 + ({
26 + slug: 'TEST_TOOL',
27 + name: 'Test Tool',
28 + description: 'A tool under test',
29 + version: '20250909_00',
30 + availableVersions: ['20250909_00'],
31 + inputParameters,
32 + tags: [],
33 + }) as Tool;
34 +
35 +/**
36 + * Register one Composio tool through the provider and connect a real MCP client to it.
37 + *
38 + * Returns the tool's advertised input schema plus a `call` helper, so each test can assert on both
39 + * what the model is shown and what actually reaches execution.
40 + */
41 +const registerTool = async (composioTool: Tool) => {
42 + const executeToolFn = vi.fn().mockResolvedValue({
43 + data: { result: 'success' },
44 + error: null,
45 + successful: true,
46 + }) as unknown as GlobalExecuteToolFn;
47 +
48 + const provider = new ClaudeAgentSDKProvider();
49 + provider._setExecuteToolFn(executeToolFn);
50 +
51 + const server = createSdkMcpServer({
52 + name: 'composio-test',
53 + version: '1.0.0',
54 + tools: [provider.wrapTool(composioTool, executeToolFn)],
55 + });
56 +
57 + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
58 + const client = new Client({ name: 'test-client', version: '1.0.0' });
59 + await server.instance.server.connect(serverTransport);
60 + await client.connect(clientTransport);
61 +
62 + const { tools } = await client.listTools();
63 +
64 + return {
65 + executeToolFn,
66 + inputSchema: tools[0].inputSchema as Record<string, unknown>,
67 + call: (args: Record<string, unknown>) =>
68 + client.callTool({ name: composioTool.slug, arguments: args }) as Promise<ToolCallResult>,
69 + };
70 +};
71 +
72 +describe('ClaudeAgentSDKProvider registration boundary', () => {
73 + it('carries a free-form object argument through registration and execution intact', async () => {
74 + const { inputSchema, executeToolFn, call } = await registerTool(
75 + buildTool({
76 + type: 'object',
77 + properties: { dataset_query: { type: 'object' } },
78 + required: ['dataset_query'],
79 + })
80 + );
81 +
82 + expect(inputSchema.properties).toMatchObject({ dataset_query: { type: 'object' } });
83 +
84 + const dataset_query = { database: 1, query: { 'source-table': 2, aggregation: [['count']] } };
85 + const result = await call({ dataset_query });
86 +
87 + expect(result.isError ?? false).toBe(false);
88 + expect(executeToolFn).toHaveBeenCalledWith(
89 + 'TEST_TOOL',
90 + expect.objectContaining({ dataset_query })
91 + );
92 + });
93 +
94 + it('rejects an unknown key instead of silently dropping it', async () => {
95 + // A raw property shape cannot express a root `additionalProperties`, so the SDK stripped
96 + // unknown keys and executed anyway. Registering the complete schema makes the root strict.
97 + const { inputSchema, executeToolFn, call } = await registerTool(
98 + buildTool({
99 + type: 'object',
100 + properties: { to: { type: 'string' } },
101 + required: ['to'],
102 + })
103 + );
104 +
105 + expect(inputSchema.additionalProperties).toBe(false);
106 +
107 + const result = await call({ to: 'someone@example.com', hallucinated: 'value' });
108 +
109 + expect(result.isError).toBe(true);
110 + expect(executeToolFn).not.toHaveBeenCalled();
111 + });
112 +
113 + it('preserves root patternProperties so matching keys are accepted and validated', async () => {
114 + const { executeToolFn, call } = await registerTool(
115 + buildTool({
116 + type: 'object',
117 + properties: {},
118 + patternProperties: { '^meta_': { type: 'string' } },
119 + })
120 + );
121 +
122 + const accepted = await call({ meta_source: 'crm' });
123 + expect(accepted.isError ?? false).toBe(false);
124 + expect(executeToolFn).toHaveBeenCalledWith(
125 + 'TEST_TOOL',
126 + expect.objectContaining({ meta_source: 'crm' })
127 + );
128 +
129 + executeToolFn.mockClear();
130 +
131 + const rejected = await call({ meta_source: 42 });
132 + expect(rejected.isError).toBe(true);
133 + expect(executeToolFn).not.toHaveBeenCalled();
134 + });
135 +
136 + it('keeps a tool with no input parameters closed', async () => {
137 + const { inputSchema, executeToolFn, call } = await registerTool(buildTool(undefined));
138 +
139 + expect(inputSchema.additionalProperties).toBe(false);
140 +
141 + const result = await call({ unexpected: 'value' });
142 +
143 + expect(result.isError).toBe(true);
144 + expect(executeToolFn).not.toHaveBeenCalled();
145 + });
146 +});
ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk.test.ts
+16 -8
@@ -29,8 +29,8 @@ interface MockedClaudeAgentTool {
29 _isMockedClaudeAgentTool: boolean;
30 }
31
32 -// Minimal structural type for a zod-like raw shape value, matching only the member these
33 -// tests dereference (`safeParse`).
32 +// Minimal structural type for the complete Zod object schema the provider registers, matching
33 +// only the member these tests dereference (`safeParse`).
34 type MinimalZodSchema = {
35 safeParse: (value: unknown) => { success: boolean };
36 };
@@ -47,7 +47,7 @@ type MockedToolFn = Mock<
47 (
48 name: string,
49 description: string | undefined,
50 - schema: Record<string, MinimalZodSchema>,
50 + schema: MinimalZodSchema,
51 handler: MockedToolHandler
52 ) => unknown
53 >;
@@ -139,13 +139,21 @@ describe('ClaudeAgentSDKProvider', () => {
139 expect(wrapped.description).toBe(mockTool.description);
140 });
141
142 - it('should pass a raw Zod shape to the Claude Agent SDK', () => {
142 + it('should pass a complete Zod object schema to the Claude Agent SDK', () => {
143 + // A raw property shape drops every root-level constraint, so the provider registers the
144 + // whole object schema instead. See claude-agent-sdk.registration.test.ts for what that
145 + // buys at the real SDK boundary.
146 provider.wrapTool(mockTool, mockExecuteToolFn);
147
145 - const schemaShape = (tool as unknown as MockedToolFn).mock.calls[0][2];
146 - expect(Object.keys(schemaShape)).toEqual(['to', 'subject', 'body']);
147 - expect(schemaShape.to.safeParse('test@example.com').success).toBe(true);
148 - expect(schemaShape.to.safeParse(123).success).toBe(false);
148 + const schema = (tool as unknown as MockedToolFn).mock.calls[0][2];
149 + expect(schema.safeParse({ to: 'test@example.com', subject: 's', body: 'b' }).success).toBe(
150 + true
151 + );
152 + expect(schema.safeParse({ to: 123, subject: 's', body: 'b' }).success).toBe(false);
153 + // The root is strict: `additionalProperties` is omitted on a named-properties schema.
154 + expect(
155 + schema.safeParse({ to: 'test@example.com', subject: 's', body: 'b', extra: 'x' }).success
156 + ).toBe(false);
157 });
158
159 it('should handle tools without input parameters', () => {