- 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, usingctx.proxyExecute()/ctx.proxy_execute()for authenticated requests. - Custom toolkits: group related standalone tools under a namespace.
- Standalone Tool
- Extension Tool
- Custom Toolkit
1
Install
Install
- Python
- TypeScript
2
Initialize the client
Initialize the client
- Python
- TypeScript
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.- Python
- TypeScript
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.- Python
- TypeScript
Preloading custom tools
Custom tools are searchable by default. Setpreload: 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.
- Python
- TypeScript
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.
- Python
- TypeScript
Verifying registration
Use these methods to list registered tools and toolkits. Slugs include their finalLOCAL_ prefix, and toolkit-scoped tools also include the toolkit slug.
- Python
- TypeScript
Reusing a session with custom tools
When reusing a session viacomposio.use(), you can attach custom tools at the same time:
- Python
- TypeScript
Programmatic execution
Usesession.execute() to run custom tools directly, outside of an agent loop. Custom tools execute in-process; remote tools are sent to the backend automatically.
- Python
- TypeScript
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 likeSEND_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), setextendsToolkit / 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 PydanticBaseModel. 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 withLOCAL_ and the toolkit name (if applicable):
GET_USER_PROFILEbecomesLOCAL_GET_USER_PROFILEASSIGN_ROLEinUSER_MANAGEMENTbecomesLOCAL_USER_MANAGEMENT_ASSIGN_ROLE
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.