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.