@devries-cameron20 / composio-1 / commits / 3e2abe7d8
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.

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.