Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us