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: move custom tools to toolkits/ as dedicated page
Reverts configuring-sessions.mdx to original state and creates a new custom-tools-and-toolkits.mdx under toolkits/ section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Dhawal Upadhyay committed
Mar 19, 2026 at 08:59 UTC
b44fe816f6183f266c217e4d6d956ae382f5a789
3 files changed
+129
-119
docs/content/docs/configuring-sessions.mdx
+2
-118
@@ -1,7 +1,7 @@
1
---
2
title: Configuring Sessions
3
-description: Enable toolkits, set auth configs, select connected accounts, and add custom tools
4
-keywords: [session, toolkits, auth configs, connected accounts, custom tools, beta]
3
+description: Enable toolkits, set auth configs, and select connected accounts
4
+keywords: [session, toolkits, auth configs, connected accounts]
5
---
6
7
## Creating a session
@@ -163,122 +163,6 @@ When executing a tool, the connected account is selected in this order:
163
164
If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
165
166
-## Custom tools (Beta)
167
-
168
-<Callout type="warn">
169
-Custom tools are experimental. The `experimental_` prefix and `experimental` session option may change in future releases. TypeScript only.
170
-</Callout>
171
-
172
-Custom tools let you define local tools that run in-process alongside remote Composio tools. There are three patterns:
173
-
174
-### Standalone tool
175
-
176
-A tool that doesn't need any Composio-managed authentication:
177
-
178
-```ts
179
-// @noErrors
180
-import { experimental_createTool } from "@composio/core";
181
-import { z } from "zod";
182
-
183
-const getUser = experimental_createTool("GET_USER", {
184
- name: "Get user",
185
- description: "Look up an internal user by ID",
186
- inputParams: z.object({
187
- user_id: z.string().describe("User ID"),
188
- }),
189
- execute: async ({ user_id }) => {
190
- // Your logic here — just return the result
191
- return { name: "Alice", email: "alice@acme.com" };
192
- },
193
-});
194
-```
195
-
196
-### Extension tool
197
-
198
-A tool that inherits authentication from an existing Composio toolkit. Use `extendsToolkit` to specify which toolkit, then call APIs through `ctx.proxyExecute()` or invoke other tools via `ctx.execute()`:
199
-
200
-```ts
201
-// @noErrors
202
-import { experimental_createTool } from "@composio/core";
203
-import { z } from "zod";
204
-
205
-const createDraft = experimental_createTool("CREATE_DRAFT", {
206
- name: "Create Gmail draft",
207
- description: "Create a Gmail draft via the Gmail API",
208
- extendsToolkit: "gmail",
209
- inputParams: z.object({
210
- to: z.string().describe("Recipient email"),
211
- subject: z.string().describe("Email subject"),
212
- body: z.string().describe("Email body"),
213
- }),
214
- execute: async (input, ctx) => {
215
- // proxyExecute routes through the session's Gmail auth
216
- const res = await ctx.proxyExecute({
217
- toolkit: "gmail",
218
- endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
219
- method: "POST",
220
- body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },
221
- });
222
- return res.data as Record<string, unknown>;
223
- },
224
-});
225
-```
226
-
227
-The `SessionContext` (`ctx`) provides:
228
-- **`ctx.proxyExecute(params)`** — Make authenticated HTTP requests through Composio's auth layer. Params: `toolkit`, `endpoint`, `method`, `body?`, `parameters?` (array of `{ in: "query" | "header", name, value }`).
229
-- **`ctx.execute(toolSlug, args)`** — Execute any Composio native tool from within your custom tool.
230
-
231
-### Custom toolkit
232
-
233
-Group related tools under a namespace using `experimental_createToolkit`:
234
-
235
-```ts
236
-// @noErrors
237
-import { experimental_createTool, experimental_createToolkit } from "@composio/core";
238
-import { z } from "zod";
239
-
240
-const setRole = experimental_createTool("SET_ROLE", {
241
- name: "Set role",
242
- description: "Set a user's role",
243
- inputParams: z.object({
244
- user_id: z.string().describe("User ID"),
245
- role: z.enum(["admin", "developer", "viewer"]).describe("New role"),
246
- }),
247
- execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),
248
-});
249
-
250
-const roleManager = experimental_createToolkit("ROLE_MANAGER", {
251
- name: "Role Manager",
252
- description: "Manage user roles",
253
- tools: [setRole],
254
-});
255
-```
256
-
257
-Tools inside a toolkit must **not** have `extendsToolkit` set — they inherit the toolkit identity instead.
258
-
259
-### Binding to a session
260
-
261
-Pass custom tools and toolkits via the `experimental` option:
262
-
263
-```ts
264
-// @noErrors
265
-import { Composio } from "@composio/core";
266
-
267
-const composio = new Composio();
268
-
269
-const session = await composio.create("user_123", {
270
- toolkits: ["gmail"],
271
- experimental: {
272
- customTools: [getUser, createDraft],
273
- customToolkits: [roleManager],
274
- },
275
-});
276
-
277
-const tools = await session.tools(); // Includes both remote and custom tools
278
-```
279
-
280
-Custom tool slugs are automatically prefixed with `LOCAL_` (e.g. `GET_USER` → `LOCAL_GET_USER`, toolkit tools get `LOCAL_ROLE_MANAGER_SET_ROLE`). The final slug must not exceed 60 characters. Slugs cannot start with `LOCAL_` or `COMPOSIO_`.
281
-
166
## Session methods
167
168
### mcp
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
new
+125
@@ -0,0 +1,125 @@
1
+---
2
+title: "Custom Tools and Toolkits (Beta)"
3
+description: Define local tools that run in-process alongside remote Composio tools
4
+keywords: [custom tools, custom toolkits, beta, experimental, local tools, proxy execute]
5
+---
6
+
7
+<Callout type="warn">
8
+Custom tools are experimental. The `experimental_` prefix and `experimental` session option may change in future releases. TypeScript only.
9
+</Callout>
10
+
11
+Custom tools let you define local tools that run in-process alongside remote Composio tools within a session.
12
+
13
+## Standalone tool
14
+
15
+A tool with no Composio-managed authentication — just input and an execute function:
16
+
17
+```ts
18
+// @noErrors
19
+import { experimental_createTool } from "@composio/core";
20
+import { z } from "zod";
21
+
22
+const getUser = experimental_createTool("GET_USER", {
23
+ name: "Get user",
24
+ description: "Look up an internal user by ID",
25
+ inputParams: z.object({
26
+ user_id: z.string().describe("User ID"),
27
+ }),
28
+ execute: async ({ user_id }) => {
29
+ return { name: "Alice", email: "alice@acme.com" };
30
+ },
31
+});
32
+```
33
+
34
+## Extension tool
35
+
36
+A tool that inherits authentication from an existing Composio toolkit via `extendsToolkit`. The second argument to `execute` is a `SessionContext` that lets you make authenticated API calls or invoke other tools:
37
+
38
+```ts
39
+// @noErrors
40
+import { experimental_createTool } from "@composio/core";
41
+import { z } from "zod";
42
+
43
+const createDraft = experimental_createTool("CREATE_DRAFT", {
44
+ name: "Create Gmail draft",
45
+ description: "Create a Gmail draft via the Gmail API",
46
+ extendsToolkit: "gmail",
47
+ inputParams: z.object({
48
+ to: z.string().describe("Recipient email"),
49
+ subject: z.string().describe("Email subject"),
50
+ body: z.string().describe("Email body"),
51
+ }),
52
+ execute: async (input, ctx) => {
53
+ const res = await ctx.proxyExecute({
54
+ toolkit: "gmail",
55
+ endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
56
+ method: "POST",
57
+ body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },
58
+ });
59
+ return res.data as Record<string, unknown>;
60
+ },
61
+});
62
+```
63
+
64
+### SessionContext
65
+
66
+The `ctx` object passed to extension tools provides:
67
+
68
+| Method | Description |
69
+|--------|-------------|
70
+| `ctx.proxyExecute(params)` | Make authenticated HTTP requests through Composio's auth layer. Params: `toolkit`, `endpoint`, `method`, `body?`, `parameters?` (array of `{ in: "query" \| "header", name, value }`). |
71
+| `ctx.execute(toolSlug, args)` | Execute any Composio native tool from within your custom tool. |
72
+
73
+## Custom toolkit
74
+
75
+Group related tools under a namespace with `experimental_createToolkit`. Tools inside a toolkit must **not** use `extendsToolkit` — they inherit the toolkit identity instead:
76
+
77
+```ts
78
+// @noErrors
79
+import { experimental_createTool, experimental_createToolkit } from "@composio/core";
80
+import { z } from "zod";
81
+
82
+const setRole = experimental_createTool("SET_ROLE", {
83
+ name: "Set role",
84
+ description: "Set a user's role",
85
+ inputParams: z.object({
86
+ user_id: z.string().describe("User ID"),
87
+ role: z.enum(["admin", "developer", "viewer"]).describe("New role"),
88
+ }),
89
+ execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),
90
+});
91
+
92
+const roleManager = experimental_createToolkit("ROLE_MANAGER", {
93
+ name: "Role Manager",
94
+ description: "Manage user roles",
95
+ tools: [setRole],
96
+});
97
+```
98
+
99
+## Binding to a session
100
+
101
+Pass custom tools and toolkits via the `experimental` option when creating a session:
102
+
103
+```ts
104
+// @noErrors
105
+import { Composio } from "@composio/core";
106
+
107
+const composio = new Composio();
108
+
109
+const session = await composio.create("user_123", {
110
+ toolkits: ["gmail"],
111
+ experimental: {
112
+ customTools: [getUser, createDraft],
113
+ customToolkits: [roleManager],
114
+ },
115
+});
116
+
117
+const tools = await session.tools(); // Includes both remote and custom tools
118
+```
119
+
120
+## Slug rules
121
+
122
+- Tool slugs are automatically prefixed with `LOCAL_` (e.g. `GET_USER` becomes `LOCAL_GET_USER`)
123
+- Toolkit tools get both prefixes (e.g. `LOCAL_ROLE_MANAGER_SET_ROLE`)
124
+- Final slug must not exceed 60 characters
125
+- Slugs cannot start with `LOCAL_` or `COMPOSIO_`
docs/content/docs/toolkits/meta.json
+2
-1
@@ -2,6 +2,7 @@
2
"title": "Toolkits",
3
"pages": [
4
"fetching-tools-and-toolkits",
5
- "enable-and-disable-toolkits"
5
+ "enable-and-disable-toolkits",
6
+ "custom-tools-and-toolkits"
7
]
8
}