@devries-cameron20 / composio Mirror · read-only / commits / 1405f4f1d
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 13:15 UTC

docs: improve tools and toolkits concept page

- Rewrite intro to explain context management problem and meta tools solution - Add detailed workflow showing what each meta tool returns - Add section explaining what SEARCH_TOOLS returns (schemas, connection status, execution plan, related tools) - Add section on when to use REMOTE_WORKBENCH vs REMOTE_BASH_TOOL - Mention session_id correlation and memory feature - Simplify Toolkits and Tools into one concise section - Add callout for direct tool execution as alternative - Update fetching-tools-and-toolkits guide to bifurcate catalog browsing vs session fetching Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Sushmithamallesh committed Jan 26, 2026 at 14:11 UTC 1405f4f1dfc29821fdcad46f47228b684f7182f6
2 files changed +240 -64
docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx
+171 -1
@@ -1,5 +1,175 @@
1 ---
2 title: Fetching tools and toolkits
3 -description: How to fetch and filter tools and toolkits for your AI agents
3 +description: How to browse Composio's catalog and fetch tools for your sessions
4 ---
5
6 +There are two ways to explore tools and toolkits:
7 +
8 +1. **Browse the catalog** - Discover what toolkits Composio offers
9 +2. **Fetch for a session** - Get tools enabled for a session
10 +
11 +## Browsing Composio's catalog
12 +
13 +Composio offers 800+ toolkits. You can explore the full catalog to discover what's available.
14 +
15 +### Using the platform
16 +
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
21 +
22 +You can also browse toolkits directly in these docs:
23 +
24 +<Card icon={<Blocks />} title="Browse all toolkits" href="/toolkits">
25 + Explore 800+ available toolkits with their tools and authentication methods
26 +</Card>
27 +
28 +### Using the SDK
29 +
30 +List available toolkits programmatically:
31 +
32 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
33 +<Tab value="Python">
34 +```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")
44 +```
45 +</Tab>
46 +<Tab value="TypeScript">
47 +```typescript
48 +import { Composio } from '@composio/core';
49 +const composio = new Composio({ apiKey: 'your_api_key' });
50 +// ---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 +}
57 +```
58 +</Tab>
59 +</Tabs>
60 +
61 +Get a specific toolkit's details:
62 +
63 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
64 +<Tab value="Python">
65 +```python
66 +# Get details for a specific toolkit
67 +github = composio.toolkits.get_by_slug("github")
68 +print(github.meta.description)
69 +```
70 +</Tab>
71 +<Tab value="TypeScript">
72 +```typescript
73 +import { Composio } from '@composio/core';
74 +const composio = new Composio({ apiKey: 'your_api_key' });
75 +// ---cut---
76 +// Get details for a specific toolkit
77 +const github = await composio.toolkits.getBySlug("github");
78 +console.log(github.meta.description);
79 +```
80 +</Tab>
81 +</Tabs>
82 +
83 +Get a specific tool's schema:
84 +
85 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
86 +<Tab value="Python">
87 +```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)
91 +```
92 +</Tab>
93 +<Tab value="TypeScript">
94 +```typescript
95 +import { Composio } from '@composio/core';
96 +const composio = new Composio({ apiKey: 'your_api_key' });
97 +// ---cut---
98 +// Get schema for a specific tool
99 +const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");
100 +console.log(tool.inputParameters);
101 +```
102 +</Tab>
103 +</Tabs>
104 +
105 +## Fetching tools for a session
106 +
107 +Once you create a session for a user, you can fetch tools and check which toolkits are enabled.
108 +
109 +### List enabled toolkits
110 +
111 +`session.toolkits()` returns toolkits enabled for the session along with their connection status:
112 +
113 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
114 +<Tab value="Python">
115 +```python
116 +session = composio.create(user_id="user_123")
117 +
118 +# List toolkits enabled for this session
119 +toolkits = session.toolkits()
120 +
121 +for toolkit in toolkits:
122 + print(f"{toolkit.name}: {toolkit.connection_status}")
123 +```
124 +</Tab>
125 +<Tab value="TypeScript">
126 +```typescript
127 +import { Composio } from '@composio/core';
128 +const composio = new Composio({ apiKey: 'your_api_key' });
129 +// ---cut---
130 +const session = await composio.create("user_123");
131 +
132 +// List toolkits enabled for this session
133 +const toolkits = await session.toolkits();
134 +
135 +for (const toolkit of toolkits) {
136 + console.log(`${toolkit.name}: ${toolkit.connectionStatus}`);
137 +}
138 +```
139 +</Tab>
140 +</Tabs>
141 +
142 +The connection status tells you if the user has authenticated with that toolkit.
143 +
144 +### Get tools for your AI framework
145 +
146 +`session.tools()` returns tools formatted for your AI provider:
147 +
148 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
149 +<Tab value="Python">
150 +```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"])
156 +```
157 +</Tab>
158 +<Tab value="TypeScript">
159 +```typescript
160 +import { Composio } from '@composio/core';
161 +const composio = new Composio({ apiKey: 'your_api_key' });
162 +const session = await composio.create("user_123");
163 +// ---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 +});
171 +```
172 +</Tab>
173 +</Tabs>
174 +
175 +Tools are automatically formatted for your configured provider (OpenAI, Anthropic, etc.).
docs/content/docs/tools-and-toolkits.mdx
+69 -63
@@ -1,84 +1,90 @@
1 ---
2 title: Tools and toolkits
3 -description: Access 800+ toolkits through Tool Router
4 -keywords: [available tools, browse toolkits]
3 +description: Understand how tools and toolkits work in Composio
4 +keywords: [tools, toolkits, meta tools, context management]
5 ---
6
7 -Tool Router gives your agent access to most Composio toolkits by default. For details on configuring which toolkits are available in a session, see [Users and sessions](/docs/users-and-sessions#enabling-toolkits).
7 +Composio offers 800+ toolkits, but loading all the tools into context would overwhelm your agent. Instead, your agent has access to 5 meta tools that discover, authenticate, and execute the right tools at runtime.
8
9 -## Toolkits and tools
10 -
11 -A **toolkit** is a collection of related tools for a service and a **tool** is an individual action your agent can execute.
12 -
13 -| Toolkit | Tools |
14 -|---------|-------|
15 -| `github` | `GITHUB_CREATE_A_COMMIT`, `GITHUB_ACTIVITY_LIST_STARGAZERS_FOR_REPO`, `GITHUB_SEARCH_REPO_S`, ... |
16 -| `gmail` | `GMAIL_SEND_EMAIL`, `GMAIL_FETCH_EMAILS`, `GMAIL_CREATE_EMAIL_DRAFT`, ... |
17 -| `linear` | `LINEAR_CREATE_LINEAR_ISSUE`, `LINEAR_UPDATE_ISSUE`, `LINEAR_CREATE_LINEAR_LABEL`, ... |
9 +## Meta tools
10
19 -## Available toolkits
11 +When you create a session, your agent gets these 5 meta tools:
12
21 -Browse all available toolkits in the [Composio platform](https://platform.composio.dev) under "All Toolkits". Each toolkit page shows its tools (with input and output parameters) and authentication methods supported for that toolkit.
13 +| Meta tool | What it does |
14 +|-----------|--------------|
15 +| `COMPOSIO_SEARCH_TOOLS` | Discover relevant tools across 500+ apps |
16 +| `COMPOSIO_MANAGE_CONNECTIONS` | Handle OAuth and API key authentication |
17 +| `COMPOSIO_MULTI_EXECUTE_TOOL` | Execute up to 20 tools in parallel |
18 +| `COMPOSIO_REMOTE_WORKBENCH` | Run Python code in a persistent sandbox |
19 +| `COMPOSIO_REMOTE_BASH_TOOL` | Execute bash commands for file and data processing |
20
23 -You can also list toolkits programmatically:
21 +Meta tool calls in a session are correlated using a `session_id`, allowing them to share context. The tools can also store useful information (like IDs and relationships discovered during execution) in memory for subsequent calls.
22
25 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
26 -<Tab value="Python">
27 -```python
28 -# Returns top 20 toolkits by default
29 -toolkits = composio.toolkits.get()
23 +### How it works
24
31 -for toolkit in toolkits:
32 - print(toolkit.name)
25 ```
34 -</Tab>
35 -<Tab value="TypeScript">
36 -```typescript
37 -import { Composio } from '@composio/core';
38 -const composio = new Composio({ apiKey: 'your_api_key' });
39 -// ---cut---
40 -// Returns top 20 toolkits by default
41 -const toolkits = await composio.toolkits.get();
42 -
43 -for (const toolkit of toolkits) {
44 - console.log(toolkit.name);
45 -}
26 +User: "Create a GitHub issue for this bug"
27 + ↓
28 +1. Agent calls COMPOSIO_SEARCH_TOOLS
29 + → Returns GITHUB_CREATE_ISSUE with input schema
30 + → Returns connection status: "not connected"
31 + → Returns execution plan and tips
32 + ↓
33 +2. Agent calls COMPOSIO_MANAGE_CONNECTIONS (because not connected)
34 + → Returns auth link for GitHub
35 + → User clicks link and authenticates
36 + ↓
37 +3. Agent calls COMPOSIO_MULTI_EXECUTE_TOOL
38 + → Executes GITHUB_CREATE_ISSUE with arguments
39 + → Returns the created issue details
40 + ↓
41 +Done. (For large results, agent can use REMOTE_WORKBENCH to process)
42 ```
47 -</Tab>
48 -</Tabs>
43
50 -For details on browsing tools within toolkits and inspecting schemas, see [Fetching tools and schemas](/docs/fetching-tools).
44 +### What SEARCH_TOOLS returns
45
52 -<Callout type="info">
53 -Some toolkits require you to provide your own credentials. See [Using custom auth configs](/docs/guides/using-custom-auth-configuration).
54 -</Callout>
46 +`COMPOSIO_SEARCH_TOOLS` returns:
47
56 -<Callout type="info">
57 -Need a toolkit that doesn't exist? [Request it here](https://request.composio.dev/boards/tool-requests).
58 -</Callout>
48 +- **Tools with schemas** - Matching tools with their slugs, descriptions, and input parameters
49 +- **Connection status** - Whether the user has already authenticated with each toolkit
50 +- **Execution plan** - Recommended steps and common pitfalls for the task
51 +- **Related tools** - Prerequisites, alternatives, and follow-up tools
52
60 -## Default session behavior
53 +### Processing large results
54
62 -When you create a session, all toolkits are available:
55 +For most tasks, `COMPOSIO_MULTI_EXECUTE_TOOL` returns results directly. But when dealing with large responses or bulk operations, your agent uses the workbench tools:
56
64 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
65 -<Tab value="Python">
66 -```python
67 -session = composio.create(user_id="user_123")
68 -```
69 -</Tab>
70 -<Tab value="TypeScript">
71 -```typescript
72 -import { Composio } from '@composio/core';
73 -const composio = new Composio({ apiKey: 'your_api_key' });
74 -// ---cut---
75 -const session = await composio.create("user_123");
76 -```
77 -</Tab>
78 -</Tabs>
57 +- **`COMPOSIO_REMOTE_WORKBENCH`** - Run Python code in a persistent sandbox. Use for bulk operations (e.g., labeling 100 emails), complex data transformations, or when results need further analysis with helper functions like `invoke_llm`.
58
80 -Your agent can search and use tools from any toolkit. To restrict or configure which toolkits are available, see [Users and sessions](/docs/users-and-sessions#enabling-toolkits).
59 +- **`COMPOSIO_REMOTE_BASH_TOOL`** - Execute bash commands for simpler file operations and data extraction using tools like `jq`, `awk`, `sed`, and `grep`.
60 +
61 +## Toolkits and tools
62
82 -<Callout type="info">
83 -Triggers can be used alongside Tool Router to respond to events in connected apps. See [Triggers](/docs/triggers) for setup instructions.
63 +A **toolkit** is a collection of related tools for a service. For example, the `github` toolkit contains tools for creating issues, managing pull requests, and starring repositories.
64 +
65 +A **tool** is an individual action your agent can execute. Each tool has an input schema (required and optional parameters) and an output schema (what it returns). Tools follow a `{TOOLKIT}_{ACTION}` naming pattern, like `GITHUB_CREATE_ISSUE`.
66 +
67 +<Callout>
68 +If you know exactly which tools you need, you can [execute them directly](/docs/tools-direct/executing-tools) without meta tools.
69 </Callout>
70 +
71 +## Authentication
72 +
73 +Tools execute with the user's authenticated credentials. When a user connects their GitHub account, all GitHub tools run with their permissions.
74 +
75 +If a tool requires authentication and the user hasn't connected yet, the agent can use `COMPOSIO_MANAGE_CONNECTIONS` to prompt them.
76 +
77 +<Card icon={<Key />} title="Authentication" href="/docs/authentication">
78 + Learn how Composio handles user authentication
79 +</Card>
80 +
81 +## Useful links
82 +
83 +<Cards>
84 + <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits">
85 + Explore all available toolkits
86 + </Card>
87 + <Card icon={<BookOpen />} title="Fetching tools" href="/docs/toolkits/fetching-tools-and-toolkits">
88 + Browse the catalog and fetch tools for sessions
89 + </Card>
90 +</Cards>