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, 08:30 UTC
docs: add tool tags page
Explains the four governance tags, how a tool's single tag is chosen, where tags come from for Composio and MCP toolkits, and how sessions use them. Configuring Sessions now links there instead of repeating the definitions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 15:15 UTC
a96f4e6f63632d744cc29f87ad9d5a9de45696e7
6 files changed
+68
-19
docs/content/docs/approval-mode.mdx
+1
-1
@@ -26,7 +26,7 @@ toolkits={"enable": ["gmail", "github"]}
26
27
### 2. Choose what each tag does
28
29
-Every tool has a [tag](/docs/configuring-sessions#filtering-tools-by-tags) for the type of action it takes:
29
+Every tool has a [tag](/docs/tool-tags) for the type of action it takes:
30
31
| Tag | Action |
32
|---|---|
docs/content/docs/configuring-sessions.mdx
+1
-16
@@ -403,22 +403,7 @@ const session = await composio.create("user_123", {
403
404
## Filtering tools by tags
405
406
-Tools carry behavior tags that you can filter on. Every tool carries at least one of these four:
407
-
408
-| Tag | Description |
409
-|-----|-------------|
410
-| `readOnlyHint` | Reads, searches, lists or computes. Changes nothing |
411
-| `createHint` | Creates a new resource, such as sending an email or opening an issue |
412
-| `updateHint` | Modifies an existing resource in place |
413
-| `destructiveHint` | Irreversibly removes, cancels or revokes data. An irreversible update also carries `updateHint` |
414
-
415
-The MCP annotation tags `idempotentHint` and `openWorldHint` are also accepted, but only some tools set them, so use the four above for access control.
416
-
417
-MCP-backed toolkits (managed ones such as `granola_mcp` and custom MCP toolkits) carry the same four tags. `readOnlyHint` comes from the server's annotations; every other tool is classified into `createHint`, `updateHint` or `destructiveHint` when the toolkit is synced. A toolkit not synced since classification was added may carry only the server's annotations, and an `enable` filter hides any tool without a matching tag.
418
-
419
-<Callout type="info">
420
-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.
421
-</Callout>
406
+Every tool has a tag for the type of action it takes: `readOnlyHint`, `createHint`, `updateHint` or `destructiveHint`. See [Tool tags](/docs/tool-tags) for what each one means and how tools get them.
407
408
To apply tag filters across all toolkits, pass `tags` at the session level:
409
docs/content/docs/meta.json
+1
@@ -16,6 +16,7 @@
16
"approval-mode",
17
"instant-tools",
18
"toolkits",
19
+ "tool-tags",
20
"authentication",
21
"triggers",
22
"skills",
docs/content/docs/tool-tags.mdx
new
+62
@@ -0,0 +1,62 @@
1
+---
2
+title: Tool tags
3
+description: How Composio tags each tool by the type of action it takes, and how sessions use the tags
4
+keywords: [tags, readOnlyHint, createHint, updateHint, destructiveHint, governance, permissions]
5
+---
6
+
7
+Every Composio tool has a tag for the type of action it takes: it reads, creates, updates or deletes. Sessions use these tags so you can decide what your agent may do by type of action, without listing every tool. For example, you can let the agent read anything, ask the user before it creates or updates something, and block deletes.
8
+
9
+## The four tags
10
+
11
+| Tag | Type of action | For example |
12
+|---|---|---|
13
+| `readOnlyHint` | Reads, searches, lists or computes something. Changes nothing | Fetch emails, list issues, export a report |
14
+| `createHint` | Adds something new | Send an email, open an issue, create a calendar event |
15
+| `updateHint` | Changes something that already exists | Edit an issue, rename a file, change a channel's topic |
16
+| `destructiveHint` | Can make something stop existing | Delete a file, remove a repository |
17
+
18
+## How a tool's tag is chosen
19
+
20
+A tool gets one tag. To choose it, ask these questions in order and stop at the first yes, so the most severe tag wins:
21
+
22
+```txt
23
+Can any call make something stop existing? → destructiveHint
24
+Can it change something that already exists? → updateHint
25
+Can it add something new? → createHint
26
+Otherwise → readOnlyHint
27
+```
28
+
29
+The tag describes what the user sees happen, not how the provider's API works:
30
+
31
+- A `POST` isn't always a create. An endpoint that takes a query and returns data is `readOnlyHint`.
32
+- A `GET` isn't always a read. Endpoints that cancel, reset or resend something change state.
33
+- Returning output isn't a change. Tools that compute, parse, convert, summarize or export data without changing anything are `readOnlyHint`.
34
+- Adding an item to a list or folder is `createHint`, even though the list now looks different.
35
+
36
+Some older tools still carry two tags, such as an upsert tagged `createHint` and `updateHint`. They're being moved to a single tag.
37
+
38
+## Where tags come from
39
+
40
+**Composio toolkits.** Each tool declares its tag in its definition, and CI reviews the tag against the tool's code with an automated check.
41
+
42
+**MCP toolkits.** Managed MCP toolkits, such as `granola_mcp`, and [custom MCP toolkits](/docs/extending-sessions/custom-mcp) take `readOnlyHint` from the MCP server's tool annotations. Every other tool is classified into `createHint`, `updateHint` or `destructiveHint` when the toolkit syncs. A toolkit that hasn't synced since classification was added may carry only the server's annotations. Tag rules don't reach a tool without a matching tag, and an `enable` filter hides it.
43
+
44
+To see a tool's tags, read its `tags` field with [Get a tool](/reference/api-reference/tools/getToolsByToolSlug). Sessions use the latest version of each tool, but 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 uses.
45
+
46
+## Using tags in a session
47
+
48
+Use the four tags to:
49
+
50
+- **Filter tools.** Hide tools by tag across the session or per toolkit. See [Filtering tools by tags](/docs/configuring-sessions#filtering-tools-by-tags).
51
+- **Ask first.** Have the session ask the user before tools with a tag run. See [Approval mode](/docs/approval-mode).
52
+
53
+Sessions also accept the MCP hints `idempotentHint` and `openWorldHint`, but only some tools set them, so don't use them for access control. Session configs in the Composio Dashboard only accept the four tags above.
54
+
55
+## Next
56
+
57
+<Card
58
+ icon={<Wrench />}
59
+ title="Approval mode"
60
+ href="/docs/approval-mode"
61
+ description="Allow, ask first or block each tag, and override them per toolkit."
62
+/>
docs/lib/home-navigation.ts
+2
-1
@@ -133,6 +133,7 @@ export const DOCS_PRODUCTS = {
133
'/docs/approval-mode',
134
'/docs/instant-tools',
135
'/docs/toolkits',
136
+ '/docs/tool-tags',
137
'/docs/authentication',
138
'/docs/triggers',
139
'/docs/skills',
@@ -174,7 +175,7 @@ export const DOCS_PRODUCTS = {
175
{
176
type: 'group',
177
label: 'Toolkits & Tools',
177
- links: [{ url: '/docs/toolkits' }, { url: '/docs/instant-tools' }],
178
+ links: [{ url: '/docs/toolkits' }, { url: '/docs/tool-tags' }, { url: '/docs/instant-tools' }],
179
},
180
{
181
type: 'group',
docs/tests/static/sidebar-nav-index.test.ts
+1
-1
@@ -66,7 +66,7 @@ describe('buildSidebarNavIndex', () => {
66
group: 'Core concepts',
67
folder: 'Authentication',
68
depth: 1,
69
- position: index['/docs/toolkits'].position + 1,
69
+ position: index['/docs/tool-tags'].position + 1,
70
});
71
});
72