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: stop documenting idempotentHint and openWorldHint
Only some tools set them, so they shouldn't be used to decide what an agent can do. Removes them from the SDK markdown docs, docstring examples and the meta-tool tag badges. The SDK types still accept them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 15:27 UTC
3e2abe7d857ab92e424b7ad5807bfcafa616648e
5 files changed
+25
-34
docs/components/meta-tools/meta-tool-detail.tsx
-8
@@ -19,14 +19,6 @@ const TAG_LABELS: Record<string, { label: string; className: string }> = {
19
label: 'Destructive',
20
className: 'bg-red-500/10 text-red-700 dark:text-red-400 border-red-500/20',
21
},
22
- idempotentHint: {
23
- label: 'Idempotent',
24
- className: 'bg-blue-500/10 text-blue-700 dark:text-blue-400 border-blue-500/20',
25
- },
26
- openWorldHint: {
27
- label: 'External',
28
- className: 'bg-purple-500/10 text-purple-700 dark:text-purple-400 border-purple-500/20',
29
- },
22
important: {
23
label: 'Important',
24
className: 'bg-amber-500/10 text-amber-700 dark:text-amber-400 border-amber-500/20',
python/composio/core/models/tool_router.py
+6
-7
@@ -869,7 +869,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
869
Example: {'disable': ['GMAIL_DELETE_EMAIL']}
870
- ToolRouterToolsTagsConfig: Dict with 'tags' key.
871
Tags can be a list (shorthand for enable) or object with enable/disable.
872
- Example: {'tags': ['readOnlyHint', 'idempotentHint']}
872
+ Example: {'tags': ['readOnlyHint', 'createHint']}
873
Example: {'tags': {'enable': ['readOnlyHint'], 'disable': ['destructiveHint']}}
874
Example: {
875
'gmail': ['GMAIL_SEND_EMAIL', 'GMAIL_SEARCH'],
@@ -883,12 +883,11 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
883
:param tags: Optional global MCP tags to filter tools by.
884
Can be:
885
- List[str]: List of tag literals (shorthand for enable).
886
- Example: ['readOnlyHint', 'idempotentHint']
886
+ Example: ['readOnlyHint', 'createHint']
887
- ToolRouterTagsEnableDisableConfig: Dict with 'enable' and/or 'disable' keys.
888
Example: {'enable': ['readOnlyHint'], 'disable': ['destructiveHint']}
889
- Available tag values: 'readOnlyHint', 'createHint',
890
- 'updateHint', 'destructiveHint', 'idempotentHint',
891
- 'openWorldHint'.
889
+ Tag values: 'readOnlyHint', 'createHint',
890
+ 'updateHint', 'destructiveHint'.
891
Experimental: the dict can also carry 'require_approval',
892
tags whose tools need the user's approval.
893
Example: {'require_approval': ['destructiveHint']}
@@ -1024,7 +1023,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1023
# Create a session with global tag filtering
1024
session = tool_router.create(
1025
user_id='user_123',
1027
- tags=['readOnlyHint', 'idempotentHint']
1026
+ tags=['readOnlyHint', 'createHint']
1027
)
1028
1029
# Create a session with toolkit-specific tag filtering (array format)
@@ -1032,7 +1031,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1031
user_id='user_123',
1032
tools={
1033
'gmail': {'tags': ['readOnlyHint']},
1035
- 'github': {'tags': ['readOnlyHint', 'idempotentHint']}
1034
+ 'github': {'tags': ['readOnlyHint', 'createHint']}
1035
}
1036
)
1037
python/docs/tool-router.md
+9
-9
@@ -158,13 +158,13 @@ session = composio.tool_router.create(
158
)
159
```
160
161
-Available tag values (every tool carries at least one of the first four):
162
-- `'readOnlyHint'`: Tools that only read data
163
-- `'createHint'`: Tools that create a new resource
164
-- `'updateHint'`: Tools that modify an existing resource in place
165
-- `'destructiveHint'`: Tools that irreversibly remove, cancel or revoke data
166
-- `'idempotentHint'`: Tools that can be safely retried (MCP hint, partial coverage)
167
-- `'openWorldHint'`: Tools that operate in an open world context (MCP hint, partial coverage)
161
+Every tool has a tag for the type of action it takes:
162
+- `'readOnlyHint'`: reads, searches, lists or computes something, and changes nothing
163
+- `'createHint'`: adds something new
164
+- `'updateHint'`: changes something that already exists
165
+- `'destructiveHint'`: can make something stop existing
166
+
167
+See [Tool tags](https://docs.composio.dev/docs/tool-tags) for how tools get their tags.
168
169
### `auth_configs`
170
@@ -744,7 +744,7 @@ ToolRouterToolsDisableConfig = TypedDict('ToolRouterToolsDisableConfig', {
744
})
745
746
ToolRouterToolsTagsConfig = TypedDict('ToolRouterToolsTagsConfig', {
747
- 'tags': List[Literal['readOnlyHint', 'destructiveHint', 'createHint', 'updateHint', 'idempotentHint', 'openWorldHint']]
747
+ 'tags': List[Literal['readOnlyHint', 'destructiveHint', 'createHint', 'updateHint']]
748
})
749
750
ToolRouterToolsConfig = Union[
@@ -757,7 +757,7 @@ ToolRouterToolsConfig = Union[
757
tools: Dict[str, ToolRouterToolsConfig] # Key is toolkit slug, value is ToolRouterToolsConfig
758
759
# Tags configuration (global)
760
-tags: List[Literal['readOnlyHint', 'destructiveHint', 'createHint', 'updateHint', 'idempotentHint', 'openWorldHint']]
760
+tags: List[Literal['readOnlyHint', 'destructiveHint', 'createHint', 'updateHint']]
761
762
# Manage connections configuration
763
ToolRouterManageConnectionsConfig = TypedDict('ToolRouterManageConnectionsConfig', {
ts/docs/api/tool-router.md
+9
-9
@@ -157,14 +157,14 @@ const session = await composio.create('user_123', {
157
});
158
```
159
160
-Available tags (every tool carries at least one of the first four):
160
+Every tool has a tag for the type of action it takes:
161
162
-- `readOnlyHint` - Tools that only read data
163
-- `createHint` - Tools that create a new resource
164
-- `updateHint` - Tools that modify an existing resource in place
165
-- `destructiveHint` - Tools that irreversibly remove, cancel or revoke data
166
-- `idempotentHint` - Tools that can be safely retried (MCP hint, partial coverage)
167
-- `openWorldHint` - Tools that operate in an open world context (MCP hint, partial coverage)
162
+- `readOnlyHint` - reads, searches, lists or computes something, and changes nothing
163
+- `createHint` - adds something new
164
+- `updateHint` - changes something that already exists
165
+- `destructiveHint` - can make something stop existing
166
+
167
+See [Tool tags](https://docs.composio.dev/docs/tool-tags) for how tools get their tags.
168
169
### `authConfigs`
170
@@ -934,9 +934,9 @@ interface ToolRouterCreateSessionConfig {
934
| string[]
935
| { enable: string[] }
936
| { disable: string[] }
937
- | { tags: ('readOnlyHint' | 'destructiveHint' | 'createHint' | 'updateHint' | 'idempotentHint' | 'openWorldHint')[] }
937
+ | { tags: ('readOnlyHint' | 'destructiveHint' | 'createHint' | 'updateHint')[] }
938
>;
939
- tags?: ('readOnlyHint' | 'destructiveHint' | 'createHint' | 'updateHint' | 'idempotentHint' | 'openWorldHint')[];
939
+ tags?: ('readOnlyHint' | 'destructiveHint' | 'createHint' | 'updateHint')[];
940
authConfigs?: Record<string, string>;
941
connectedAccounts?: Record<string, string>;
942
manageConnections?:
ts/packages/core/src/types/toolRouter.types.ts
+1
-1
@@ -525,7 +525,7 @@ export const ToolRouterCreateSessionConfigSchema = z
525
* @param {SessionPreset} [sessionPreset] - Shortcut that exposes every tool allowed by the session filters directly in session.tools() and the MCP tool list. Disables search, multi-execute, manage-connections, and sandbox by default; explicit overrides for supported fields still win. Without this preset, ToolRouter uses the default configuration with meta tools enabled.
526
* @param {ToolRouterToolkitsParamSchema | ToolRouterToolkitsDisabledConfigSchema | ToolRouterToolkitsEnabledConfigSchema} toolkits - The toolkits to use in the tool router session
527
* @param {Record<string, ToolRouterToolsParam | ToolRouterConfigTools>} tools - The tools to configure per toolkit (key is toolkit slug)
528
- * @param {Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>} tags - Global tags to filter tools by behavior
528
+ * @param {Array<'readOnlyHint' | 'createHint' | 'updateHint' | 'destructiveHint'>} tags - Global tags to filter tools by the type of action they take
529
* @param {Record<string, string>} authConfigs - The auth configs to use in the tool router session
530
* @param {Record<string, string | string[]>} connectedAccounts - The connected accounts to use in the tool router session. A single string is coerced to a single-element array before being sent to the backend.
531
* @param {ToolRouterInstant} [instant] - Experimental Instant usage policy. The project must allow Instant usage.