@devries-cameron20 / composio-1 / commits / d4063eef4
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add meta tools integration, verification, programmatic execution

- Document how custom tools work with COMPOSIO_SEARCH_TOOLS, COMPOSIO_GET_TOOL_SCHEMAS, COMPOSIO_MULTI_EXECUTE_TOOL, and COMPOSIO_MANAGE_CONNECTIONS - Note that custom tools are not supported in Workbench - Add tool naming section (LOCAL_ prefix + toolkit name) - Add session.customTools() and session.customToolkits() for verification - Add session.execute() for programmatic execution with original slug - Update old custom tools page callout to point to new experimental API Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Dhawal Upadhyay committed Mar 23, 2026 at 18:08 UTC d4063eef4eea4af1b98e5f550ed7926d8af01230
2 files changed +70 -2
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+69 -1
@@ -9,7 +9,7 @@ Custom tools are experimental. The `experimental_` prefix and `experimental` ses
9 </Callout>
10
11 <Callout type="info">
12 -Custom tools work with **native tools** (`session.tools()`). MCP support is coming soon.
12 +Custom tools work with **native tools** (`session.tools()`). MCP support is coming soon — custom tools are not available via the MCP server URL yet.
13 </Callout>
14
15 Custom tools let you define tools that run in-process alongside remote Composio tools within a session. There are three patterns:
@@ -104,6 +104,74 @@ const session = await composio.create("user_1", {
104 const tools = await session.tools();
105 ```
106
107 +## How custom tools work with meta tools
108 +
109 +Custom tools integrate seamlessly with Composio's meta tools:
110 +
111 +- **`COMPOSIO_SEARCH_TOOLS`** automatically includes your custom tools and toolkits in search results, giving slight priority to tools that don't require auth or are already connected
112 +- **`COMPOSIO_GET_TOOL_SCHEMAS`** returns schemas for custom tools alongside remote tools — the agent sees them as first-class tools
113 +- **`COMPOSIO_MULTI_EXECUTE_TOOL`** intelligently splits execution — custom tools run in-process while remote tools go to the backend, results are merged transparently
114 +- **`COMPOSIO_MANAGE_CONNECTIONS`** handles auth for extension tools — if a tool extends `gmail`, the agent can prompt the user to connect Gmail just like any other toolkit
115 +- Custom tools are **not supported in Workbench** — the LLM is made aware of this and will not attempt to use them there
116 +
117 +## Tool naming
118 +
119 +Tool names exposed to the agent are automatically prefixed with `LOCAL_` and the toolkit name (if any):
120 +
121 +- `GET_USER_PROFILE` → `LOCAL_GET_USER_PROFILE`
122 +- `SEND_PROMO_EMAIL` → `LOCAL_SEND_PROMO_EMAIL`
123 +- `ASSIGN_ROLE` in `USER_MANAGEMENT` toolkit → `LOCAL_USER_MANAGEMENT_ASSIGN_ROLE`
124 +
125 +Slugs cannot start with `LOCAL_` or `COMPOSIO_` — these prefixes are reserved.
126 +
127 +## Verifying registration
128 +
129 +After creating a session, use `session.customTools()` and `session.customToolkits()` to verify your tools were registered correctly:
130 +
131 +```typescript
132 +import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
133 +import { z } from "zod/v3";
134 +
135 +const getUserProfile = experimental_createTool("GET_USER_PROFILE", { name: "Get user profile", description: "Retrieve profile", inputParams: z.object({}), execute: async (_input, ctx) => ({}) });
136 +const userManagement = experimental_createToolkit("USER_MANAGEMENT", { name: "User management", description: "Manage roles", tools: [experimental_createTool("ASSIGN_ROLE", { name: "Assign role", description: "Assign role", inputParams: z.object({ user_id: z.string() }), execute: async () => ({}) })] });
137 +const composio = new Composio({ apiKey: "your_api_key" });
138 +const session = await composio.create("user_1", { experimental: { customTools: [getUserProfile], customToolkits: [userManagement] } });
139 +// ---cut---
140 +// List all registered custom tools (with their final LOCAL_ prefixed slugs)
141 +const registeredTools = session.customTools();
142 +console.log(registeredTools);
143 +// [{ slug: "LOCAL_GET_USER_PROFILE", name: "Get user profile", ... }]
144 +
145 +// Filter by toolkit
146 +const managementTools = session.customTools({ toolkit: "USER_MANAGEMENT" });
147 +
148 +// List registered custom toolkits
149 +const registeredToolkits = session.customToolkits();
150 +console.log(registeredToolkits);
151 +// [{ slug: "USER_MANAGEMENT", name: "User management", tools: [...] }]
152 +```
153 +
154 +## Programmatic execution
155 +
156 +Use `session.execute()` to run custom tools directly — outside of an agent loop. You can use the original slug without the `LOCAL_` prefix:
157 +
158 +```typescript
159 +import { Composio, experimental_createTool } from "@composio/core";
160 +import { z } from "zod/v3";
161 +
162 +const getUserProfile = experimental_createTool("GET_USER_PROFILE", { name: "Get user profile", description: "Retrieve profile", inputParams: z.object({}), execute: async (_input, ctx) => ({ name: "Alice", tier: "enterprise" }) });
163 +const composio = new Composio({ apiKey: "your_api_key" });
164 +const session = await composio.create("user_1", { experimental: { customTools: [getUserProfile] } });
165 +// ---cut---
166 +// Both work — original slug or full LOCAL_ prefixed slug
167 +const result = await session.execute("GET_USER_PROFILE");
168 +const same = await session.execute("LOCAL_GET_USER_PROFILE");
169 +
170 +console.log(result.data); // { name: "Alice", tier: "enterprise" }
171 +```
172 +
173 +Custom tools execute in-process. Remote Composio tools are sent to the backend automatically.
174 +
175 ## SessionContext
176
177 Every custom tool's `execute` function receives `(input, ctx)`. The `ctx` object provides:
docs/content/docs/tools-direct/custom-tools.mdx
+1 -1
@@ -6,7 +6,7 @@ llmGuardrails: "direct-execution"
6 ---
7
8 <Callout type="info">
9 -If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. See [Tools and toolkits](/docs/tools-and-toolkits) for how sessions discover and execute tools automatically.
9 +If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. See [Custom Tools and Toolkits (Experimental)](/docs/toolkits/custom-tools-and-toolkits) for defining local tools that run in-process alongside remote Composio tools within a session.
10 </Callout>
11
12 Custom tools allow you to create your own tools that can be used with Composio.