Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(claude-agent-sdk): register complete tool schemas
jkomynoac6bbabd313b
diff --git a/.changeset/claude-agent-sdk-complete-schema-registration.md b/.changeset/claude-agent-sdk-complete-schema-registration.mdnew file mode 100644index 000000000..fbf4c714a--- /dev/null+++ b/.changeset/claude-agent-sdk-complete-schema-registration.md@@ -0,0 +1,9 @@+---+'@composio/claude-agent-sdk': minor+---++Register tools with their complete Zod object schema instead of a raw property shape, so root-level constraints survive registration.++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.++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.diff --git a/docs/content/changelog/08-06-26-free-form-tool-arguments.mdx b/docs/content/changelog/08-06-26-free-form-tool-arguments.mdxindex 57c6d50db..e245a0842 100644--- a/docs/content/changelog/08-06-26-free-form-tool-arguments.mdx+++ b/docs/content/changelog/08-06-26-free-form-tool-arguments.mdx@@ -1,7 +1,7 @@----title: "Free-Form Object Arguments Are Preserved Across SDKs"-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"-date: "2026-08-06"+title: 'Free-Form Object Arguments Are Preserved Across SDKs'+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'+date: '2026-08-06'---## Version Information@@ -13,8 +13,8 @@ date: "2026-08-06"### TypeScript/JavaScript-- Packages: `@composio/core`, `@composio/json-schema-to-zod`-- Versions: `0.15.0`+, `0.3.0`++- Packages: `@composio/core`, `@composio/json-schema-to-zod`, `@composio/claude-agent-sdk`+- Versions: `0.15.0`+, `0.3.0`+, `0.11.0`+---@@ -65,6 +65,7 @@ Root-level `patternProperties` and boolean- or schema-valued `additionalPropertiIn the Python SDK, an object schema that **does** name properties and omits `additionalProperties` now rejects unknown keys instead of silently dropping them.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.+</Callout>**Before:**@@ -89,8 +90,25 @@ This brings Python in line with the TypeScript SDK, where the Zod converter has- **`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.- **Declared field behavior, aliases for reserved Python keywords, `skip_default`, combiners, and references.** All unchanged.+## Behavior Change for the Claude Agent SDK Provider++<Callout type="warn">+**Behavior change**++`@composio/claude-agent-sdk` now registers each tool with its complete object schema rather than a raw property shape.++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.++</Callout>++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.++### Not affected++- **`@composio/vercel`, `@composio/langchain`, and `@composio/llamaindex`.** These already registered complete schemas, so they picked the fix up with no change.+## Backward CompatibilityAccepting and preserving free-form object content is backward compatible: payloads that previously failed now succeed, and payloads that previously arrived empty now arrive complete.-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.+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.diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex ed10f4ac4..a1424f221 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -1532,6 +1532,9 @@ importers:'@composio/core':specifier: workspace:*version: link:../../core+ '@modelcontextprotocol/sdk':+ specifier: 'catalog:'+ version: 1.30.0(@cfworker/[email protected])([email protected])tsdown:specifier: 'catalog:'version: 0.22.14(@arethetypeswrong/[email protected])([email protected])([email protected])([email protected])([email protected](@emnapi/[email protected])(@emnapi/[email protected]))@@ -8606,7 +8609,7 @@ snapshots:debug: 4.4.3([email protected])openai: 6.49.0(@aws-sdk/[email protected])(@smithy/[email protected])([email protected])([email protected])optionalDependencies:- '@modelcontextprotocol/sdk': 1.29.0(@cfworker/[email protected])([email protected])+ '@modelcontextprotocol/sdk': 1.30.0(@cfworker/[email protected])([email protected])zod: 4.4.3transitivePeerDependencies:- '@aws-sdk/credential-provider-node'diff --git a/ts/packages/providers/claude-agent-sdk/package.json b/ts/packages/providers/claude-agent-sdk/package.jsonindex 4ed50922e..12427a539 100644--- a/ts/packages/providers/claude-agent-sdk/package.json+++ b/ts/packages/providers/claude-agent-sdk/package.json@@ -56,6 +56,7 @@},"devDependencies": {"@anthropic-ai/claude-agent-sdk": "^0.3.220",+ "@modelcontextprotocol/sdk": "catalog:","@composio/core": "workspace:*","tsdown": "catalog:","typescript": "catalog:",diff --git a/ts/packages/providers/claude-agent-sdk/src/index.ts b/ts/packages/providers/claude-agent-sdk/src/index.tsindex aff8a055e..bb8380fc8 100644--- a/ts/packages/providers/claude-agent-sdk/src/index.ts+++ b/ts/packages/providers/claude-agent-sdk/src/index.ts@@ -15,8 +15,8 @@ import {McpUrlResponse,McpServerGetResponse,normalizeToolArguments,+ jsonSchemaToZodSchema,} from '@composio/core';-import { jsonSchemaToZodShape } from '@composio/core/utils/json-schema';import {tool as sdkTool,type Options as ClaudeAgentOptions,@@ -102,18 +102,29 @@ export class ClaudeAgentSDKProvider extends BaseAgenticProvider<* ```*/wrapTool(composioTool: Tool, executeTool: ExecuteToolFn): ClaudeAgentTool {- const inputZodShape = jsonSchemaToZodShape(- composioTool.inputParameters ?? { type: 'object', properties: {} }+ // Register the complete object schema rather than its raw property shape. A raw shape is only+ // the per-property map, so every root-level constraint — `additionalProperties`, whether+ // boolean or schema-valued, and `patternProperties` — is structurally unrepresentable and gets+ // dropped at registration. The SDK then silently strips unknown keys instead of rejecting them,+ // and free-form roots lose the content they exist to carry.+ //+ // A tool with no input parameters stays closed: the fallback spells out+ // `additionalProperties: false`, because a bare `properties: {}` is now an open object.+ const inputZodSchema = jsonSchemaToZodSchema(+ composioTool.inputParameters ?? {+ type: 'object',+ properties: {},+ additionalProperties: false,+ });- // The SDK types tool() generically over its zod raw shape, which makes the handler argument- // instantiate excessively deep against the v3 shape returned here (TS2589). Narrow tool() to a- // concrete, monomorphic signature once — this sidesteps the deep instantiation and lets the- // handler keep a precise argument type, instead of scattering `as never` casts at the call.+ // The SDK runtime accepts a complete schema, but `tool()` only exposes the raw-shape type, and+ // that generic signature also makes the handler argument instantiate excessively deep (TS2589).+ // Narrow it to a concrete, monomorphic signature once, instead of scattering casts at the call.const defineTool = sdkTool as unknown as (name: string,description: string,- inputShape: ReturnType<typeof jsonSchemaToZodShape>,+ inputSchema: ReturnType<typeof jsonSchemaToZodSchema>,handler: (args: Record<string, unknown>) => Promise<{ content: Array<{ type: 'text'; text: string }> }>@@ -122,7 +133,7 @@ export class ClaudeAgentSDKProvider extends BaseAgenticProvider<return defineTool(composioTool.slug,composioTool.description ?? `Execute ${composioTool.slug}`,- inputZodShape,+ inputZodSchema,async args => {try {// Models occasionally emit tool input as a JSON string rather than an object (issue #2406).diff --git a/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk.registration.test.ts b/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk.registration.test.tsnew file mode 100644index 000000000..7f00e2441--- /dev/null+++ b/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk.registration.test.ts@@ -0,0 +1,146 @@+/**+ * Registration boundary tests for the Claude Agent SDK provider.+ *+ * The sibling suite mocks `tool()`, which proves what the provider *passes* but not what the SDK+ * *does* with it. Root object constraints are precisely the part a mock cannot check: they survive+ * or vanish inside `createSdkMcpServer`, when the registered Zod schema is projected to the JSON+ * Schema the model sees and used to validate incoming arguments.+ *+ * These tests therefore drive the real SDK over an in-memory MCP transport and assert on the+ * emitted `inputSchema` and on real `tools/call` results.+ */+import { describe, it, expect, vi } from 'vitest';+import { Client } from '@modelcontextprotocol/sdk/client/index.js';+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';+import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';+import type { Tool, GlobalExecuteToolFn } from '@composio/core';+import { ClaudeAgentSDKProvider } from '../src';++type ToolCallResult = {+ isError?: boolean;+ content?: Array<{ type: string; text?: string }>;+};++const buildTool = (inputParameters: Tool['inputParameters']): Tool =>+ ({+ slug: 'TEST_TOOL',+ name: 'Test Tool',+ description: 'A tool under test',+ version: '20250909_00',+ availableVersions: ['20250909_00'],+ inputParameters,+ tags: [],+ }) as Tool;++/**+ * Register one Composio tool through the provider and connect a real MCP client to it.+ *+ * Returns the tool's advertised input schema plus a `call` helper, so each test can assert on both+ * what the model is shown and what actually reaches execution.+ */+const registerTool = async (composioTool: Tool) => {+ const executeToolFn = vi.fn().mockResolvedValue({+ data: { result: 'success' },+ error: null,+ successful: true,+ }) as unknown as GlobalExecuteToolFn;++ const provider = new ClaudeAgentSDKProvider();+ provider._setExecuteToolFn(executeToolFn);++ const server = createSdkMcpServer({+ name: 'composio-test',+ version: '1.0.0',+ tools: [provider.wrapTool(composioTool, executeToolFn)],+ });++ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();+ const client = new Client({ name: 'test-client', version: '1.0.0' });+ await server.instance.server.connect(serverTransport);+ await client.connect(clientTransport);++ const { tools } = await client.listTools();++ return {+ executeToolFn,+ inputSchema: tools[0].inputSchema as Record<string, unknown>,+ call: (args: Record<string, unknown>) =>+ client.callTool({ name: composioTool.slug, arguments: args }) as Promise<ToolCallResult>,+ };+};++describe('ClaudeAgentSDKProvider registration boundary', () => {+ it('carries a free-form object argument through registration and execution intact', async () => {+ const { inputSchema, executeToolFn, call } = await registerTool(+ buildTool({+ type: 'object',+ properties: { dataset_query: { type: 'object' } },+ required: ['dataset_query'],+ })+ );++ expect(inputSchema.properties).toMatchObject({ dataset_query: { type: 'object' } });++ const dataset_query = { database: 1, query: { 'source-table': 2, aggregation: [['count']] } };+ const result = await call({ dataset_query });++ expect(result.isError ?? false).toBe(false);+ expect(executeToolFn).toHaveBeenCalledWith(+ 'TEST_TOOL',+ expect.objectContaining({ dataset_query })+ );+ });++ it('rejects an unknown key instead of silently dropping it', async () => {+ // A raw property shape cannot express a root `additionalProperties`, so the SDK stripped+ // unknown keys and executed anyway. Registering the complete schema makes the root strict.+ const { inputSchema, executeToolFn, call } = await registerTool(+ buildTool({+ type: 'object',+ properties: { to: { type: 'string' } },+ required: ['to'],+ })+ );++ expect(inputSchema.additionalProperties).toBe(false);++ const result = await call({ to: '[email protected]', hallucinated: 'value' });++ expect(result.isError).toBe(true);+ expect(executeToolFn).not.toHaveBeenCalled();+ });++ it('preserves root patternProperties so matching keys are accepted and validated', async () => {+ const { executeToolFn, call } = await registerTool(+ buildTool({+ type: 'object',+ properties: {},+ patternProperties: { '^meta_': { type: 'string' } },+ })+ );++ const accepted = await call({ meta_source: 'crm' });+ expect(accepted.isError ?? false).toBe(false);+ expect(executeToolFn).toHaveBeenCalledWith(+ 'TEST_TOOL',+ expect.objectContaining({ meta_source: 'crm' })+ );++ executeToolFn.mockClear();++ const rejected = await call({ meta_source: 42 });+ expect(rejected.isError).toBe(true);+ expect(executeToolFn).not.toHaveBeenCalled();+ });++ it('keeps a tool with no input parameters closed', async () => {+ const { inputSchema, executeToolFn, call } = await registerTool(buildTool(undefined));++ expect(inputSchema.additionalProperties).toBe(false);++ const result = await call({ unexpected: 'value' });++ expect(result.isError).toBe(true);+ expect(executeToolFn).not.toHaveBeenCalled();+ });+});diff --git a/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk.test.ts b/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk.test.tsindex f0c76026f..f3cd02be4 100644--- a/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk.test.ts+++ b/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk.test.ts@@ -29,8 +29,8 @@ interface MockedClaudeAgentTool {_isMockedClaudeAgentTool: boolean;}-// Minimal structural type for a zod-like raw shape value, matching only the member these-// tests dereference (`safeParse`).+// Minimal structural type for the complete Zod object schema the provider registers, matching+// only the member these tests dereference (`safeParse`).type MinimalZodSchema = {safeParse: (value: unknown) => { success: boolean };};@@ -47,7 +47,7 @@ type MockedToolFn = Mock<(name: string,description: string | undefined,- schema: Record<string, MinimalZodSchema>,+ schema: MinimalZodSchema,handler: MockedToolHandler) => unknown>;@@ -139,13 +139,21 @@ describe('ClaudeAgentSDKProvider', () => {expect(wrapped.description).toBe(mockTool.description);});- it('should pass a raw Zod shape to the Claude Agent SDK', () => {+ it('should pass a complete Zod object schema to the Claude Agent SDK', () => {+ // A raw property shape drops every root-level constraint, so the provider registers the+ // whole object schema instead. See claude-agent-sdk.registration.test.ts for what that+ // buys at the real SDK boundary.provider.wrapTool(mockTool, mockExecuteToolFn);- const schemaShape = (tool as unknown as MockedToolFn).mock.calls[0][2];- expect(Object.keys(schemaShape)).toEqual(['to', 'subject', 'body']);- expect(schemaShape.to.safeParse('[email protected]').success).toBe(true);- expect(schemaShape.to.safeParse(123).success).toBe(false);+ const schema = (tool as unknown as MockedToolFn).mock.calls[0][2];+ expect(schema.safeParse({ to: '[email protected]', subject: 's', body: 'b' }).success).toBe(+ true+ );+ expect(schema.safeParse({ to: 123, subject: 's', body: 'b' }).success).toBe(false);+ // The root is strict: `additionalProperties` is omitted on a named-properties schema.+ expect(+ schema.safeParse({ to: '[email protected]', subject: 's', body: 'b', extra: 'x' }).success+ ).toBe(false);});it('should handle tools without input parameters', () => {