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, 07:15 UTC
docs: move governance guides
Brendan O'Leary committed
Nov 3, 2026 at 16:06 UTC
bc59f892143a65d4376847b193273eee04a38303
12 files changed
+87
-29
docs/content/docs/configuring-sessions.mdx
+4
-4
@@ -539,11 +539,11 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
539
540
## Filtering tools by tags
541
542
-Every tool has a [tag](/docs/tool-tags) for the type of action it takes: `readOnlyHint`, `createHint`, `updateHint` or `destructiveHint`. Use the tags to set what happens to each type of tool:
542
+Every tool has a [hint](/docs/governance/tool-hints) for the type of action it takes: `readOnlyHint`, `createHint`, `updateHint` or `destructiveHint`. Use the `tags` configuration to set what happens to each type of tool:
543
544
-- **Allow:** leave the tag out. This is the default.
545
-- **Block:** add the tag to `tags.disable`. The agent can't see or call these tools.
546
-- **Require approval:** add the tag to `tags.require_approval`. These tools wait for the user's approval before they run. See [Approvals](/docs/approvals).
544
+- **Allow:** leave the hint out. This is the default.
545
+- **Block:** add the hint to `tags.disable`. The agent can't see or call these tools.
546
+- **Require approval:** add the hint to `tags.require_approval`. These tools wait for the user's approval before they run. See [Approvals](/docs/governance/approvals).
547
548
For example, to block every tool that can delete something:
549
docs/content/docs/governance/approvals.mdx
renamed
+2
-2
@@ -15,7 +15,7 @@ Approvals are experimental. They need `composio` newer than 0.27.0 or `@composio
15
16
## Choosing which tools need approval
17
18
-You choose which tools need approval with their [tags](/docs/tool-tags) when you create a session. For example, this session asks the user before any tool that creates, updates or deletes something:
18
+You choose which tools need approval with their [hints](/docs/governance/tool-hints) when you create a session. For example, this session asks the user before any tool that creates, updates or deletes something:
19
20
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
21
<Tab value="Python">
@@ -308,7 +308,7 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
308
309
- **Workbench and bash scripts.** Composio uses a model to find the tools a `COMPOSIO_REMOTE_WORKBENCH` or `COMPOSIO_REMOTE_BASH_TOOL` script calls, so it can miss some. If approval must never be skipped, [disable the sandbox](/docs/configuring-sessions#disabling-the-sandbox).
310
- **Proxy execute.** `session.proxy_execute()` is currently disabled for a toolkit when any of its tools need approval.
311
-- **Tags.** Rules based on [tags](/docs/tool-tags) are only as accurate as the tags, which Composio assigns on a best-effort basis. List tools explicitly for anything you must gate.
311
+- **Hints.** Rules based on [hints](/docs/governance/tool-hints) are only as accurate as the hints, which Composio assigns on a best-effort basis. List tools explicitly for anything you must gate.
312
- **Providers.** The SDK's `handle_tool_calls` and framework providers don't handle approval yet. Run tool calls with `session.execute()`, as in the [full example](#full-example) below.
313
314
## Full example
docs/content/docs/governance/meta.json
new
+4
@@ -0,0 +1,4 @@
1
+{
2
+ "title": "Governance",
3
+ "pages": ["tool-hints", "approvals"]
4
+}
docs/content/docs/governance/tool-hints.mdx
renamed
+12
-12
@@ -1,36 +1,36 @@
1
---
2
-title: Tool tags
3
-description: How Composio tags each tool by the action it takes, and how sessions use the tags
2
+title: Tool hints
3
+description: How Composio classifies each tool by the action it takes, and how sessions use those hints
4
keywords: [tags, readOnlyHint, createHint, updateHint, destructiveHint, governance, permissions]
5
---
6
7
-Every tool has a **tag** that describes the action it takes: reading, creating, updating or deleting. In [sessions](/docs/configuring-sessions), you can use tags to configure the tools available in the session.
7
+Every tool has a **hint** that describes the action it takes: reading, creating, updating or deleting. In [sessions](/docs/configuring-sessions), you can use these hints to configure the tools available in the session.
8
9
-## Tags
9
+## Hints
10
11
-| Tag | The tool | For example |
11
+| Hint | The tool | For example |
12
| --- | --- | --- |
13
| `readOnlyHint` | Reads data without changing anything. This includes tools that search, list, compute or export data. | Fetch emails, list pull requests, export a report |
14
| `createHint` | Adds something new, such as a message, record or file. It doesn't change anything that already exists. | Send an email, create an issue |
15
| `updateHint` | Changes something that already exists, such as its content or settings. It doesn't delete anything. | Edit an issue, rename a file |
16
-| `destructiveHint` | Deletes something, such as a file, record or repository. A tool that can delete something has this tag, even if it also creates or updates. | Delete a file, delete a repository |
16
+| `destructiveHint` | Deletes something, such as a file, record or repository. A tool that can delete something has this hint, even if it also creates or updates. | Delete a file, delete a repository |
17
18
-## How tools are tagged
18
+## How tools get hints
19
20
-Composio tags tools on a best-effort basis, based on each tool's description and behavior. For MCP tools, Composio infers the tag from the tool's description and the hints the MCP server provides.
20
+Composio assigns hints on a best-effort basis, based on each tool's description and behavior. For MCP tools, Composio infers them from the tool's description and the hints the MCP server provides.
21
22
-## Using tags in a session
22
+## Using hints in a session
23
24
-A session can allow, block or require approval for tools by their tag, and override this for specific toolkits:
24
+A session can allow, block or require approval for tools by their hint, and override this for specific toolkits:
25
26
- To block tools, see [Filtering tools by tags](/docs/configuring-sessions#filtering-tools-by-tags).
27
-- To require approval, see [Approvals](/docs/approvals).
27
+- To require approval, see [Approvals](/docs/governance/approvals).
28
29
## Next
30
31
<Card
32
icon={<Wrench />}
33
title="Approvals"
34
- href="/docs/approvals"
34
+ href="/docs/governance/approvals"
35
description="Require the user's approval before tools run."
36
/>
docs/content/docs/meta.json
+2
-2
@@ -13,14 +13,14 @@
13
"how-composio-works",
14
"configuring-sessions",
15
"session-configs",
16
- "approvals",
16
"instant-tools",
17
"toolkits",
19
- "tool-tags",
18
"authentication",
19
"triggers",
20
"skills",
21
"---Governance---",
22
+ "governance/tool-hints",
23
+ "governance/approvals",
24
"firewall",
25
"---Guides---",
26
"consumer-agents",
docs/content/docs/production-readiness.mdx
+1
-1
@@ -62,7 +62,7 @@ Configure sessions with only the toolkits and tools required by the feature. Nar
62
63
Require explicit user confirmation before destructive or externally visible actions, such as sending a message, creating a purchase, or deleting data. Enforce product authorization before creating or restoring the session, especially for workspace-owned connections.
64
65
-See [Configuring sessions](/docs/configuring-sessions) for toolkit and tool filters, and [Approvals](/docs/approvals) to have a session ask the user before it runs the tools you choose.
65
+See [Configuring sessions](/docs/configuring-sessions) for toolkit and tool filters, and [Approvals](/docs/governance/approvals) to have a session ask the user before it runs the tools you choose.
66
67
## 5. Persist the right state
68
docs/content/docs/sessions-vs-direct-execution.mdx
+2
-2
@@ -13,7 +13,7 @@ A **session** is the runtime context Composio creates for one of your users with
13
Direct execution is a legacy interface that remains supported for existing integrations. We recommend sessions for new integrations and encourage existing users to [migrate to sessions](/docs/migration-guide/direct-to-sessions). Sessions handle runtime tool discovery, authentication, and execution.
14
</Callout>
15
16
-If your application needs a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. If you need approval before execution, use [approvals](/docs/approvals): the session asks the user before it runs the tools you choose, including calls inside meta tools that execute multiple app tools. The comparison below describes the tradeoffs when maintaining a direct-execution integration.
16
+If your application needs a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. If you need approval before execution, use [approvals](/docs/governance/approvals): the session asks the user before it runs the tools you choose, including calls inside meta tools that execute multiple app tools. The comparison below describes the tradeoffs when maintaining a direct-execution integration.
17
18
| | Sessions | Direct execution |
19
|---|---|---|
@@ -23,7 +23,7 @@ If your application needs a fixed tool set, consider the [direct tools preset](/
23
| **Memory** | Meta tools share context across calls, storing discovered IDs and relationships | You manage state between calls |
24
| **Auth** | [In-chat](/docs/authentication#in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/authentication/manually-authenticating) | You build the auth flow with [connect links](/docs/tools-direct/authenticating-tools) |
25
| **[Sandbox](/docs/sandbox/remote)** | Built in, large responses offloaded automatically | Not available |
26
-| **Human approval** | [Approvals](/docs/approvals) ask the user before the tools you choose run, including inside meta tools | You intercept before each call in your code |
26
+| **Human approval** | [Approvals](/docs/governance/approvals) ask the user before the tools you choose run, including inside meta tools | You intercept before each call in your code |
27
| **Latency** | Multiple LLM turns (search, then execute) | Single call |
28
29
Sessions are configurable. [Restrict toolkits](/docs/configuring-sessions), set [auth configs](/docs/auth-configuration/custom-auth-configs) for white-labeled OAuth, and pin [connected accounts](/docs/configuring-sessions#account-selection). See [Configuring Sessions](/docs/configuring-sessions) for the full list.
docs/lib/home-navigation.ts
+8
-5
@@ -130,11 +130,11 @@ export const DOCS_PRODUCTS = {
130
'/docs/how-composio-works',
131
'/docs/configuring-sessions',
132
'/docs/session-configs',
133
- '/docs/approvals',
133
+ '/docs/governance/approvals',
134
'/docs/firewall',
135
'/docs/instant-tools',
136
'/docs/toolkits',
137
- '/docs/tool-tags',
137
+ '/docs/governance/tool-hints',
138
'/docs/authentication',
139
'/docs/triggers',
140
'/docs/skills',
@@ -170,18 +170,21 @@ export const DOCS_PRODUCTS = {
170
{ url: '/docs/configuring-sessions' },
171
{ url: '/docs/session-configs' },
172
{ url: '/docs/sessions-via-mcp' },
173
- { url: '/docs/approvals' },
173
],
174
},
175
{
176
type: 'group',
177
label: 'Toolkits & Tools',
179
- links: [{ url: '/docs/toolkits' }, { url: '/docs/tool-tags' }, { url: '/docs/instant-tools' }],
178
+ links: [{ url: '/docs/toolkits' }, { url: '/docs/instant-tools' }],
179
},
180
{
181
type: 'group',
182
label: 'Governance',
184
- links: [{ url: '/docs/firewall' }],
183
+ links: [
184
+ { url: '/docs/governance/tool-hints' },
185
+ { url: '/docs/governance/approvals' },
186
+ { url: '/docs/firewall' },
187
+ ],
188
},
189
{
190
type: 'group',
docs/next.config.mjs
+21
@@ -193,6 +193,27 @@ const config = {
193
permanent: true,
194
},
195
// === end docs v3 reorganization redirects ===
196
+ // Governance guides moved to a shared route namespace.
197
+ {
198
+ source: '/docs/tool-tags',
199
+ destination: '/docs/governance/tool-hints',
200
+ permanent: true,
201
+ },
202
+ {
203
+ source: '/docs/tool-tags.:format(md|mdx)',
204
+ destination: '/docs/governance/tool-hints.md',
205
+ permanent: true,
206
+ },
207
+ {
208
+ source: '/docs/approvals',
209
+ destination: '/docs/governance/approvals',
210
+ permanent: true,
211
+ },
212
+ {
213
+ source: '/docs/approvals.:format(md|mdx)',
214
+ destination: '/docs/governance/approvals.md',
215
+ permanent: true,
216
+ },
217
{
218
source: '/',
219
destination: '/docs',
docs/tests/integration/redirects.test.ts
+4
@@ -32,6 +32,10 @@ const REDIRECTS = [
32
{ from: "/changelog", to: "/docs/changelog" },
33
{ from: "/docs/mcp-quickstart", to: "/docs/single-toolkit-mcp" },
34
{ from: "/docs/getting-started", to: "/docs/quickstart" },
35
+ { from: "/docs/tool-tags", to: "/docs/governance/tool-hints" },
36
+ { from: "/docs/tool-tags.md", to: "/docs/governance/tool-hints.md" },
37
+ { from: "/docs/approvals", to: "/docs/governance/approvals" },
38
+ { from: "/docs/approvals.md", to: "/docs/governance/approvals.md" },
39
{ from: "/docs/welcome", to: "/docs" },
40
{ from: "/docs/managed-authentication", to: "/docs/authentication" },
41
{ from: "/docs/workbench", to: "/docs/sandbox/remote" },
docs/tests/static/navigation.test.ts
+11
@@ -75,6 +75,17 @@ describe("Navigation - meta.json validity", () => {
75
"agent-setup",
76
]);
77
78
+ expect(
79
+ pages.slice(
80
+ pages.indexOf("---Governance---") + 1,
81
+ pages.indexOf("---Guides---")
82
+ )
83
+ ).toEqual([
84
+ "governance/tool-hints",
85
+ "governance/approvals",
86
+ "firewall",
87
+ ]);
88
+
89
expect(
90
pages.slice(
91
pages.indexOf("---Direct execution (legacy)---") + 1,
docs/tests/static/sidebar-nav-index.test.ts
+16
-1
@@ -61,12 +61,27 @@ describe('buildSidebarNavIndex', () => {
61
});
62
});
63
64
+ test('governance guides stay top-level within the Governance section', () => {
65
+ expect(index['/docs/governance/tool-hints']).toEqual({
66
+ group: 'Governance',
67
+ folder: null,
68
+ depth: 1,
69
+ position: 1,
70
+ });
71
+ expect(index['/docs/governance/approvals']).toEqual({
72
+ group: 'Governance',
73
+ folder: null,
74
+ depth: 1,
75
+ position: 2,
76
+ });
77
+ });
78
+
79
test('folder index pages resolve to the folder row', () => {
80
expect(index['/docs/authentication']).toEqual({
81
group: 'Core concepts',
82
folder: 'Authentication',
83
depth: 1,
69
- position: index['/docs/tool-tags'].position + 1,
84
+ position: index['/docs/toolkits'].position + 1,
85
});
86
});
87