Skip to main content
For a complete agent that combines an internal lookup with a public API, follow Combine your own tools with Composio. If you already have your own tool definitions, start with Managed authentication for your own tools. You can call the authenticated proxy from your code without adopting the experimental session-extension API below. Custom tools let you define tools that run in-process alongside remote Composio tools within a session. You have three patterns:
  • Standalone tools: internal app logic that doesn’t need Composio auth (DB lookups, in-memory data, business rules).
  • Extension tools: wrap a Composio toolkit’s API with custom business logic via extendsToolkit / extends_toolkit, using ctx.proxyExecute() / ctx.proxy_execute() for authenticated requests.
  • Custom toolkits: group related standalone tools under a namespace.
1

Install

Install
2

Initialize the client

Initialize the client
3

Create the tool

Create the toolA standalone tool handles internal app logic that doesn’t need Composio auth. ctx.userId identifies which user’s session is running.
4

Bind to a session

Bind to a sessionPass custom tools via the experimental option. session.tools() returns both remote Composio tools and your custom tools.

Preloading custom tools

Custom tools are searchable by default. Set preload: true / preload=True on a custom tool when it should be returned directly from session.tools(). Toolkit preload applies to all tools in that toolkit; set preload: false / preload=False on one tool to opt it out.

Meta tools integration

Custom tools work automatically with Composio’s meta tools:
Custom tools are not supported in the sandbox.

Context object (ctx)

Every custom tool’s execute function receives (input, ctx). Use ctx to access the current user, make authenticated API requests, or call other Composio tools.
See the full API in the SDK reference: TypeScript | Python

Verifying registration

Use these methods to list registered tools and toolkits. Slugs include their final LOCAL_ prefix, and toolkit-scoped tools also include the toolkit slug.

Reusing a session with custom tools

When reusing a session via composio.use(), you can attach custom tools at the same time:

Programmatic execution

Use session.execute() to run custom tools directly, outside of an agent loop. Custom tools execute in-process; remote tools are sent to the backend automatically.

Best practices

Naming and descriptions

The agent relies on your tool’s name and description to decide when to call it. Be specific: “Send weekly promo email” is better than “Send email”. Include what the tool does, when to use it, and what it returns. In TypeScript, use uppercase slugs like SEND_PROMO_EMAIL. In Python, slugs are inferred from the function name, so snake_case produces clean defaults. You can also pass slug and name explicitly.

Accessing authenticated APIs

If your tool calls an API that requires user credentials (Gmail, GitHub, and so on), set extendsToolkit / extends_toolkit to the toolkit name. Composio handles authentication automatically, and the agent can prompt users to connect their account when needed.

Defining inputs in Python

Your tool’s first parameter must be a Pydantic BaseModel. The field descriptions become what the agent sees as the input schema, and the function’s docstring becomes the tool description. You can override this by passing description explicitly.

Tool names get prefixed

Slugs exposed to the agent are automatically prefixed with LOCAL_ and the toolkit name (if applicable):
  • GET_USER_PROFILE becomes LOCAL_GET_USER_PROFILE
  • ASSIGN_ROLE in USER_MANAGEMENT becomes LOCAL_USER_MANAGEMENT_ASSIGN_ROLE
Your slugs cannot start with LOCAL_. This prefix is reserved. Use the final LOCAL_* slug when you call a custom tool directly. The original slug still works when it identifies exactly one local tool. If two custom toolkits both define SEARCH, call LOCAL_CATALOG_SEARCH or LOCAL_SUPPORT_SEARCH. Calling SEARCH directly raises an error with the qualified slugs instead of choosing one toolkit silently.

Next

Configuring sessions