@devries-cameron20 / composio-1 / commits / 82341760c
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: describe the four verdict hints sessions filter on

Every tool carries at least one of readOnlyHint, createHint, updateHint or destructiveHint, but the tag table and SDK reference docs only listed the four MCP-spec hints, two of which (idempotentHint, openWorldHint) are set on a minority of tools. Lead with the four verdict hints and note the pinned-version gotcha on the v3 tools endpoints. The TypeScript twoslash example stays on readOnlyHint until @composio/core ships the widened enum (composio#4467). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHkYsmhteM1jJQoaoruiP3

Palash Kala committed Sep 13, 2026 at 21:45 UTC 82341760c4ecd3bef6723954aba5596074741a7b
3 files changed +36 -26
docs/content/docs/configuring-sessions.mdx
+15 -9
@@ -337,24 +337,30 @@ const session = await composio.create("user_123", {
337
338 ## Filtering tools by tags
339
340 -Tools carry behavior tags that you can filter on. The available tags are:
340 +Tools carry behavior tags that you can filter on. Every tool carries at least one of these four:
341
342 | Tag | Description |
343 |-----|-------------|
344 -| `readOnlyHint` | Tools that only read data |
345 -| `destructiveHint` | Tools that modify or delete data |
346 -| `idempotentHint` | Tools that can be safely retried |
347 -| `openWorldHint` | Tools that operate in an open world context |
344 +| `readOnlyHint` | Reads, searches, lists or computes. Changes nothing |
345 +| `createHint` | Creates a new resource, such as sending an email or opening an issue |
346 +| `updateHint` | Modifies an existing resource in place |
347 +| `destructiveHint` | Irreversibly removes, cancels or revokes data. An irreversible update also carries `updateHint` |
348 +
349 +The MCP annotation tags `idempotentHint` and `openWorldHint` are also accepted, but only some tools set them, so use the four above for access control.
350 +
351 +<Callout type="info">
352 +Sessions read the latest published version of each tool. The v3 tools endpoints default to the pinned version `00000000_00`, so pass `version=latest` (or use v3.1) to see the tags a session enforces.
353 +</Callout>
354
355 To apply tag filters across all toolkits, pass `tags` at the session level:
356
357 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
358 <Tab value="Python">
359 ```python
354 -# Only include read-only and idempotent tools
360 +# Only include tools that read or create; no updates or deletes
361 session = composio.sessions.create(
362 user_id="user_123",
357 - tags=["readOnlyHint", "idempotentHint"]
363 + tags=["readOnlyHint", "createHint"]
364 )
365
366 # Enable some tags, disable others
@@ -372,9 +378,9 @@ session = composio.sessions.create(
378 import { Composio } from '@composio/core';
379 const composio = new Composio({ apiKey: 'your_api_key' });
380 // ---cut---
375 -// Only include read-only and idempotent tools
381 +// Only include read-only tools
382 const session = await composio.create("user_123", {
377 - tags: ["readOnlyHint", "idempotentHint"]
383 + tags: ["readOnlyHint"]
384 });
385
386 // Enable some tags, disable others
python/docs/tool-router.md
+11 -9
@@ -140,8 +140,8 @@ session = composio.tool_router.create(
140 # Explicit disable configuration
141 'slack': {'disable': ['SLACK_DELETE_MESSAGE']},
142
143 - # Filter by MCP tags (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
144 - 'linear': {'tags': ['readOnlyHint', 'idempotentHint']}
143 + # Filter by behavior tags (readOnlyHint, destructiveHint, createHint, updateHint)
144 + 'linear': {'tags': ['readOnlyHint', 'createHint']}
145 }
146 )
147 ```
@@ -154,15 +154,17 @@ Global MCP tags to filter tools by across all toolkits. Only tools matching thes
154 session = composio.tool_router.create(
155 user_id='user_123',
156 toolkits=['gmail', 'github', 'slack'],
157 - tags=['readOnlyHint', 'idempotentHint'] # Only show read-only and idempotent tools
157 + tags=['readOnlyHint', 'createHint'] # Only show tools that read or create
158 )
159 ```
160
161 -Available tag values:
161 +Available tag values (every tool carries at least one of the first four):
162 - `'readOnlyHint'`: Tools that only read data
163 -- `'destructiveHint'`: Tools that modify or delete data
164 -- `'idempotentHint'`: Tools that can be safely retried
165 -- `'openWorldHint'`: Tools that operate in an open world context
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)
168
169 ### `auth_configs`
170
@@ -742,7 +744,7 @@ ToolRouterToolsDisableConfig = TypedDict('ToolRouterToolsDisableConfig', {
744 })
745
746 ToolRouterToolsTagsConfig = TypedDict('ToolRouterToolsTagsConfig', {
745 - 'tags': List[Literal['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint']]
747 + 'tags': List[Literal['readOnlyHint', 'destructiveHint', 'createHint', 'updateHint', 'idempotentHint', 'openWorldHint']]
748 })
749
750 ToolRouterToolsConfig = Union[
@@ -755,7 +757,7 @@ ToolRouterToolsConfig = Union[
757 tools: Dict[str, ToolRouterToolsConfig] # Key is toolkit slug, value is ToolRouterToolsConfig
758
759 # Tags configuration (global)
758 -tags: List[Literal['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint']]
760 +tags: List[Literal['readOnlyHint', 'destructiveHint', 'createHint', 'updateHint', 'idempotentHint', 'openWorldHint']]
761
762 # Manage connections configuration
763 ToolRouterManageConnectionsConfig = TypedDict('ToolRouterManageConnectionsConfig', {
ts/docs/api/tool-router.md
+10 -8
@@ -153,16 +153,18 @@ Global tags to filter tools by their behavior hints. Tags can be overridden per
153 const session = await composio.create('user_123', {
154 toolkits: ['gmail', 'github'],
155 // Global tags applied to all toolkits
156 - tags: ['readOnlyHint', 'idempotentHint'],
156 + tags: ['readOnlyHint', 'createHint'],
157 });
158 ```
159
160 -Available tags:
160 +Available tags (every tool carries at least one of the first four):
161
162 - `readOnlyHint` - Tools that only read data
163 -- `destructiveHint` - Tools that modify or delete data
164 -- `idempotentHint` - Tools that can be safely retried
165 -- `openWorldHint` - Tools that operate in an open world context
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)
168
169 ### `authConfigs`
170
@@ -904,7 +906,7 @@ These types include the `sessionId` in their parameters, allowing you to track a
906
907 3. **Connection Management**: Use `manageConnections: true` (default) for interactive applications where users can be prompted to connect accounts.
908
907 -4. **Tag Filtering**: Use global `tags` to filter tools by their behavior (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and override per toolkit when needed.
909 +4. **Tag Filtering**: Use global `tags` to filter tools by their behavior (readOnlyHint, destructiveHint, createHint, updateHint) and override per toolkit when needed.
910
911 5. **Session Reuse**: Store and reuse `sessionId` to maintain user sessions across requests.
912
@@ -932,9 +934,9 @@ interface ToolRouterCreateSessionConfig {
934 | string[]
935 | { enable: string[] }
936 | { disable: string[] }
935 - | { tags: ('readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint')[] }
937 + | { tags: ('readOnlyHint' | 'destructiveHint' | 'createHint' | 'updateHint' | 'idempotentHint' | 'openWorldHint')[] }
938 >;
937 - tags?: ('readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint')[];
939 + tags?: ('readOnlyHint' | 'destructiveHint' | 'createHint' | 'updateHint' | 'idempotentHint' | 'openWorldHint')[];
940 authConfigs?: Record<string, string>;
941 connectedAccounts?: Record<string, string>;
942 manageConnections?: