Skip to content

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

Dhawal Upadhyayb44fe816f618
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdx
index dfcce99e4..be79c7180 100644
--- a/docs/content/docs/configuring-sessions.mdx
+++ b/docs/content/docs/configuring-sessions.mdx
@@ -1,7 +1,7 @@
---
title: Configuring Sessions
-description: Enable toolkits, set auth configs, select connected accounts, and add custom tools
-keywords: [session, toolkits, auth configs, connected accounts, custom tools, beta]
+description: Enable toolkits, set auth configs, and select connected accounts
+keywords: [session, toolkits, auth configs, connected accounts]
---
## Creating a session
@@ -163,122 +163,6 @@ When executing a tool, the connected account is selected in this order:
If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
-## Custom tools (Beta)
-
-<Callout type="warn">
-Custom tools are experimental. The `experimental_` prefix and `experimental` session option may change in future releases. TypeScript only.
-</Callout>
-
-Custom tools let you define local tools that run in-process alongside remote Composio tools. There are three patterns:
-
-### Standalone tool
-
-A tool that doesn't need any Composio-managed authentication:
-
-```ts
-// @noErrors
-import { experimental_createTool } from "@composio/core";
-import { z } from "zod";
-
-const getUser = experimental_createTool("GET_USER", {
- name: "Get user",
- description: "Look up an internal user by ID",
- inputParams: z.object({
- user_id: z.string().describe("User ID"),
- }),
- execute: async ({ user_id }) => {
- // Your logic here — just return the result
- return { name: "Alice", email: "[email protected]" };
- },
-});
-```
-
-### Extension tool
-
-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()`:
-
-```ts
-// @noErrors
-import { experimental_createTool } from "@composio/core";
-import { z } from "zod";
-
-const createDraft = experimental_createTool("CREATE_DRAFT", {
- name: "Create Gmail draft",
- description: "Create a Gmail draft via the Gmail API",
- extendsToolkit: "gmail",
- inputParams: z.object({
- to: z.string().describe("Recipient email"),
- subject: z.string().describe("Email subject"),
- body: z.string().describe("Email body"),
- }),
- execute: async (input, ctx) => {
- // proxyExecute routes through the session's Gmail auth
- const res = await ctx.proxyExecute({
- toolkit: "gmail",
- endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
- method: "POST",
- body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },
- });
- return res.data as Record<string, unknown>;
- },
-});
-```
-
-The `SessionContext` (`ctx`) provides:
-- **`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 }`).
-- **`ctx.execute(toolSlug, args)`** — Execute any Composio native tool from within your custom tool.
-
-### Custom toolkit
-
-Group related tools under a namespace using `experimental_createToolkit`:
-
-```ts
-// @noErrors
-import { experimental_createTool, experimental_createToolkit } from "@composio/core";
-import { z } from "zod";
-
-const setRole = experimental_createTool("SET_ROLE", {
- name: "Set role",
- description: "Set a user's role",
- inputParams: z.object({
- user_id: z.string().describe("User ID"),
- role: z.enum(["admin", "developer", "viewer"]).describe("New role"),
- }),
- execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),
-});
-
-const roleManager = experimental_createToolkit("ROLE_MANAGER", {
- name: "Role Manager",
- description: "Manage user roles",
- tools: [setRole],
-});
-```
-
-Tools inside a toolkit must **not** have `extendsToolkit` set — they inherit the toolkit identity instead.
-
-### Binding to a session
-
-Pass custom tools and toolkits via the `experimental` option:
-
-```ts
-// @noErrors
-import { Composio } from "@composio/core";
-
-const composio = new Composio();
-
-const session = await composio.create("user_123", {
- toolkits: ["gmail"],
- experimental: {
- customTools: [getUser, createDraft],
- customToolkits: [roleManager],
- },
-});
-
-const tools = await session.tools(); // Includes both remote and custom tools
-```
-
-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_`.
-
## Session methods
### mcp
diff --git a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
new file mode 100644
index 000000000..214b97888
--- /dev/null
+++ b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
@@ -0,0 +1,125 @@
+---
+title: "Custom Tools and Toolkits (Beta)"
+description: Define local tools that run in-process alongside remote Composio tools
+keywords: [custom tools, custom toolkits, beta, experimental, local tools, proxy execute]
+---
+
+<Callout type="warn">
+Custom tools are experimental. The `experimental_` prefix and `experimental` session option may change in future releases. TypeScript only.
+</Callout>
+
+Custom tools let you define local tools that run in-process alongside remote Composio tools within a session.
+
+## Standalone tool
+
+A tool with no Composio-managed authentication — just input and an execute function:
+
+```ts
+// @noErrors
+import { experimental_createTool } from "@composio/core";
+import { z } from "zod";
+
+const getUser = experimental_createTool("GET_USER", {
+ name: "Get user",
+ description: "Look up an internal user by ID",
+ inputParams: z.object({
+ user_id: z.string().describe("User ID"),
+ }),
+ execute: async ({ user_id }) => {
+ return { name: "Alice", email: "[email protected]" };
+ },
+});
+```
+
+## Extension tool
+
+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:
+
+```ts
+// @noErrors
+import { experimental_createTool } from "@composio/core";
+import { z } from "zod";
+
+const createDraft = experimental_createTool("CREATE_DRAFT", {
+ name: "Create Gmail draft",
+ description: "Create a Gmail draft via the Gmail API",
+ extendsToolkit: "gmail",
+ inputParams: z.object({
+ to: z.string().describe("Recipient email"),
+ subject: z.string().describe("Email subject"),
+ body: z.string().describe("Email body"),
+ }),
+ execute: async (input, ctx) => {
+ const res = await ctx.proxyExecute({
+ toolkit: "gmail",
+ endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
+ method: "POST",
+ body: { message: { raw: btoa(`To: ${input.to}\r\nSubject: ${input.subject}\r\n\r\n${input.body}`) } },
+ });
+ return res.data as Record<string, unknown>;
+ },
+});
+```
+
+### SessionContext
+
+The `ctx` object passed to extension tools provides:
+
+| Method | Description |
+|--------|-------------|
+| `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 }`). |
+| `ctx.execute(toolSlug, args)` | Execute any Composio native tool from within your custom tool. |
+
+## Custom toolkit
+
+Group related tools under a namespace with `experimental_createToolkit`. Tools inside a toolkit must **not** use `extendsToolkit` — they inherit the toolkit identity instead:
+
+```ts
+// @noErrors
+import { experimental_createTool, experimental_createToolkit } from "@composio/core";
+import { z } from "zod";
+
+const setRole = experimental_createTool("SET_ROLE", {
+ name: "Set role",
+ description: "Set a user's role",
+ inputParams: z.object({
+ user_id: z.string().describe("User ID"),
+ role: z.enum(["admin", "developer", "viewer"]).describe("New role"),
+ }),
+ execute: async ({ user_id, role }) => ({ user_id, role, updated: true }),
+});
+
+const roleManager = experimental_createToolkit("ROLE_MANAGER", {
+ name: "Role Manager",
+ description: "Manage user roles",
+ tools: [setRole],
+});
+```
+
+## Binding to a session
+
+Pass custom tools and toolkits via the `experimental` option when creating a session:
+
+```ts
+// @noErrors
+import { Composio } from "@composio/core";
+
+const composio = new Composio();
+
+const session = await composio.create("user_123", {
+ toolkits: ["gmail"],
+ experimental: {
+ customTools: [getUser, createDraft],
+ customToolkits: [roleManager],
+ },
+});
+
+const tools = await session.tools(); // Includes both remote and custom tools
+```
+
+## Slug rules
+
+- Tool slugs are automatically prefixed with `LOCAL_` (e.g. `GET_USER` becomes `LOCAL_GET_USER`)
+- Toolkit tools get both prefixes (e.g. `LOCAL_ROLE_MANAGER_SET_ROLE`)
+- Final slug must not exceed 60 characters
+- Slugs cannot start with `LOCAL_` or `COMPOSIO_`
diff --git a/docs/content/docs/toolkits/meta.json b/docs/content/docs/toolkits/meta.json
index b9790828b..4fae1be95 100644
--- a/docs/content/docs/toolkits/meta.json
+++ b/docs/content/docs/toolkits/meta.json
@@ -2,6 +2,7 @@
"title": "Toolkits",
"pages": [
"fetching-tools-and-toolkits",
- "enable-and-disable-toolkits"
+ "enable-and-disable-toolkits",
+ "custom-tools-and-toolkits"
]
}