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 22, 13:15 UTC
docs: polish fetching tools and toolkits page
- Reorder sections: session fetching first, catalog browsing second - Add pagination example with proper do-while pattern - Add filtering examples (isConnected, search) - Show toolkits and tools browsing in one snippet - Add tool schema inspection with all properties - Clarify default behavior (top 20 sorted by popularity) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh committed
Jan 26, 2026 at 17:41 UTC
cea2df5590677b02004da089117f15464c4e23f9
3 files changed
+461
-82
docs/content/docs/toolkits/enable-and-disable-toolkits.mdx
new
+371
@@ -0,0 +1,371 @@
1
+---
2
+title: Enable and disable toolkits
3
+description: Control which toolkits and tools are available in your sessions
4
+---
5
+
6
+When creating a session, you can control which toolkits are available to your agent. By default, all 800+ toolkits are discoverable, but you can restrict or exclude specific ones.
7
+
8
+## Enabling specific toolkits
9
+
10
+To limit your session to only specific toolkits, pass an array of toolkit slugs:
11
+
12
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
13
+<Tab value="Python">
14
+```python
15
+from composio import Composio
16
+
17
+composio = Composio()
18
+
19
+# Only GitHub and Gmail will be available
20
+session = composio.create(
21
+ user_id="user_123",
22
+ toolkits=["github", "gmail"]
23
+)
24
+```
25
+</Tab>
26
+<Tab value="TypeScript">
27
+```typescript
28
+import { Composio } from '@composio/core';
29
+const composio = new Composio({ apiKey: 'your_api_key' });
30
+// ---cut---
31
+// Only GitHub and Gmail will be available
32
+const session = await composio.create("user_123", {
33
+ toolkits: ["github", "gmail"]
34
+});
35
+```
36
+</Tab>
37
+</Tabs>
38
+
39
+You can also use the explicit `enable` syntax:
40
+
41
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
42
+<Tab value="Python">
43
+```python
44
+session = composio.create(
45
+ user_id="user_123",
46
+ toolkits={"enable": ["github", "gmail"]}
47
+)
48
+```
49
+</Tab>
50
+<Tab value="TypeScript">
51
+```typescript
52
+import { Composio } from '@composio/core';
53
+const composio = new Composio({ apiKey: 'your_api_key' });
54
+// ---cut---
55
+const session = await composio.create("user_123", {
56
+ toolkits: { enable: ["github", "gmail"] }
57
+});
58
+```
59
+</Tab>
60
+</Tabs>
61
+
62
+## Disabling specific toolkits
63
+
64
+To make all toolkits available except certain ones, use the `disable` syntax:
65
+
66
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
67
+<Tab value="Python">
68
+```python
69
+# All toolkits available except Linear and Jira
70
+session = composio.create(
71
+ user_id="user_123",
72
+ toolkits={"disable": ["linear", "jira"]}
73
+)
74
+```
75
+</Tab>
76
+<Tab value="TypeScript">
77
+```typescript
78
+import { Composio } from '@composio/core';
79
+const composio = new Composio({ apiKey: 'your_api_key' });
80
+// ---cut---
81
+// All toolkits available except Linear and Jira
82
+const session = await composio.create("user_123", {
83
+ toolkits: { disable: ["linear", "jira"] }
84
+});
85
+```
86
+</Tab>
87
+</Tabs>
88
+
89
+## Enabling or disabling specific tools
90
+
91
+You can also control which individual tools are available within a toolkit using the `tools` configuration. The key is the toolkit slug and the value specifies which tools to enable or disable.
92
+
93
+### Enable specific tools
94
+
95
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
96
+<Tab value="Python">
97
+```python
98
+session = composio.create(
99
+ user_id="user_123",
100
+ tools={
101
+ # Only these Gmail tools will be available
102
+ "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]},
103
+ # Only issue-related GitHub tools
104
+ "github": {"enable": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]}
105
+ }
106
+)
107
+```
108
+</Tab>
109
+<Tab value="TypeScript">
110
+```typescript
111
+import { Composio } from '@composio/core';
112
+const composio = new Composio({ apiKey: 'your_api_key' });
113
+// ---cut---
114
+const session = await composio.create("user_123", {
115
+ tools: {
116
+ // Only these Gmail tools will be available
117
+ gmail: { enable: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"] },
118
+ // Only issue-related GitHub tools
119
+ github: { enable: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"] }
120
+ }
121
+});
122
+```
123
+</Tab>
124
+</Tabs>
125
+
126
+You can also use the shorthand array syntax which is equivalent to `enable`:
127
+
128
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
129
+<Tab value="Python">
130
+```python
131
+session = composio.create(
132
+ user_id="user_123",
133
+ tools={
134
+ "gmail": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
135
+ "github": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
136
+ }
137
+)
138
+```
139
+</Tab>
140
+<Tab value="TypeScript">
141
+```typescript
142
+import { Composio } from '@composio/core';
143
+const composio = new Composio({ apiKey: 'your_api_key' });
144
+// ---cut---
145
+const session = await composio.create("user_123", {
146
+ tools: {
147
+ gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
148
+ github: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
149
+ }
150
+});
151
+```
152
+</Tab>
153
+</Tabs>
154
+
155
+### Disable specific tools
156
+
157
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
158
+<Tab value="Python">
159
+```python
160
+session = composio.create(
161
+ user_id="user_123",
162
+ tools={
163
+ # All Slack tools except delete
164
+ "slack": {"disable": ["SLACK_DELETE_MESSAGE"]},
165
+ # All GitHub tools except destructive ones
166
+ "github": {"disable": ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"]}
167
+ }
168
+)
169
+```
170
+</Tab>
171
+<Tab value="TypeScript">
172
+```typescript
173
+import { Composio } from '@composio/core';
174
+const composio = new Composio({ apiKey: 'your_api_key' });
175
+// ---cut---
176
+const session = await composio.create("user_123", {
177
+ tools: {
178
+ // All Slack tools except delete
179
+ slack: { disable: ["SLACK_DELETE_MESSAGE"] },
180
+ // All GitHub tools except destructive ones
181
+ github: { disable: ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"] }
182
+ }
183
+});
184
+```
185
+</Tab>
186
+</Tabs>
187
+
188
+## Filtering tools by tags
189
+
190
+Tools can be filtered by their behavior tags. Available tags are:
191
+
192
+| Tag | Description |
193
+|-----|-------------|
194
+| `readOnlyHint` | Tools that only read data |
195
+| `destructiveHint` | Tools that delete or permanently modify data |
196
+| `idempotentHint` | Tools that can be safely retried |
197
+| `openWorldHint` | Tools that interact with external systems |
198
+
199
+### Global tag filtering
200
+
201
+Apply tag filters to all toolkits:
202
+
203
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
204
+<Tab value="Python">
205
+```python
206
+# Only include read-only and idempotent tools
207
+session = composio.create(
208
+ user_id="user_123",
209
+ tags=["readOnlyHint", "idempotentHint"]
210
+)
211
+
212
+# Enable some tags, disable others
213
+session = composio.create(
214
+ user_id="user_123",
215
+ tags={
216
+ "enable": ["readOnlyHint"],
217
+ "disable": ["destructiveHint"]
218
+ }
219
+)
220
+```
221
+</Tab>
222
+<Tab value="TypeScript">
223
+```typescript
224
+import { Composio } from '@composio/core';
225
+const composio = new Composio({ apiKey: 'your_api_key' });
226
+// ---cut---
227
+// Only include read-only and idempotent tools
228
+const session = await composio.create("user_123", {
229
+ tags: ["readOnlyHint", "idempotentHint"]
230
+});
231
+
232
+// Enable some tags, disable others
233
+const sessionWithTagConfig = await composio.create("user_123", {
234
+ tags: {
235
+ enable: ["readOnlyHint"],
236
+ disable: ["destructiveHint"]
237
+ }
238
+});
239
+```
240
+</Tab>
241
+</Tabs>
242
+
243
+### Per-toolkit tag filtering
244
+
245
+Override global tags for specific toolkits:
246
+
247
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
248
+<Tab value="Python">
249
+```python
250
+session = composio.create(
251
+ user_id="user_123",
252
+ # Global: only read-only tools
253
+ tags=["readOnlyHint"],
254
+ tools={
255
+ # Override for GitHub: allow all tools except destructive
256
+ "github": {"tags": {"disable": ["destructiveHint"]}},
257
+ # Override for Gmail: only read-only tools (explicit)
258
+ "gmail": {"tags": ["readOnlyHint"]}
259
+ }
260
+)
261
+```
262
+</Tab>
263
+<Tab value="TypeScript">
264
+```typescript
265
+import { Composio } from '@composio/core';
266
+const composio = new Composio({ apiKey: 'your_api_key' });
267
+// ---cut---
268
+const session = await composio.create("user_123", {
269
+ // Global: only read-only tools
270
+ tags: ["readOnlyHint"],
271
+ tools: {
272
+ // Override for GitHub: allow all tools except destructive
273
+ github: { tags: { disable: ["destructiveHint"] } },
274
+ // Override for Gmail: only read-only tools (explicit)
275
+ gmail: { tags: ["readOnlyHint"] }
276
+ }
277
+});
278
+```
279
+</Tab>
280
+</Tabs>
281
+
282
+## Common patterns
283
+
284
+### Read-only session for browsing
285
+
286
+Create a safe session that can only read data:
287
+
288
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
289
+<Tab value="Python">
290
+```python
291
+session = composio.create(
292
+ user_id="user_123",
293
+ tags=["readOnlyHint"]
294
+)
295
+```
296
+</Tab>
297
+<Tab value="TypeScript">
298
+```typescript
299
+import { Composio } from '@composio/core';
300
+const composio = new Composio({ apiKey: 'your_api_key' });
301
+// ---cut---
302
+const session = await composio.create("user_123", {
303
+ tags: ["readOnlyHint"]
304
+});
305
+```
306
+</Tab>
307
+</Tabs>
308
+
309
+### Restricted toolkits with full tool access
310
+
311
+Limit to specific services but allow all their tools:
312
+
313
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
314
+<Tab value="Python">
315
+```python
316
+session = composio.create(
317
+ user_id="user_123",
318
+ toolkits=["github", "linear", "slack"]
319
+)
320
+```
321
+</Tab>
322
+<Tab value="TypeScript">
323
+```typescript
324
+import { Composio } from '@composio/core';
325
+const composio = new Composio({ apiKey: 'your_api_key' });
326
+// ---cut---
327
+const session = await composio.create("user_123", {
328
+ toolkits: ["github", "linear", "slack"]
329
+});
330
+```
331
+</Tab>
332
+</Tabs>
333
+
334
+### Granular control per toolkit
335
+
336
+Different restrictions for different services:
337
+
338
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
339
+<Tab value="Python">
340
+```python
341
+session = composio.create(
342
+ user_id="user_123",
343
+ toolkits=["github", "gmail", "slack"],
344
+ tools={
345
+ # Full access to GitHub
346
+ # Gmail: only send and fetch
347
+ "gmail": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
348
+ # Slack: everything except delete
349
+ "slack": {"disable": ["SLACK_DELETE_MESSAGE"]}
350
+ }
351
+)
352
+```
353
+</Tab>
354
+<Tab value="TypeScript">
355
+```typescript
356
+import { Composio } from '@composio/core';
357
+const composio = new Composio({ apiKey: 'your_api_key' });
358
+// ---cut---
359
+const session = await composio.create("user_123", {
360
+ toolkits: ["github", "gmail", "slack"],
361
+ tools: {
362
+ // Full access to GitHub
363
+ // Gmail: only send and fetch
364
+ gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
365
+ // Slack: everything except delete
366
+ slack: { disable: ["SLACK_DELETE_MESSAGE"] }
367
+ }
368
+});
369
+```
370
+</Tab>
371
+</Tabs>
docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx
+88
-81
@@ -1,175 +1,182 @@
1
---
2
title: Fetching tools and toolkits
3
-description: How to browse Composio's catalog and fetch tools for your sessions
3
+description: How to fetch tools and toolkits for sessions and browse the catalog
4
---
5
6
-There are two ways to explore tools and toolkits:
6
+## Fetching for a session
7
8
-1. **Browse the catalog** - Discover what toolkits Composio offers
9
-2. **Fetch for a session** - Get tools enabled for a session
8
+When using sessions, fetch tools through the session object.
9
11
-## Browsing Composio's catalog
10
+### List enabled toolkits
11
13
-Composio offers 800+ toolkits. You can explore the full catalog to discover what's available.
12
+`session.toolkits()` returns toolkits enabled for your session, sorted by popularity. By default, it returns the top 20. Each toolkit includes its `slug`, `name`, `logo`, and connection status.
13
15
-### Using the platform
14
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
15
+<Tab value="Python">
16
+```python
17
+session = composio.create(user_id="user_123")
18
17
-Browse all toolkits at [platform.composio.dev](https://platform.composio.dev). Each toolkit page shows:
18
-- Available tools with input/output parameters
19
-- Supported authentication methods
20
-- Required OAuth scopes
19
+result = session.toolkits()
20
22
-You can also browse toolkits directly in these docs:
21
+for toolkit in result.items:
22
+ print(f"{toolkit.name}: connected={toolkit.connection.is_active if toolkit.connection else 'n/a'}")
23
+```
24
+</Tab>
25
+<Tab value="TypeScript">
26
+```typescript
27
+import { Composio } from '@composio/core';
28
+const composio = new Composio({ apiKey: 'your_api_key' });
29
+// ---cut---
30
+const session = await composio.create("user_123");
31
24
-<Card icon={<Blocks />} title="Browse all toolkits" href="/toolkits">
25
- Explore 800+ available toolkits with their tools and authentication methods
26
-</Card>
32
+const result = await session.toolkits();
33
28
-### Using the SDK
34
+for (const toolkit of result.items) {
35
+ console.log(`${toolkit.name}: connected=${toolkit.connection?.isActive ?? 'n/a'}`);
36
+}
37
+```
38
+</Tab>
39
+</Tabs>
40
30
-List available toolkits programmatically:
41
+You can filter to only connected toolkits or search by name:
42
43
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
44
<Tab value="Python">
45
```python
35
-from composio import Composio
36
-
37
-composio = Composio()
38
-
39
-# List available toolkits (top 20 by default)
40
-toolkits = composio.toolkits.get()
41
-
42
-for toolkit in toolkits:
43
- print(f"{toolkit.name} - {toolkit.meta.tools_count} tools")
46
+result = session.toolkits(is_connected=True) # Only connected
47
+result = session.toolkits(search="github") # Search by name
48
```
49
</Tab>
50
<Tab value="TypeScript">
51
```typescript
52
import { Composio } from '@composio/core';
53
const composio = new Composio({ apiKey: 'your_api_key' });
54
+const session = await composio.create("user_123");
55
// ---cut---
51
-// List available toolkits (top 20 by default)
52
-const toolkits = await composio.toolkits.get();
53
-
54
-for (const toolkit of toolkits) {
55
- console.log(`${toolkit.name} - ${toolkit.meta.toolsCount} tools`);
56
-}
56
+const connected = await session.toolkits({ isConnected: true }); // Only connected
57
+const searched = await session.toolkits({ search: "github" }); // Search by name
58
```
59
</Tab>
60
</Tabs>
61
61
-Get a specific toolkit's details:
62
+To fetch all toolkits, paginate through the results:
63
64
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
65
<Tab value="Python">
66
```python
66
-# Get details for a specific toolkit
67
-github = composio.toolkits.get_by_slug("github")
68
-print(github.meta.description)
67
+all_toolkits = []
68
+cursor = None
69
+
70
+while True:
71
+ result = session.toolkits(limit=20, next_cursor=cursor)
72
+ all_toolkits.extend(result.items)
73
+ cursor = result.next_cursor
74
+ if not cursor:
75
+ break
76
```
77
</Tab>
78
<Tab value="TypeScript">
79
```typescript
80
import { Composio } from '@composio/core';
81
const composio = new Composio({ apiKey: 'your_api_key' });
82
+const session = await composio.create("user_123");
83
// ---cut---
76
-// Get details for a specific toolkit
77
-const github = await composio.toolkits.getBySlug("github");
78
-console.log(github.meta.description);
84
+const allToolkits: any[] = [];
85
+let cursor: string | undefined;
86
+
87
+do {
88
+ const { items, nextCursor } = await session.toolkits({ limit: 20, nextCursor: cursor });
89
+ allToolkits.push(...items);
90
+ cursor = nextCursor;
91
+} while (cursor);
92
```
93
</Tab>
94
</Tabs>
95
83
-Get a specific tool's schema:
96
+### Get meta tools
97
+
98
+`session.tools()` returns the 5 meta tools formatted for your configured provider (OpenAI, Anthropic, etc.):
99
100
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
101
<Tab value="Python">
102
```python
88
-# Get schema for a specific tool
89
-tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
90
-print(tool.input_parameters)
103
+# Get all meta tools
104
+tools = session.tools()
105
```
106
</Tab>
107
<Tab value="TypeScript">
108
```typescript
109
import { Composio } from '@composio/core';
110
const composio = new Composio({ apiKey: 'your_api_key' });
111
+const session = await composio.create("user_123");
112
// ---cut---
98
-// Get schema for a specific tool
99
-const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");
100
-console.log(tool.inputParameters);
113
+// Get all meta tools
114
+const tools = await session.tools();
115
```
116
</Tab>
117
</Tabs>
118
105
-## Fetching tools for a session
119
+To restrict which toolkits or tools are discoverable by the meta tools, configure them when [creating the session](/docs/toolkits/enable-and-disable-toolkits).
120
107
-Once you create a session for a user, you can fetch tools and check which toolkits are enabled.
121
+## Browsing the catalog
122
109
-### List enabled toolkits
123
+### Browse toolkits and tools
124
111
-`session.toolkits()` returns toolkits enabled for the session along with their connection status:
125
+You can explore all 800+ toolkits at [platform.composio.dev](https://platform.composio.dev) or in the [docs](/toolkits).
126
127
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
128
<Tab value="Python">
129
```python
116
-session = composio.create(user_id="user_123")
130
+from composio import Composio
131
118
-# List toolkits enabled for this session
119
-toolkits = session.toolkits()
132
+composio = Composio()
133
+
134
+# List toolkits
135
+toolkits = composio.toolkits.get()
136
121
-for toolkit in toolkits:
122
- print(f"{toolkit.name}: {toolkit.connection_status}")
137
+# List tools within a toolkit
138
+tools = composio.tools.get(user_id, toolkits=["GITHUB"])
139
```
140
</Tab>
141
<Tab value="TypeScript">
142
```typescript
143
import { Composio } from '@composio/core';
144
const composio = new Composio({ apiKey: 'your_api_key' });
145
+const userId = 'user_123';
146
// ---cut---
130
-const session = await composio.create("user_123");
131
-
132
-// List toolkits enabled for this session
133
-const toolkits = await session.toolkits();
147
+// List toolkits
148
+const toolkits = await composio.toolkits.get();
149
135
-for (const toolkit of toolkits) {
136
- console.log(`${toolkit.name}: ${toolkit.connectionStatus}`);
137
-}
150
+// List tools within a toolkit
151
+const tools = await composio.tools.get(userId, { toolkits: ["GITHUB"] });
152
```
153
</Tab>
154
</Tabs>
155
142
-The connection status tells you if the user has authenticated with that toolkit.
156
+### Get a tool's schema
157
144
-### Get tools for your AI framework
145
-
146
-`session.tools()` returns tools formatted for your AI provider:
158
+To inspect a tool's input parameters and types without needing a user context, use `getRawComposioToolBySlug`:
159
160
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
161
<Tab value="Python">
162
```python
151
-# Get tools from specific toolkits
152
-tools = session.tools(toolkits=["github", "gmail"])
153
-
154
-# Or get specific tools by name
155
-tools = session.tools(tools=["GITHUB_CREATE_ISSUE", "GMAIL_SEND_EMAIL"])
163
+tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
164
+print(tool.name)
165
+print(tool.description)
166
+print(tool.input_parameters)
167
+print(tool.output_parameters)
168
```
169
</Tab>
170
<Tab value="TypeScript">
171
```typescript
172
import { Composio } from '@composio/core';
173
const composio = new Composio({ apiKey: 'your_api_key' });
162
-const session = await composio.create("user_123");
174
// ---cut---
164
-// Get tools from specific toolkits
165
-const tools = await session.tools({ toolkits: ["github", "gmail"] });
166
-
167
-// Or get specific tools by name
168
-const specificTools = await session.tools({
169
- tools: ["GITHUB_CREATE_ISSUE", "GMAIL_SEND_EMAIL"]
170
-});
175
+const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");
176
+console.log(tool.name);
177
+console.log(tool.description);
178
+console.log(tool.inputParameters);
179
+console.log(tool.outputParameters);
180
```
181
</Tab>
182
</Tabs>
174
-
175
-Tools are automatically formatted for your configured provider (OpenAI, Anthropic, etc.).
docs/content/docs/toolkits/meta.json
+2
-1
@@ -1,6 +1,7 @@
1
{
2
"title": "Toolkits",
3
"pages": [
4
- "fetching-tools-and-toolkits"
4
+ "fetching-tools-and-toolkits",
5
+ "enable-and-disable-toolkits"
6
]
7
}