Tools and toolkits

Composio offers 800+ toolkits, but loading all the tools into context would overwhelm your agent. Instead, your agent has access to 5 meta tools that discover, authenticate, and execute the right tools at runtime.

Meta tools

When you create a session, your agent gets these 5 meta tools:

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.

Toolkits and tools

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.

Authentication

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

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

Useful links