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: frame toolkit settings as overrides of the global tags
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 15:03 UTC
7670ab63b9b42f0bf444f9106b7010e242cd501a
1 file changed
+12
-8
docs/content/docs/approval-mode.mdx
+12
-8
@@ -50,11 +50,13 @@ tags={
50
}
51
```
52
53
-### 3. Override toolkits
53
+### 3. Override the tags for a toolkit
54
55
-You can override step 2 for a toolkit, either by tag or by tool.
55
+The global `tags` from step 2 apply to every toolkit. To treat a toolkit differently, add an override for it under `tools.<toolkit>`.
56
57
-**By tag.** Set `tools.<toolkit>.tags`, the same way as step 2. This replaces the session-wide `tags` for that toolkit rather than adding to them, so list every tag you want it to ask about or block. For example, this lets GitHub's destructive actions run after the user approves them, rather than blocking them:
57
+An override replaces the global `tags` for that toolkit. The global `tags` no longer apply to it at all, so the override has to say everything about the toolkit. An override is either by tag or by tool.
58
+
59
+**By tag.** Set `tools.<toolkit>.tags` the same way as step 2. Repeat any global settings you still want for the toolkit. For example, this override makes GitHub's destructive actions ask first instead of being blocked. Creates and updates are listed again so they still ask first:
60
61
```python
62
tools={
@@ -64,7 +66,7 @@ tools={
66
}
67
```
68
67
-**By tool.** List the tools the agent can use in `tools.<toolkit>.enable`, and the ones to ask about first in `tools.<toolkit>.require_approval`. Tools you leave out are blocked, including tools added to the toolkit later. Always set `require_approval`, even to `[]`. Otherwise the session-wide `tags.require_approval` still applies to the listed tools. For example, this lets the agent read and send Gmail, and asks before sending:
69
+**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:
70
71
```python
72
tools={
@@ -75,6 +77,8 @@ tools={
77
}
78
```
79
80
+Always set `require_approval` in a by-tool override, even to `[]`. Without it, the global `tags.require_approval` isn't overridden and still applies to the listed tools.
81
+
82
Use one or the other for a toolkit, not both.
83
84
### Putting it together
@@ -127,11 +131,11 @@ const session = await composio.create('user_123', {
131
</Tab>
132
</Tabs>
133
130
-With this session, the agent can:
134
+With this session:
135
132
-- read GitHub freely, and create, update or delete things in GitHub after the user approves
133
-- fetch Gmail emails freely, and send emails after the user approves
134
-- use no other Gmail tools, and no other toolkits
136
+- **GitHub** has a by-tag override. Reads run freely, and creates, updates and deletes ask first.
137
+- **Gmail** has a by-tool override. Fetching emails runs freely, sending asks first, and no other Gmail tools are available.
138
+- **Any other toolkit** isn't enabled. If you enabled one without an override, the global `tags` would apply to it: reads run freely, creates and updates ask first, and destructive actions are blocked.
139
140
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.
141