> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetching tools and schemas

> Fetch and filter tools, and inspect schemas

> [!NOTE]
>
> **Legacy API: prefer sessions**
>
> This guide covers legacy direct-execution methods, which remain supported for existing integrations. For new integrations, use [sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) to discover and fetch tools at runtime. If you need a fixed tool set, consider the [direct tools preset](https://composio-preview.mintlify.site/docs/configuring-sessions.md#direct-tools-preset). See [Sessions vs direct execution](https://composio-preview.mintlify.site/docs/sessions-vs-direct-execution.md) and the [migration guide](https://composio-preview.mintlify.site/docs/migration-guide/direct-to-sessions.md).

Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.

Not sure which toolkit covers your use case? Browse the [Toolkits catalog](https://composio-preview.mintlify.site/toolkits.md) — each toolkit page lists its tool slugs — or [search by task](#by-search-experimental) below.

## Basic usage

> [tab] Python
>
> ```python theme={null}
> tools = composio.tools.get(
>     user_id,
>     toolkits=["GITHUB"]
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> const tools = await composio.tools.get(userId, {
>   toolkits: ["GITHUB"],
>   important: false,
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # Returns raw tool schemas; the SDKs also format them for your provider
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?toolkit_slug=GITHUB" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

Returns up to 20 tools by default. Tools require a `user_id` because they're scoped to authenticated accounts. See [User scoping](https://composio-preview.mintlify.site/docs/how-composio-works.md) and [Authentication](https://composio-preview.mintlify.site/docs/tools-direct/authenticating-tools.md).

## Tool schemas

Inspect tool parameters and types without a user\_id:

> [tab] Python
>
> ```python theme={null}
> tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET https://backend.composio.dev/api/v3.1/tools/GMAIL_SEND_EMAIL \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

Generate type-safe code for direct SDK execution with [`composio generate`](https://composio-preview.mintlify.site/docs/cli#generate-type-definitions). This creates TypeScript or Python types from tool schemas.

> [!NOTE]
>
> View tool parameters and schemas visually in the [Composio platform](https://dashboard.composio.dev?utm_source=docs\&utm_medium=content\&utm_campaign=docs-tools-direct-fetching-tools). Navigate to any toolkit and select a tool to see its input/output parameters.

## Filtering tools

### By toolkit

Get tools from specific apps. Returns up to 20 tools by default.

`limit` caps the number of returned tools. It does not select the tools needed for a task or guarantee relevance order. A small limit can exclude the tool you need. For a fixed workflow, [fetch explicit tool names](#by-name).

> [!NOTE]
>
> **TypeScript: limit and important tools**
>
> When you filter only by toolkit, the TypeScript SDK automatically requests tools marked `important` unless you set `important: false`. Supplying `limit`, `search`, or `tags` disables that automatic filter. To keep the important subset with a limit, pass `important: true` explicitly. The Python SDK does not expose this option.

> [tab] Python
>
> ```python theme={null}
> # Fetch with limit for a specific user
> tools = composio.tools.get(
>     user_id,
>     toolkits=["GITHUB"],
>     limit=5  # Return at most 5 tools
> )
>
> # Same filter but without user_id (for schemas)
> raw_tools = composio.tools.get_raw_composio_tools(
>     toolkits=["GITHUB"],
>     limit=5
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> // Fetch with limit for a specific user
> const limitedTools = await composio.tools.get(userId, {
>   toolkits: ["GITHUB"],
>   important: true,
>   limit: 5  // Return at most 5 important tools
> });
>
> // Same filter but without userId (for schemas)
> const rawTools = await composio.tools.getRawComposioTools({
>   toolkits: ["GITHUB"],
>   important: true,
>   limit: 5
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # Return at most 5 tools
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?toolkit_slug=GITHUB&limit=5" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

### By name

Fetch specific tools when you know their names.

> [tab] Python
>
> ```python theme={null}
> # Fetch specific tools by name
> tools = composio.tools.get(
>     user_id,
>     tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
> )
>
> # Get schemas without user_id
> raw_tools = composio.tools.get_raw_composio_tools(
>     tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> // Fetch specific tools by name
> const specificTools = await composio.tools.get(userId, {
>   tools: ["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
> });
>
> // Get schemas without userId
> const specificRawTools = await composio.tools.getRawComposioTools({
>   tools: ["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # Fetch specific tools by name
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?tool_slugs=GITHUB_CREATE_ISSUE,GITHUB_CREATE_PULL_REQUEST" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

### By scopes

Filter OAuth tools by permission level. Only works with a single toolkit.

> [tab] Python
>
> ```python theme={null}
> # Filter by OAuth scopes (single toolkit only)
> tools = composio.tools.get(
>     user_id,
>     toolkits=["GITHUB"],
>     scopes=["write:org"]
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> // Filter by OAuth scopes (single toolkit only)
> const scopedTools = await composio.tools.get(userId, {
>   toolkits: ["GITHUB"],
>   scopes: ["write:org"]
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # Filter by OAuth scopes (single toolkit only)
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?toolkit_slug=GITHUB&scopes=write:org" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

### By search (experimental)

Search for tools with the `search` option. Start with short action keywords such as `create event`, `free busy`, or `send email`, and narrow the query with `toolkits` when you know the app.

Inspect the returned descriptions and input schemas before selecting a tool. Do not assume the first result is the best match or that a natural-language goal returns every relevant tool. If you get no results, shorten the query or [fetch a known tool by name](#by-name).

> [tab] Python
>
> ```python theme={null}
> # Search tools by action keywords
> tools = composio.tools.get(
>     user_id,
>     search="create event",
>     toolkits=["googlecalendar"]
> )
>
> # Search schemas without user_id
> raw_tools = composio.tools.get_raw_composio_tools(
>     search="create event",
>     toolkits=["googlecalendar"]
> )
>
> # Search within a specific toolkit
> tools = composio.tools.get(
>     user_id,
>     search="issues",
>     toolkits=["GITHUB"],
> )
>
> # Search toolkit schemas without user_id
> raw_tools = composio.tools.get_raw_composio_tools(
>     search="issues",
>     toolkits=["GITHUB"]
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> // Search tools by action keywords
> const searchResults = await composio.tools.get(userId, {
>   search: "create event",
>   toolkits: ["googlecalendar"]
> });
>
> // Search schemas without userId
> const searchRawTools = await composio.tools.getRawComposioTools({
>   search: "create event",
>   toolkits: ["googlecalendar"]
> });
>
> // Search within a specific toolkit
> const toolkitSearch = await composio.tools.get(userId, {
>   search: "issues",
>   toolkits: ["GITHUB"]
> });
>
> // Search toolkit schemas without userId
> const toolkitSearchRaw = await composio.tools.getRawComposioTools({
>   search: "issues",
>   toolkits: ["GITHUB"]
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # Search tools by action keywords
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?query=create%20event&toolkit_slug=googlecalendar" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
>
> # Search within a specific toolkit
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?query=issues&toolkit_slug=GITHUB" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

> [!NOTE]
>
> These SDK examples use `latest` by default. REST v3 tool endpoints default to `00000000_00`; REST v3.1 tool endpoints default to `latest`. Pin a dated version when application code parses tool output. See [toolkit versioning](https://composio-preview.mintlify.site/docs/tools-direct/toolkit-versioning.md).

## Next

> [card] [Executing tools](https://composio-preview.mintlify.site/docs/tools-direct/executing-tools.md)
>
> Run tools with providers, agentic frameworks, or direct execution
