Skip to content

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

Sushmithamalleshcea2df559067
diff --git a/docs/content/docs/toolkits/enable-and-disable-toolkits.mdx b/docs/content/docs/toolkits/enable-and-disable-toolkits.mdx
new file mode 100644
index 000000000..4e94198b6
--- /dev/null
+++ b/docs/content/docs/toolkits/enable-and-disable-toolkits.mdx
@@ -0,0 +1,371 @@
+---
+title: Enable and disable toolkits
+description: Control which toolkits and tools are available in your sessions
+---
+
+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.
+
+## Enabling specific toolkits
+
+To limit your session to only specific toolkits, pass an array of toolkit slugs:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio()
+
+# Only GitHub and Gmail will be available
+session = composio.create(
+ user_id="user_123",
+ toolkits=["github", "gmail"]
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// Only GitHub and Gmail will be available
+const session = await composio.create("user_123", {
+ toolkits: ["github", "gmail"]
+});
+```
+</Tab>
+</Tabs>
+
+You can also use the explicit `enable` syntax:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ toolkits={"enable": ["github", "gmail"]}
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ toolkits: { enable: ["github", "gmail"] }
+});
+```
+</Tab>
+</Tabs>
+
+## Disabling specific toolkits
+
+To make all toolkits available except certain ones, use the `disable` syntax:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# All toolkits available except Linear and Jira
+session = composio.create(
+ user_id="user_123",
+ toolkits={"disable": ["linear", "jira"]}
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// All toolkits available except Linear and Jira
+const session = await composio.create("user_123", {
+ toolkits: { disable: ["linear", "jira"] }
+});
+```
+</Tab>
+</Tabs>
+
+## Enabling or disabling specific tools
+
+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.
+
+### Enable specific tools
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ tools={
+ # Only these Gmail tools will be available
+ "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]},
+ # Only issue-related GitHub tools
+ "github": {"enable": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]}
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ tools: {
+ // Only these Gmail tools will be available
+ gmail: { enable: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"] },
+ // Only issue-related GitHub tools
+ github: { enable: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"] }
+ }
+});
+```
+</Tab>
+</Tabs>
+
+You can also use the shorthand array syntax which is equivalent to `enable`:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ tools={
+ "gmail": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
+ "github": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ tools: {
+ gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
+ github: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
+ }
+});
+```
+</Tab>
+</Tabs>
+
+### Disable specific tools
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ tools={
+ # All Slack tools except delete
+ "slack": {"disable": ["SLACK_DELETE_MESSAGE"]},
+ # All GitHub tools except destructive ones
+ "github": {"disable": ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"]}
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ tools: {
+ // All Slack tools except delete
+ slack: { disable: ["SLACK_DELETE_MESSAGE"] },
+ // All GitHub tools except destructive ones
+ github: { disable: ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"] }
+ }
+});
+```
+</Tab>
+</Tabs>
+
+## Filtering tools by tags
+
+Tools can be filtered by their behavior tags. Available tags are:
+
+| Tag | Description |
+|-----|-------------|
+| `readOnlyHint` | Tools that only read data |
+| `destructiveHint` | Tools that delete or permanently modify data |
+| `idempotentHint` | Tools that can be safely retried |
+| `openWorldHint` | Tools that interact with external systems |
+
+### Global tag filtering
+
+Apply tag filters to all toolkits:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Only include read-only and idempotent tools
+session = composio.create(
+ user_id="user_123",
+ tags=["readOnlyHint", "idempotentHint"]
+)
+
+# Enable some tags, disable others
+session = composio.create(
+ user_id="user_123",
+ tags={
+ "enable": ["readOnlyHint"],
+ "disable": ["destructiveHint"]
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// Only include read-only and idempotent tools
+const session = await composio.create("user_123", {
+ tags: ["readOnlyHint", "idempotentHint"]
+});
+
+// Enable some tags, disable others
+const sessionWithTagConfig = await composio.create("user_123", {
+ tags: {
+ enable: ["readOnlyHint"],
+ disable: ["destructiveHint"]
+ }
+});
+```
+</Tab>
+</Tabs>
+
+### Per-toolkit tag filtering
+
+Override global tags for specific toolkits:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ # Global: only read-only tools
+ tags=["readOnlyHint"],
+ tools={
+ # Override for GitHub: allow all tools except destructive
+ "github": {"tags": {"disable": ["destructiveHint"]}},
+ # Override for Gmail: only read-only tools (explicit)
+ "gmail": {"tags": ["readOnlyHint"]}
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ // Global: only read-only tools
+ tags: ["readOnlyHint"],
+ tools: {
+ // Override for GitHub: allow all tools except destructive
+ github: { tags: { disable: ["destructiveHint"] } },
+ // Override for Gmail: only read-only tools (explicit)
+ gmail: { tags: ["readOnlyHint"] }
+ }
+});
+```
+</Tab>
+</Tabs>
+
+## Common patterns
+
+### Read-only session for browsing
+
+Create a safe session that can only read data:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ tags=["readOnlyHint"]
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ tags: ["readOnlyHint"]
+});
+```
+</Tab>
+</Tabs>
+
+### Restricted toolkits with full tool access
+
+Limit to specific services but allow all their tools:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ toolkits=["github", "linear", "slack"]
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ toolkits: ["github", "linear", "slack"]
+});
+```
+</Tab>
+</Tabs>
+
+### Granular control per toolkit
+
+Different restrictions for different services:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ toolkits=["github", "gmail", "slack"],
+ tools={
+ # Full access to GitHub
+ # Gmail: only send and fetch
+ "gmail": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
+ # Slack: everything except delete
+ "slack": {"disable": ["SLACK_DELETE_MESSAGE"]}
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ toolkits: ["github", "gmail", "slack"],
+ tools: {
+ // Full access to GitHub
+ // Gmail: only send and fetch
+ gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
+ // Slack: everything except delete
+ slack: { disable: ["SLACK_DELETE_MESSAGE"] }
+ }
+});
+```
+</Tab>
+</Tabs>
diff --git a/docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx b/docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx
index 7e8516ee4..fd2dc4edb 100644
--- a/docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx
+++ b/docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx
@@ -1,175 +1,182 @@
---
title: Fetching tools and toolkits
-description: How to browse Composio's catalog and fetch tools for your sessions
+description: How to fetch tools and toolkits for sessions and browse the catalog
---
-There are two ways to explore tools and toolkits:
+## Fetching for a session
-1. **Browse the catalog** - Discover what toolkits Composio offers
-2. **Fetch for a session** - Get tools enabled for a session
+When using sessions, fetch tools through the session object.
-## Browsing Composio's catalog
+### List enabled toolkits
-Composio offers 800+ toolkits. You can explore the full catalog to discover what's available.
+`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.
-### Using the platform
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(user_id="user_123")
-Browse all toolkits at [platform.composio.dev](https://platform.composio.dev). Each toolkit page shows:
-- Available tools with input/output parameters
-- Supported authentication methods
-- Required OAuth scopes
+result = session.toolkits()
-You can also browse toolkits directly in these docs:
+for toolkit in result.items:
+ print(f"{toolkit.name}: connected={toolkit.connection.is_active if toolkit.connection else 'n/a'}")
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123");
-<Card icon={<Blocks />} title="Browse all toolkits" href="/toolkits">
- Explore 800+ available toolkits with their tools and authentication methods
-</Card>
+const result = await session.toolkits();
-### Using the SDK
+for (const toolkit of result.items) {
+ console.log(`${toolkit.name}: connected=${toolkit.connection?.isActive ?? 'n/a'}`);
+}
+```
+</Tab>
+</Tabs>
-List available toolkits programmatically:
+You can filter to only connected toolkits or search by name:
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
-from composio import Composio
-
-composio = Composio()
-
-# List available toolkits (top 20 by default)
-toolkits = composio.toolkits.get()
-
-for toolkit in toolkits:
- print(f"{toolkit.name} - {toolkit.meta.tools_count} tools")
+result = session.toolkits(is_connected=True) # Only connected
+result = session.toolkits(search="github") # Search by name
```
</Tab>
<Tab value="TypeScript">
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
// ---cut---
-// List available toolkits (top 20 by default)
-const toolkits = await composio.toolkits.get();
-
-for (const toolkit of toolkits) {
- console.log(`${toolkit.name} - ${toolkit.meta.toolsCount} tools`);
-}
+const connected = await session.toolkits({ isConnected: true }); // Only connected
+const searched = await session.toolkits({ search: "github" }); // Search by name
```
</Tab>
</Tabs>
-Get a specific toolkit's details:
+To fetch all toolkits, paginate through the results:
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
-# Get details for a specific toolkit
-github = composio.toolkits.get_by_slug("github")
-print(github.meta.description)
+all_toolkits = []
+cursor = None
+
+while True:
+ result = session.toolkits(limit=20, next_cursor=cursor)
+ all_toolkits.extend(result.items)
+ cursor = result.next_cursor
+ if not cursor:
+ break
```
</Tab>
<Tab value="TypeScript">
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
// ---cut---
-// Get details for a specific toolkit
-const github = await composio.toolkits.getBySlug("github");
-console.log(github.meta.description);
+const allToolkits: any[] = [];
+let cursor: string | undefined;
+
+do {
+ const { items, nextCursor } = await session.toolkits({ limit: 20, nextCursor: cursor });
+ allToolkits.push(...items);
+ cursor = nextCursor;
+} while (cursor);
```
</Tab>
</Tabs>
-Get a specific tool's schema:
+### Get meta tools
+
+`session.tools()` returns the 5 meta tools formatted for your configured provider (OpenAI, Anthropic, etc.):
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
-# Get schema for a specific tool
-tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
-print(tool.input_parameters)
+# Get all meta tools
+tools = session.tools()
```
</Tab>
<Tab value="TypeScript">
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
// ---cut---
-// Get schema for a specific tool
-const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");
-console.log(tool.inputParameters);
+// Get all meta tools
+const tools = await session.tools();
```
</Tab>
</Tabs>
-## Fetching tools for a session
+To restrict which toolkits or tools are discoverable by the meta tools, configure them when [creating the session](/docs/toolkits/enable-and-disable-toolkits).
-Once you create a session for a user, you can fetch tools and check which toolkits are enabled.
+## Browsing the catalog
-### List enabled toolkits
+### Browse toolkits and tools
-`session.toolkits()` returns toolkits enabled for the session along with their connection status:
+You can explore all 800+ toolkits at [platform.composio.dev](https://platform.composio.dev) or in the [docs](/toolkits).
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
-session = composio.create(user_id="user_123")
+from composio import Composio
-# List toolkits enabled for this session
-toolkits = session.toolkits()
+composio = Composio()
+
+# List toolkits
+toolkits = composio.toolkits.get()
-for toolkit in toolkits:
- print(f"{toolkit.name}: {toolkit.connection_status}")
+# List tools within a toolkit
+tools = composio.tools.get(user_id, toolkits=["GITHUB"])
```
</Tab>
<Tab value="TypeScript">
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
+const userId = 'user_123';
// ---cut---
-const session = await composio.create("user_123");
-
-// List toolkits enabled for this session
-const toolkits = await session.toolkits();
+// List toolkits
+const toolkits = await composio.toolkits.get();
-for (const toolkit of toolkits) {
- console.log(`${toolkit.name}: ${toolkit.connectionStatus}`);
-}
+// List tools within a toolkit
+const tools = await composio.tools.get(userId, { toolkits: ["GITHUB"] });
```
</Tab>
</Tabs>
-The connection status tells you if the user has authenticated with that toolkit.
+### Get a tool's schema
-### Get tools for your AI framework
-
-`session.tools()` returns tools formatted for your AI provider:
+To inspect a tool's input parameters and types without needing a user context, use `getRawComposioToolBySlug`:
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
-# Get tools from specific toolkits
-tools = session.tools(toolkits=["github", "gmail"])
-
-# Or get specific tools by name
-tools = session.tools(tools=["GITHUB_CREATE_ISSUE", "GMAIL_SEND_EMAIL"])
+tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
+print(tool.name)
+print(tool.description)
+print(tool.input_parameters)
+print(tool.output_parameters)
```
</Tab>
<Tab value="TypeScript">
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
// ---cut---
-// Get tools from specific toolkits
-const tools = await session.tools({ toolkits: ["github", "gmail"] });
-
-// Or get specific tools by name
-const specificTools = await session.tools({
- tools: ["GITHUB_CREATE_ISSUE", "GMAIL_SEND_EMAIL"]
-});
+const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");
+console.log(tool.name);
+console.log(tool.description);
+console.log(tool.inputParameters);
+console.log(tool.outputParameters);
```
</Tab>
</Tabs>
-
-Tools are automatically formatted for your configured provider (OpenAI, Anthropic, etc.).
diff --git a/docs/content/docs/toolkits/meta.json b/docs/content/docs/toolkits/meta.json
index 800f9376c..b9790828b 100644
--- a/docs/content/docs/toolkits/meta.json
+++ b/docs/content/docs/toolkits/meta.json
@@ -1,6 +1,7 @@
{
"title": "Toolkits",
"pages": [
- "fetching-tools-and-toolkits"
+ "fetching-tools-and-toolkits",
+ "enable-and-disable-toolkits"
]
}