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