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
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: