Tools and toolkits

A toolkit is a collection of related tools for a service. For example, the github toolkit contains tools for creating issues, managing pull requests, and starring repositories.

A tool is an individual action your agent can execute. Each tool has an input schema (required and optional parameters) and an output schema (what it returns). Tools follow a {TOOLKIT}_{ACTION} naming pattern, like GITHUB_CREATE_ISSUE.

Meta tools

When using a Composio session, your agent primarily interfaces with tools and toolkits through meta tools. These tools let the agent search the catalog, inspect schemas, authenticate users, execute app tools, and use the workbench without loading every possible tool into context.

If you know exactly which tools the agent should use, you can preload those tools or use the direct tools preset to expose them directly and disable meta tools.

A session provides these meta tools:

See the Meta Tools Reference for complete input/output schemas and details.

Meta tool calls in a session are correlated using a session_id, allowing them to share context. The tools can also store useful information (like IDs and relationships discovered during execution) in memory for subsequent calls.

How it works

User: "Create a GitHub issue for this bug"
    ↓
1. Agent calls COMPOSIO_SEARCH_TOOLS
   → Returns GITHUB_CREATE_ISSUE with input schema
   → Returns connection status: "not connected"
   → Returns execution plan and tips
    ↓
2. Agent calls COMPOSIO_MANAGE_CONNECTIONS (because not connected)
   → Returns auth link for GitHub
   → User clicks link and authenticates
    ↓
3. Agent calls COMPOSIO_MULTI_EXECUTE_TOOL
   → Executes GITHUB_CREATE_ISSUE with arguments
   → Returns the created issue details
    ↓
Done. (For large results, agent can use REMOTE_WORKBENCH to process)

What SEARCH_TOOLS returns

COMPOSIO_SEARCH_TOOLS returns:

• Tools with schemas - Matching tools with their slugs, descriptions, and input parameters
• Connection status - Whether the user has already authenticated with each toolkit
• Execution plan - Recommended steps and common pitfalls for the task
• Related tools - Prerequisites, alternatives, and follow-up tools

Processing large results

For most tasks, COMPOSIO_MULTI_EXECUTE_TOOL returns results directly. But when dealing with large responses or bulk operations, your agent uses the workbench tools:

• COMPOSIO_REMOTE_WORKBENCH - Run Python code in a persistent sandbox. Use for bulk operations (e.g., labeling 100 emails), complex data transformations, or when results need further analysis with helper functions like invoke_llm.

• COMPOSIO_REMOTE_BASH_TOOL - Execute bash commands for simpler file operations and data extraction using tools like jq, awk, sed, and grep.

Custom tools and toolkits

You can also add local in-process tools to a session using the experimental custom tools and custom toolkits API. See Custom tools and toolkits.

What toolkits does my agent have access to?

All toolkits are discoverable by default. When you create a session without specifying a toolkits parameter, every toolkit in the Composio catalog is available through COMPOSIO_SEARCH_TOOLS. The agent searches for relevant tools at runtime — it doesn't load them all into context at once.

To restrict which toolkits are available, pass toolkits when creating the session. See Enable and disable toolkits.

Authentication

Tools execute with the user's authenticated credentials. When a user connects their GitHub account, all GitHub tools run with their permissions.

For OAuth toolkits, Composio uses managed apps by default. Use a custom app when you need your own OAuth branding, scopes, or consent screen.

If a tool requires authentication and the user hasn't connected yet, the agent can use COMPOSIO_MANAGE_CONNECTIONS to prompt them.

What to read next