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: simplify tool tags and approval wording
Removes internal details from the tool tags page, explains how tools are tagged as a fact rather than a checklist, and uses "require approval" consistently across the three pages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 15:39 UTC
f3cb14f89decf174f56d9783fb096fd32ff43320
5 files changed
+44
-58
docs/content/docs/approval-mode.mdx
+16
-16
@@ -14,7 +14,7 @@ Approval mode is experimental, and its SDK options may change. Answering questio
14
15
## Requiring approval
16
17
-You choose which tools ask first when you create or update a session.
17
+You choose which tools need approval when you create or update a session.
18
19
### By type of tool
20
@@ -27,7 +27,7 @@ Every tool has a [tag](/docs/tool-tags) for the type of action it takes:
27
| `updateHint` | Update |
28
| `destructiveHint` | Destructive |
29
30
-To make every tool of a type ask first, add its tag to `tags.require_approval`. Tools whose tags you leave out run without asking, and tools whose tags are in `tags.disable` are [blocked](/docs/configuring-sessions#filtering-tools-by-tags). For example, to ask before tools that create or update, and block tools that delete:
30
+To require approval for every tool of a type, add its tag to `tags.require_approval`. Tools whose tags you leave out run without approval, and tools whose tags are in `tags.disable` are [blocked](/docs/configuring-sessions#filtering-tools-by-tags). For example, to require approval for tools that create or update, and block tools that delete:
31
32
```python
33
tags={
@@ -40,7 +40,7 @@ tags={
40
41
The session-wide `tags` apply to the tools of every toolkit. To handle a toolkit's tools differently, override them under `tools.<toolkit>`. The override replaces the session-wide `tags` for that toolkit, so it has to cover all of its tools. You can override by type or tool by tool.
42
43
-**By type.** Set `tools.<toolkit>.tags` the same way as the session-wide `tags`, and repeat anything from them you still want for the toolkit. For example, this override makes GitHub's tools that delete ask first instead of being blocked. Tools that create or update are listed again so they still ask first:
43
+**By type.** Set `tools.<toolkit>.tags` the same way as the session-wide `tags`, and repeat anything from them you still want for the toolkit. For example, this override makes GitHub's tools that delete need approval instead of being blocked. Tools that create or update are listed again so they still need approval:
44
45
```python
46
tools={
@@ -50,7 +50,7 @@ tools={
50
}
51
```
52
53
-**Tool by tool.** List the tools the agent can use in `tools.<toolkit>.enable`, and the ones that ask first in `tools.<toolkit>.require_approval`. Tools you leave out are blocked, including tools added to the toolkit later. For example, this override lets the agent fetch and send Gmail, and asks before sending:
53
+**Tool by tool.** List the tools the agent can use in `tools.<toolkit>.enable`, and the ones that need approval in `tools.<toolkit>.require_approval`. Tools you leave out are blocked, including tools added to the toolkit later. For example, this override lets the agent fetch and send Gmail, and requires approval to send:
54
55
```python
56
tools={
@@ -61,7 +61,7 @@ tools={
61
}
62
```
63
64
-Always set `require_approval` in a tool-by-tool override, even to `[]`. Without it, the tools you list still ask first if the session-wide `tags` say so.
64
+Always set `require_approval` in a tool-by-tool override, even to `[]`. Without it, the session-wide `tags.require_approval` still applies to the tools you list.
65
66
Use one or the other for a toolkit, not both.
67
@@ -117,11 +117,11 @@ const session = await composio.create('user_123', {
117
118
With this session:
119
120
-- **GitHub** is overridden by type. Tools that read run freely, and tools that create, update or delete ask first.
121
-- **Gmail** is overridden tool by tool. Fetching emails runs freely, sending asks first, and no other Gmail tools are available.
122
-- **Any other toolkit** isn't enabled. If you enabled one without an override, the session-wide `tags` would apply to its tools: tools that read run freely, tools that create or update ask first, and tools that delete are blocked.
120
+- **GitHub** is overridden by type. Tools that read run without approval, and tools that create, update or delete need approval.
121
+- **Gmail** is overridden tool by tool. Fetching emails runs without approval, sending needs approval, and no other Gmail tools are available.
122
+- **Any other toolkit** isn't enabled. If you enabled one without an override, the session-wide `tags` would apply to its tools: tools that read run without approval, tools that create or update need approval, and tools that delete are blocked.
123
124
-Asking first doesn't hide a tool from the agent. It can still find and call it, and the call waits for the user's approval. This also applies to each tool call inside `COMPOSIO_MULTI_EXECUTE_TOOL`, the meta tool agents use to run app tools. A batch with two calls that need approval comes back with two questions.
124
+Tools that need approval stay visible to the agent. It can find and call them, and each call waits for the user's approval. This includes calls the agent makes through `COMPOSIO_MULTI_EXECUTE_TOOL`: a batch with two calls that need approval returns two questions.
125
126
## Asking the user
127
@@ -164,7 +164,7 @@ try {
164
</Tab>
165
</Tabs>
166
167
-`input_requests` (`inputRequests` in TypeScript) holds the questions for the user, keyed by an ID you'll answer them under:
167
+`input_requests` (`inputRequests` in TypeScript) holds the questions for the user, keyed by question ID:
168
169
```json
170
{
@@ -191,9 +191,9 @@ try {
191
}
192
```
193
194
-Each question is an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Your app can show the `message` to the user, along with a form built from `requested_schema` (`requestedSchema` in TypeScript). This is a JSON Schema for the answer. As in MCP form mode, it's a flat object whose fields are strings, numbers, booleans, or single- or multi-select enums. Build the form from the schema rather than hard-coding the choices, because different questions offer different ones.
194
+Each question is an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Show the user its `message` and a form built from `requested_schema` (`requestedSchema` in TypeScript), which is a JSON Schema for the answer. Build the form from the schema rather than hard-coding the choices, because questions can offer different ones.
195
196
-`request_state` (`requestState` in TypeScript) is state you send back with the answer. The SDK keeps it out of the error's message, logs and serialized output, so read it from the attribute.
196
+You send `request_state` (`requestState` in TypeScript) back with the answer. It's left out of the error's message and logs, so read it from the attribute.
197
198
## Sending the answer
199
@@ -237,7 +237,7 @@ const result = await session.execute('GMAIL_SEND_EMAIL', args, {
237
</Tab>
238
</Tabs>
239
240
-Send the same tool and arguments. The question's ID comes from the call, so a call with different arguments is a new question.
240
+Use the same tool and arguments as the original call. A call with different arguments needs its own approval.
241
242
If the user approves, the tool runs and `result_type` is `completed`. If they deny it, or the answer's `action` is `decline` or `cancel`, the tool doesn't run and `result_type` is `failed`, with an error you can pass back to the agent.
243
@@ -428,7 +428,7 @@ terminal.close();
428
</Tab>
429
</Tabs>
430
431
-Running it, the agent searches for the Gmail tool, then asks to send the email through `COMPOSIO_MULTI_EXECUTE_TOOL`. Before anything is sent, you see:
431
+When you run it, the agent asks to send the email, and you see:
432
433
```txt
434
Your agent wants to run the following tool:
@@ -448,7 +448,7 @@ In a web app, the user answers in your UI, perhaps minutes later, so you can't w
448
449
Then send the questions to your frontend and end the request. When the user answers, call `session.execute()` again with the saved tool name and arguments, their answers in `input_responses`, and the saved `request_state`. Add the result to the conversation as that tool call's result, and continue the agent loop.
450
451
-Keep `request_state` on your server. It's only meaningful to Composio, so don't send it to the browser.
451
+Keep `request_state` on your server, not in the browser.
452
453
## Using MCP
454
@@ -494,7 +494,7 @@ While approval mode is experimental, only `session.execute()` and `session.execu
494
495
- **Providers.** `handle_tool_calls` (`handleToolCalls` in TypeScript) and the tools that framework providers wrap don't ask the user. Depending on the provider, a call that needs approval either raises the error or returns it to the agent as a tool error. Run tool calls with `session.execute()`, as in the example above.
496
- **Custom tools.** If a [custom tool](/docs/extending-sessions/custom-tools-and-toolkits) runs a tool that needs approval through `ctx.execute()`, it raises the error, and there's no way to pass the answer back through the custom tool yet.
497
-- **Proxy execute.** A proxy request can't be matched to a tool, so it can't be approved. `session.proxy_execute()` (`proxyExecute()` in TypeScript) is disabled for any toolkit where approval could apply to one of its tools.
497
+- **Proxy execute.** `session.proxy_execute()` (`proxyExecute()` in TypeScript) is disabled for a toolkit when any of its tools can need approval.
498
499
## Next
500
docs/content/docs/configuring-sessions.mdx
+1
-1
@@ -407,7 +407,7 @@ Every tool has a [tag](/docs/tool-tags) for the type of action it takes: `readOn
407
408
- **Allow:** leave the tag out. This is the default.
409
- **Block:** add the tag to `tags.disable`. The agent can't see or call these tools.
410
-- **Ask first:** add the tag to `tags.require_approval`. The agent can call these tools, but the session asks the user before they run. See [Approval mode](/docs/approval-mode).
410
+- **Require approval:** add the tag to `tags.require_approval`. These tools wait for the user's approval before they run. See [Approval mode](/docs/approval-mode).
411
412
For example, to block every tool that can delete something:
413
docs/content/docs/tool-tags.mdx
+23
-37
@@ -1,57 +1,43 @@
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
3
+description: How Composio tags each tool by the 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.
7
+Every tool has a **tag** that describes the action it takes: reading, creating, updating or deleting. Sessions use tags to allow, block or require approval for tools by type, instead of listing tools one by one.
8
9
-## The four tags
9
+## 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 |
11
+| Tag | The tool | For example |
12
+| --- | --- | --- |
13
+| `readOnlyHint` | Reads data and changes nothing | Fetch emails, list pull requests, export a report |
14
+| `createHint` | Adds something new | Send an email, create an issue |
15
+| `updateHint` | Changes something that already exists | Edit an issue, rename a file |
16
+| `destructiveHint` | Deletes something | Delete a file, delete a repository |
17
18
-## How a tool's tag is chosen
18
+## How tools are tagged
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:
20
+Composio tags each tool with the most severe action it can take. A tool that can delete something is tagged `destructiveHint`, even if it also updates. A tool that changes something that already exists is tagged `updateHint`. A tool that only adds something new is tagged `createHint`. Every other tool is tagged `readOnlyHint`.
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
-```
22
+A tool's tag reflects what changes for the user, not the HTTP method of the API behind it:
23
29
-The tag describes what the user sees happen, not how the provider's API works:
24
+- A tool that sends a search query with `POST` and returns results is `readOnlyHint`.
25
+- A tool that cancels or resets something with `GET` is `updateHint` or `destructiveHint`.
26
+- A tool that computes, converts, summarizes or exports data without changing anything is `readOnlyHint`.
27
+- A tool that adds an item to a list or folder is `createHint`.
28
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.
29
+In MCP toolkits, such as `granola_mcp` and [custom MCP toolkits](/docs/extending-sessions/custom-mcp), `readOnlyHint` comes from the MCP server's tool annotations, and Composio tags the server's other tools when the toolkit syncs.
30
36
-Some older tools still carry two tags, such as an upsert tagged `createHint` and `updateHint`. They're being moved to a single tag.
31
+## Viewing a tool's tags
32
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.
33
+[Get a tool](/reference/api-reference/tools/getToolsByToolSlug) returns its tags in the `tags` field. Pass `version=latest` to see the tags a session uses.
34
35
## Using tags in a session
36
48
-A session uses the tags to decide what happens to each type of tool:
49
-
50
-- **Allow:** the tools run without asking. This is the default.
51
-- **Block:** the agent can't see or call the tools. See [Filtering tools by tags](/docs/configuring-sessions#filtering-tools-by-tags).
52
-- **Ask first:** the tools wait for the user's approval. See [Approval mode](/docs/approval-mode).
37
+A session can allow, block or require approval for tools by their tag, and override this for specific toolkits:
38
54
-You set this for the whole session, then override it for specific toolkits.
39
+- To block tools, see [Filtering tools by tags](/docs/configuring-sessions#filtering-tools-by-tags).
40
+- To require approval, see [Approval mode](/docs/approval-mode).
41
42
## Next
43
@@ -59,5 +45,5 @@ You set this for the whole session, then override it for specific toolkits.
45
icon={<Wrench />}
46
title="Approval mode"
47
href="/docs/approval-mode"
62
- description="Allow, ask first or block each tag, and override them per toolkit."
48
+ description="Require the user's approval before tools run."
49
/>
python/docs/tool-router.md
+2
-2
@@ -159,10 +159,10 @@ session = composio.tool_router.create(
159
```
160
161
Every tool has a tag for the type of action it takes:
162
-- `'readOnlyHint'`: reads, searches, lists or computes something, and changes nothing
162
+- `'readOnlyHint'`: reads data and changes nothing
163
- `'createHint'`: adds something new
164
- `'updateHint'`: changes something that already exists
165
-- `'destructiveHint'`: can make something stop existing
165
+- `'destructiveHint'`: deletes something
166
167
See [Tool tags](https://docs.composio.dev/docs/tool-tags) for how tools get their tags.
168
ts/docs/api/tool-router.md
+2
-2
@@ -159,10 +159,10 @@ const session = await composio.create('user_123', {
159
160
Every tool has a tag for the type of action it takes:
161
162
-- `readOnlyHint` - reads, searches, lists or computes something, and changes nothing
162
+- `readOnlyHint` - reads data and changes nothing
163
- `createHint` - adds something new
164
- `updateHint` - changes something that already exists
165
-- `destructiveHint` - can make something stop existing
165
+- `destructiveHint` - deletes something
166
167
See [Tool tags](https://docs.composio.dev/docs/tool-tags) for how tools get their tags.
168