@devries-cameron20 / composio Mirror · read-only / commits / e8ffecece
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 16:00 UTC

docs(changelog): document free-form object argument preservation

Records the cross-SDK fix and, in particular, the Python behavior change the release would otherwise ship undocumented: object schemas that name properties and omit `additionalProperties` now reject unknown keys instead of dropping them, affecting the langchain, langgraph, and crewai providers.

jkomyno committed Aug 6, 2026 at 20:50 UTC e8ffecece3b482571e6584e18aedfe1cd0e2ab8c
1 file changed +96
docs/content/changelog/08-06-26-free-form-tool-arguments.mdx new
+96
@@ -0,0 +1,96 @@
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"
5 +---
6 +
7 +## Version Information
8 +
9 +### Python
10 +
11 +- Package: `composio`
12 +- Version: `0.18.2`+
13 +
14 +### TypeScript/JavaScript
15 +
16 +- Packages: `@composio/core`, `@composio/json-schema-to-zod`
17 +- Versions: `0.14.2`+, `0.2.2`+
18 +
19 +---
20 +
21 +A tool argument declared as a bare `{"type": "object"}` — with no `properties` of its own — was rejected or silently emptied at every schema conversion boundary. This affects any tool that takes a free-form payload, such as `dataset_query` on `METABASE_POST_API_CARD`.
22 +
23 +## What Changed
24 +
25 +An object schema that names no properties is now treated as open: arbitrary content is accepted and preserved, at the root, nested inside another object, and inside array items.
26 +
27 +**Before:**
28 +
29 +```python
30 +# dataset_query is declared as {"type": "object"} with no properties
31 +tool.run({"dataset_query": {"database": 1, "query": {"source-table": 2}}})
32 +# The argument was accepted, then arrived at execution as an empty object
33 +```
34 +
35 +**After:**
36 +
37 +```python
38 +tool.run({"dataset_query": {"database": 1, "query": {"source-table": 2}}})
39 +# The full payload reaches execution intact
40 +```
41 +
42 +In TypeScript the same schema was rejected outright rather than emptied, both in the Zod converter and in CLI tool-input validation:
43 +
44 +```
45 +<root>: Unknown key "database". Allowed top-level keys: dataset_query
46 +```
47 +
48 +Those inputs are now accepted.
49 +
50 +### Dynamic keys apply only where they should
51 +
52 +Where a schema declares `patternProperties` or a schema-valued `additionalProperties`, each key is now validated against exactly the schemas that claim it. Previously a key could pass by satisfying an unrelated pattern instead of its own.
53 +
54 +- Every matching `patternProperties` entry validates its key.
55 +- `additionalProperties` applies only to keys that no declared property and no pattern matches.
56 +- A key declared in `properties` is still checked against every pattern it matches.
57 +
58 +Root-level `patternProperties` and boolean- or schema-valued `additionalProperties` also survive tool schema parsing; they were previously dropped before any converter could see them.
59 +
60 +## Behavior Change for Python Agentic Providers
61 +
62 +<Callout type="warn">
63 +**Behavior change**
64 +
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 +</Callout>
69 +
70 +**Before:**
71 +
72 +```python
73 +# Tool declares only `name`. The model also emits `typo`.
74 +wrapped.run({"name": "a", "typo": 1})
75 +# The tool executed with {"name": "a"} - the extra argument was dropped in silence
76 +```
77 +
78 +**After:**
79 +
80 +```python
81 +wrapped.run({"name": "a", "typo": 1})
82 +# Raises ValidationError before execution, so the agent can correct and retry
83 +```
84 +
85 +This brings Python in line with the TypeScript SDK, where the Zod converter has always rejected unknown keys for schemas that name properties. Strictness applies only when `additionalProperties` is omitted; `additionalProperties: true` and schema-valued forms behave as declared.
86 +
87 +### Not affected
88 +
89 +- **`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.
90 +- **Declared field behavior, aliases for reserved Python keywords, `skip_default`, combiners, and references.** All unchanged.
91 +
92 +## Backward Compatibility
93 +
94 +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.
95 +
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.