@devries-cameron20 / composio-1 / commits / bc59f8921
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: 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