Tools

Manage and execute tools in the Composio SDK

The Tools class provides methods to retrieve, execute, and manage tools. Tools are individual functions like GITHUB_CREATE_ISSUE, GMAIL_SEND_EMAIL, etc.

Accessing Tools

from composio import Composio

composio = Composio()
tools_api = composio.tools

Methods

get

Retrieve tools based on various filters. Returns provider-specific tool collection (type automatically inferred).

tools = composio.tools.get(
    user_id="default",
    toolkits=["github"],
    search="issue",
    limit=10
)

user_id · str · required

The user ID to get tools for. Used for user-specific authentication.

slug · str

Get a single tool by slug (e.g., "GITHUB_CREATE_ISSUE").

tools · list[str]

List of specific tool slugs to retrieve.

tools = composio.tools.get(
    user_id="default",
    tools=["GITHUB_CREATE_ISSUE", "GITHUB_LIST_REPOS"]
)

search · str

Search term to filter tools by name or description.

tools = composio.tools.get(
    user_id="default",
    toolkits=["github"],
    search="issue"
)

toolkits · list[str]

Filter tools by toolkit slugs.

tools = composio.tools.get(
    user_id="default",
    toolkits=["github", "slack"]
)

scopes · list[str]

Filter by required OAuth scopes.

modifiers · list[Modifier]

Apply schema or execution modifiers to tools. See Decorators.

limit · int

Maximum number of tools to return.

return · TToolCollection

Provider-specific tool collection. The type is automatically inferred:

• OpenAIProvider → list[ChatCompletionToolParam]
• AnthropicProvider → list[ToolParam]
• Other providers → respective tool types

execute

Execute a tool with the provided parameters.

result = composio.tools.execute(
    slug="GITHUB_CREATE_ISSUE",
    arguments={
        "owner": "composiohq",
        "repo": "composio",
        "title": "Bug report",
        "body": "Description of the issue"
    },
    user_id="default"
)

slug · str · required

The tool slug to execute (e.g., "GITHUB_CREATE_ISSUE").

arguments · dict[str, Any] · required

The arguments to pass to the tool. Must match the tool’s input schema.

user_id · str

The user ID to execute the tool for. Used to select the connected account.

connected_account_id · str

Specific connected account ID to use for execution.

custom_auth_params · dict

Custom authentication parameters for the tool execution.

custom_connection_data · dict

Custom connection data (takes priority over custom_auth_params).

text · str

Additional text context for the tool execution.

version · str

Specific tool version to execute. Overrides SDK-level toolkit versions.

dangerously_skip_version_check · bool · default: "False"

Skip version check for ‘latest’ version. May cause unexpected behavior.

modifiers · list[Modifier]

Apply before/after execution modifiers.

return · ToolExecutionResponse

Execution result with the following structure:

{
    "data": {...},  # Tool output data
    "error": None | str,  # Error message if failed
    "successful": bool  # Whether execution succeeded
}

proxy

Make direct API calls through connected accounts.

response = composio.tools.proxy(
    endpoint="/repos/composiohq/composio/issues/1",
    method="GET",
    connected_account_id="ca_xxx",
    parameters=[
        {
            "name": "Accept",
            "value": "application/vnd.github.v3+json",
            "type": "header"
        }
    ]
)

endpoint · str · required

API endpoint path (e.g., /repos/owner/repo/issues).

method · Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD'] · required

HTTP method for the request.

body · object

Request body for POST/PUT/PATCH requests.

connected_account_id · str

Connected account ID to use for authentication.

parameters · list[Parameter]

Additional parameters (headers, query params, etc.).

Each parameter has:

• name: Parameter name
• value: Parameter value
• type: "header", "query", or "path"

custom_connection_data · dict

Custom connection data for the request.

custom_tool

Register a custom tool. This is an alias for composio.tools.custom_tool.

See Custom Tools for detailed documentation.

from pydantic import BaseModel

class MyToolRequest(BaseModel):
    message: str

@composio.tools.custom_tool
def my_custom_tool(request: MyToolRequest) -> dict:
    """My custom tool that processes messages."""
    return {"result": f"Processed: {request.message}"}

get_raw_composio_tool_by_slug

Get raw tool schema without provider wrapping (advanced usage).

tool_schema = composio.tools.get_raw_composio_tool_by_slug(
    slug="GITHUB_CREATE_ISSUE"
)

get_raw_composio_tools

Get raw tool schemas without provider wrapping (advanced usage).

tools = composio.tools.get_raw_composio_tools(
    toolkits=["github"],
    search="issue"
)

Examples

Get Tools by Toolkit

# Get all GitHub tools
tools = composio.tools.get(
    user_id="default",
    toolkits=["github"]
)

# Get tools from multiple toolkits
tools = composio.tools.get(
    user_id="default",
    toolkits=["github", "slack", "gmail"]
)

Get Specific Tools

# Get a single tool
tool = composio.tools.get(
    user_id="default",
    slug="GITHUB_CREATE_ISSUE"
)

# Get multiple specific tools
tools = composio.tools.get(
    user_id="default",
    tools=[
        "GITHUB_CREATE_ISSUE",
        "GITHUB_LIST_REPOS",
        "GITHUB_GET_REPO"
    ]
)

Search Tools

# Search for tools related to "email"
tools = composio.tools.get(
    user_id="default",
    search="email"
)

# Search within specific toolkits
tools = composio.tools.get(
    user_id="default",
    toolkits=["github"],
    search="issue"
)

Execute Tools

# Basic execution
result = composio.tools.execute(
    slug="GITHUB_GET_REPO",
    arguments={"owner": "composiohq", "repo": "composio"},
    user_id="default"
)

if result["successful"]:
    print(f"Repository data: {result['data']}")
else:
    print(f"Error: {result['error']}")

Execute with Specific Account

result = composio.tools.execute(
    slug="GITHUB_CREATE_ISSUE",
    arguments={
        "owner": "composiohq",
        "repo": "composio",
        "title": "New feature request",
        "body": "Description"
    },
    connected_account_id="ca_specific_account"
)

Execute with Custom Auth

result = composio.tools.execute(
    slug="GITHUB_GET_REPO",
    arguments={"owner": "composiohq", "repo": "composio"},
    custom_auth_params={
        "token": "github_pat_xxx"
    }
)

Proxy Call

# GET request
response = composio.tools.proxy(
    endpoint="/user",
    method="GET",
    connected_account_id="ca_github_account"
)

# POST request with body
response = composio.tools.proxy(
    endpoint="/repos/owner/repo/issues",
    method="POST",
    body={
        "title": "Bug report",
        "body": "Description"
    },
    connected_account_id="ca_github_account"
)

Type Safety

The Tools class is generic and provides full type safety:

from composio import Composio
from composio_openai import OpenAIProvider
from composio_anthropic import AnthropicProvider

# OpenAI tools
composio_openai = Composio(provider=OpenAIProvider())
tools: list[ChatCompletionToolParam] = composio_openai.tools.get(
    user_id="default",
    toolkits=["github"]
)

# Anthropic tools
composio_anthropic = Composio(provider=AnthropicProvider())
tools: list[ToolParam] = composio_anthropic.tools.get(
    user_id="default",
    toolkits=["github"]
)

Next Steps

Decorators

Learn about tool modifiers

Custom Tools

Create your own tools

Connected Accounts

Manage authentication

Providers

Use tools with AI frameworks