Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxnew file mode 100644index 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.mdxindex 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">```typescriptimport { 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">```typescriptimport { 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">```typescriptimport { 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">```typescriptimport { 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">```typescriptimport { 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.jsonindex 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"]}