@devries-cameron20 / composio-1 / commits / 11588f8d7
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: restructure custom tools page with Steps and IntegrationTabs

- Split into IntegrationTabs (Standalone Tool / Extension Tool / Custom Toolkit) each with its own 4-step flow (Install, Initialize, Create, Bind) - Simplified experimental callout - Replaced dense bullet lists with tables (meta tools, ctx reference) - Added code snippets for verifying registration and programmatic execution - Broke best practices into separate subsections - Removed em dash from MCP callout Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Sushmithamallesh committed Mar 30, 2026 at 22:28 UTC 11588f8d71f2ffcea2696e969cbda2163c6dff25
1 file changed +437 -108
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+437 -108
@@ -5,32 +5,77 @@ keywords: [custom tools, custom toolkits, experimental, local tools, proxy execu
5 ---
6
7 <Callout type="warn">
8 -Custom tool APIs are experimental. TypeScript uses `experimental_createTool()` / `experimental_createToolkit()`. Python uses `@composio.experimental.tool()` / `composio.experimental.Toolkit(...)`. The session `experimental` option may change in future releases.
8 +Custom tool APIs are experimental and may change in future releases.
9 </Callout>
10
11 <Callout type="info">
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.
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:
16
17 -- **Standalone tools** — for internal app logic that doesn't need Composio auth (DB lookups, in-memory data, business rules)
18 -- **Extension tools** — wrap a Composio toolkit's API with custom business logic via `extendsToolkit` / `extends_toolkit`, using `ctx.proxyExecute()` / `ctx.proxy_execute()` for authenticated requests
19 -- **Custom toolkits** — group related standalone tools under a namespace
17 +- **Standalone tools** - for internal app logic that doesn't need Composio auth (DB lookups, in-memory data, business rules)
18 +- **Extension tools** - wrap a Composio toolkit's API with custom business logic via `extendsToolkit` / `extends_toolkit`, using `ctx.proxyExecute()` / `ctx.proxy_execute()` for authenticated requests
19 +- **Custom toolkits** - group related standalone tools under a namespace
20
21 -The example below defines one of each and binds them to a session:
21 +<IntegrationTabs tabs={[
22 + { value: "standalone", label: "Standalone Tool" },
23 + { value: "extension", label: "Extension Tool" },
24 + { value: "toolkit", label: "Custom Toolkit" },
25 +]}>
26 +
27 +<IntegrationContent value="standalone">
28 +<Steps>
29 +<Step>
30 +**Install**
31
32 <Tabs groupId="language" items={['TypeScript', 'Python']} persist>
33 <Tab value="TypeScript">
34 +```bash
35 +npm install @composio/core zod
36 +```
37 +</Tab>
38 +<Tab value="Python">
39 +```bash
40 +pip install composio
41 +```
42 +</Tab>
43 +</Tabs>
44 +</Step>
45 +
46 +<Step>
47 +**Initialize the client**
48
49 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
50 +<Tab value="TypeScript">
51 ```typescript
27 -import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
52 +import { Composio } from "@composio/core";
53 +
54 +const composio = new Composio({ apiKey: "your_api_key" });
55 +```
56 +</Tab>
57 +<Tab value="Python">
58 +```python
59 +from composio import Composio
60 +
61 +composio = Composio(api_key="your_api_key")
62 +```
63 +</Tab>
64 +</Tabs>
65 +</Step>
66 +
67 +<Step>
68 +**Create the tool**
69 +
70 +A standalone tool handles internal app logic that doesn't need Composio auth. `ctx.userId` identifies which user's session is running.
71 +
72 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
73 +<Tab value="TypeScript">
74 +```typescript
75 +import { Composio, experimental_createTool } from "@composio/core";
76 import { z } from "zod/v3";
77 // ---cut---
78
31 -// ── Standalone tool ─────────────────────────────────────────────
32 -// Internal data lookup — no Composio auth needed.
33 -// ctx.userId identifies which user's session is running.
79 const profiles: Record<string, { name: string; email: string; tier: string }> = {
80 "user_1": { name: "Alice Johnson", email: "alice@myapp.com", tier: "enterprise" },
81 "user_2": { name: "Bob Smith", email: "bob@myapp.com", tier: "free" },
@@ -46,10 +91,136 @@ const getUserProfile = experimental_createTool("GET_USER_PROFILE", {
91 return profile;
92 },
93 });
94 +```
95 +</Tab>
96 +<Tab value="Python">
97 +```python
98 +from pydantic import BaseModel, Field
99 +
100 +from composio import Composio
101 +
102 +composio = Composio(api_key="your_api_key")
103 +
104 +
105 +class UserLookupInput(BaseModel):
106 + user_id: str = Field(description="User ID")
107 +
108 +
109 +USERS = {
110 + "user_1": {"name": "Alice Johnson", "email": "alice@myapp.com", "tier": "enterprise"},
111 + "user_2": {"name": "Bob Smith", "email": "bob@myapp.com", "tier": "free"},
112 +}
113 +
114 +
115 +@composio.experimental.tool()
116 +def get_user_profile(input: UserLookupInput, ctx):
117 + """Retrieve the current user's profile from the internal directory."""
118 + profile = USERS.get(input.user_id)
119 + if not profile:
120 + raise ValueError(f'No profile found for user "{input.user_id}"')
121 + return profile
122 +```
123 +</Tab>
124 +</Tabs>
125 +</Step>
126 +
127 +<Step>
128 +**Bind to a session**
129 +
130 +Pass custom tools via the `experimental` option. `session.tools()` returns both remote Composio tools and your custom tools.
131 +
132 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
133 +<Tab value="TypeScript">
134 +```typescript
135 +import { Composio, experimental_createTool } from "@composio/core";
136 +import { z } from "zod/v3";
137 +
138 +declare const getUserProfile: ReturnType<typeof experimental_createTool>;
139 +const composio = new Composio({ apiKey: "your_api_key" });
140 +// ---cut---
141 +
142 +const session = await composio.create("user_1", {
143 + experimental: {
144 + customTools: [getUserProfile],
145 + },
146 +});
147 +
148 +const tools = await session.tools();
149 +```
150 +</Tab>
151 +<Tab value="Python">
152 +```python
153 +from composio import Composio
154 +
155 +composio = Composio(api_key="your_api_key")
156 +
157 +session = composio.create(
158 + user_id="user_1",
159 + experimental={
160 + "custom_tools": [get_user_profile],
161 + },
162 +)
163 +
164 +tools = session.tools()
165 +```
166 +</Tab>
167 +</Tabs>
168 +</Step>
169 +</Steps>
170 +</IntegrationContent>
171 +
172 +<IntegrationContent value="extension">
173 +<Steps>
174 +<Step>
175 +**Install**
176 +
177 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
178 +<Tab value="TypeScript">
179 +```bash
180 +npm install @composio/core zod
181 +```
182 +</Tab>
183 +<Tab value="Python">
184 +```bash
185 +pip install composio
186 +```
187 +</Tab>
188 +</Tabs>
189 +</Step>
190 +
191 +<Step>
192 +**Initialize the client**
193 +
194 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
195 +<Tab value="TypeScript">
196 +```typescript
197 +import { Composio } from "@composio/core";
198 +
199 +const composio = new Composio({ apiKey: "your_api_key" });
200 +```
201 +</Tab>
202 +<Tab value="Python">
203 +```python
204 +from composio import Composio
205 +
206 +composio = Composio(api_key="your_api_key")
207 +```
208 +</Tab>
209 +</Tabs>
210 +</Step>
211 +
212 +<Step>
213 +**Create the tool**
214 +
215 +An extension tool wraps a Composio toolkit's API with custom business logic. It inherits auth via `extendsToolkit` / `extends_toolkit`, so `ctx.proxyExecute()` / `ctx.proxy_execute()` handles credentials automatically.
216 +
217 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
218 +<Tab value="TypeScript">
219 +```typescript
220 +import { Composio, experimental_createTool } from "@composio/core";
221 +import { z } from "zod/v3";
222 +// ---cut---
223
50 -// ── Extension tool ──────────────────────────────────────────────
51 -// Wraps Gmail API with business logic. Inherits auth via extendsToolkit,
52 -// so ctx.proxyExecute() handles credentials automatically.
224 const sendPromoEmail = experimental_createTool("SEND_PROMO_EMAIL", {
225 name: "Send promo email",
226 description: "Send the standard promotional email to a recipient",
@@ -71,45 +242,9 @@ const sendPromoEmail = experimental_createTool("SEND_PROMO_EMAIL", {
242 return { status: res.status, to: input.to };
243 },
244 });
74 -
75 -// ── Custom toolkit ──────────────────────────────────────────────
76 -// Groups standalone tools that don't need Composio auth under a toolkit.
77 -// Tools inside a toolkit cannot use extendsToolkit.
78 -const userManagement = experimental_createToolkit("USER_MANAGEMENT", {
79 - name: "User management",
80 - description: "Manage user roles and permissions",
81 - tools: [
82 - experimental_createTool("ASSIGN_ROLE", {
83 - name: "Assign role",
84 - description: "Assign a role to a user in the internal system",
85 - inputParams: z.object({
86 - user_id: z.string().describe("Target user ID"),
87 - role: z.enum(["admin", "editor", "viewer"]).describe("Role to assign"),
88 - }),
89 - execute: async ({ user_id, role }) => ({ user_id, role, assigned: true }),
90 - }),
91 - ],
92 -});
93 -
94 -// ── Bind to session ─────────────────────────────────────────────
95 -// Pass custom tools and toolkits via the experimental option.
96 -// session.tools() returns both remote Composio tools and your custom tools.
97 -const composio = new Composio({ apiKey: "your_api_key" });
98 -
99 -const session = await composio.create("user_1", {
100 - toolkits: ["gmail"],
101 - experimental: {
102 - customTools: [getUserProfile, sendPromoEmail],
103 - customToolkits: [userManagement],
104 - },
105 -});
106 -
107 -const tools = await session.tools();
245 ```
109 -
246 </Tab>
247 <Tab value="Python">
112 -
248 ```python
249 import base64
250
@@ -117,29 +252,9 @@ from pydantic import BaseModel, Field
252
253 from composio import Composio
254
120 -
255 composio = Composio(api_key="your_api_key")
256
257
124 -class UserLookupInput(BaseModel):
125 - user_id: str = Field(description="User ID")
126 -
127 -
128 -USERS = {
129 - "user_1": {"name": "Alice Johnson", "email": "alice@myapp.com", "tier": "enterprise"},
130 - "user_2": {"name": "Bob Smith", "email": "bob@myapp.com", "tier": "free"},
131 -}
132 -
133 -
134 -@composio.experimental.tool()
135 -def get_user_profile(input: UserLookupInput, ctx):
136 - """Retrieve the current user's profile from the internal directory."""
137 - profile = USERS.get(input.user_id)
138 - if not profile:
139 - raise ValueError(f'No profile found for user "{input.user_id}"')
140 - return profile
141 -
142 -
258 class PromoEmailInput(BaseModel):
259 to: str = Field(description="Recipient email address")
260
@@ -168,7 +283,134 @@ def send_promo_email(input: PromoEmailInput, ctx):
283 body={"raw": raw},
284 )
285 return {"status": res.status, "to": input.to}
286 +```
287 +</Tab>
288 +</Tabs>
289 +</Step>
290 +
291 +<Step>
292 +**Bind to a session**
293 +
294 +Pass custom tools via the `experimental` option. Extension tools inherit auth from the toolkit specified in `extendsToolkit`.
295 +
296 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
297 +<Tab value="TypeScript">
298 +```typescript
299 +import { Composio, experimental_createTool } from "@composio/core";
300 +import { z } from "zod/v3";
301 +
302 +declare const sendPromoEmail: ReturnType<typeof experimental_createTool>;
303 +const composio = new Composio({ apiKey: "your_api_key" });
304 +// ---cut---
305 +
306 +const session = await composio.create("user_1", {
307 + toolkits: ["gmail"],
308 + experimental: {
309 + customTools: [sendPromoEmail],
310 + },
311 +});
312 +
313 +const tools = await session.tools();
314 +```
315 +</Tab>
316 +<Tab value="Python">
317 +```python
318 +from composio import Composio
319 +
320 +composio = Composio(api_key="your_api_key")
321 +
322 +session = composio.create(
323 + user_id="user_1",
324 + toolkits=["gmail"],
325 + experimental={
326 + "custom_tools": [send_promo_email],
327 + },
328 +)
329 +
330 +tools = session.tools()
331 +```
332 +</Tab>
333 +</Tabs>
334 +</Step>
335 +</Steps>
336 +</IntegrationContent>
337 +
338 +<IntegrationContent value="toolkit">
339 +<Steps>
340 +<Step>
341 +**Install**
342 +
343 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
344 +<Tab value="TypeScript">
345 +```bash
346 +npm install @composio/core zod
347 +```
348 +</Tab>
349 +<Tab value="Python">
350 +```bash
351 +pip install composio
352 +```
353 +</Tab>
354 +</Tabs>
355 +</Step>
356 +
357 +<Step>
358 +**Initialize the client**
359 +
360 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
361 +<Tab value="TypeScript">
362 +```typescript
363 +import { Composio } from "@composio/core";
364 +
365 +const composio = new Composio({ apiKey: "your_api_key" });
366 +```
367 +</Tab>
368 +<Tab value="Python">
369 +```python
370 +from composio import Composio
371 +
372 +composio = Composio(api_key="your_api_key")
373 +```
374 +</Tab>
375 +</Tabs>
376 +</Step>
377 +
378 +<Step>
379 +**Create the toolkit**
380 +
381 +A custom toolkit groups related standalone tools under a namespace. Tools inside a toolkit cannot use `extendsToolkit`.
382 +
383 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
384 +<Tab value="TypeScript">
385 +```typescript
386 +import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
387 +import { z } from "zod/v3";
388 +// ---cut---
389 +
390 +const userManagement = experimental_createToolkit("USER_MANAGEMENT", {
391 + name: "User management",
392 + description: "Manage user roles and permissions",
393 + tools: [
394 + experimental_createTool("ASSIGN_ROLE", {
395 + name: "Assign role",
396 + description: "Assign a role to a user in the internal system",
397 + inputParams: z.object({
398 + user_id: z.string().describe("Target user ID"),
399 + role: z.enum(["admin", "editor", "viewer"]).describe("Role to assign"),
400 + }),
401 + execute: async ({ user_id, role }) => ({ user_id, role, assigned: true }),
402 + }),
403 + ],
404 +});
405 +```
406 +</Tab>
407 +<Tab value="Python">
408 +```python
409 +from pydantic import BaseModel, Field
410 +
411 +from composio import Composio
412
413 +composio = Composio(api_key="your_api_key")
414
415 user_management = composio.experimental.Toolkit(
416 slug="USER_MANAGEMENT",
@@ -186,80 +428,167 @@ class AssignRoleInput(BaseModel):
428 def assign_role(input: AssignRoleInput, ctx):
429 """Assign a role to a user in the internal system."""
430 return {"user_id": input.user_id, "role": input.role, "assigned": True}
431 +```
432 +</Tab>
433 +</Tabs>
434 +</Step>
435 +
436 +<Step>
437 +**Bind to a session**
438
439 +Pass custom toolkits via the `experimental` option. `session.tools()` returns both remote Composio tools and your custom toolkit's tools.
440 +
441 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
442 +<Tab value="TypeScript">
443 +```typescript
444 +import { Composio, experimental_createToolkit } from "@composio/core";
445 +import { z } from "zod/v3";
446 +
447 +declare const userManagement: ReturnType<typeof experimental_createToolkit>;
448 +const composio = new Composio({ apiKey: "your_api_key" });
449 +// ---cut---
450 +
451 +const session = await composio.create("user_1", {
452 + experimental: {
453 + customToolkits: [userManagement],
454 + },
455 +});
456 +
457 +const tools = await session.tools();
458 +```
459 +</Tab>
460 +<Tab value="Python">
461 +```python
462 +from composio import Composio
463 +
464 +composio = Composio(api_key="your_api_key")
465
466 session = composio.create(
467 user_id="user_1",
193 - toolkits=["gmail"],
468 experimental={
195 - "custom_tools": [get_user_profile, send_promo_email],
469 "custom_toolkits": [user_management],
470 },
471 )
472
473 tools = session.tools()
474 ```
202 -
475 </Tab>
476 </Tabs>
477 +</Step>
478 +</Steps>
479 +</IntegrationContent>
480
206 -## How custom tools work with meta tools
481 +</IntegrationTabs>
482
208 -Custom tools integrate seamlessly with Composio's meta tools:
483 +## Meta tools integration
484
210 -- **`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
211 -- **`COMPOSIO_GET_TOOL_SCHEMAS`** returns schemas for custom tools alongside remote tools — the agent sees them as first-class tools
212 -- **`COMPOSIO_MULTI_EXECUTE_TOOL`** intelligently splits execution — custom tools run in-process while remote tools go to the backend, results are merged transparently
213 -- **`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
214 -- Custom tools are **not supported in Workbench** — the LLM is made aware of this and will not attempt to use them there
485 +Custom tools work automatically with Composio's meta tools:
486
216 -## Best practices
487 +| Meta tool | Behavior |
488 +|-----------|----------|
489 +| `COMPOSIO_SEARCH_TOOLS` | Includes custom tools in search results, with slight priority for tools that don't require auth |
490 +| `COMPOSIO_GET_TOOL_SCHEMAS` | Returns schemas for custom tools alongside remote tools |
491 +| `COMPOSIO_MULTI_EXECUTE_TOOL` | Runs custom tools in-process while remote tools go to the backend, merging results transparently |
492 +| `COMPOSIO_MANAGE_CONNECTIONS` | Handles auth for extension tools. If a tool extends `gmail`, the agent can prompt the user to connect Gmail |
493
218 -- **Descriptive names and slugs** — The agent sees your tool's name and description to decide when to use it. Be specific: "Send weekly promo email" is better than "Send email". In TypeScript, define uppercase slugs like `SEND_PROMO_EMAIL`. In Python, inferred slugs come from the function name, so `snake_case` function names produce the cleanest defaults; or pass `slug=` / `name=` explicitly.
219 -- **Detailed descriptions** — Include what the tool does, when to use it, and what it returns. The agent relies on this to pick the right tool.
220 -- **Use `extendsToolkit` / `extends_toolkit` for auth** — If your tool needs Gmail/GitHub/etc. auth for `ctx.proxyExecute()` / `ctx.proxy_execute()` or `ctx.execute()`, set the toolkit extension so connection management is handled seamlessly via `COMPOSIO_MANAGE_CONNECTIONS`.
221 -- **In Python, annotations are the schema** — The first parameter must be a Pydantic `BaseModel`, and its field descriptions become the input schema. Docstrings are used as the default tool description unless you pass `description=`.
222 -- **Tool names get prefixed** — Slugs exposed to the agent are automatically prefixed with `LOCAL_` and the toolkit name (if any). `GET_USER_PROFILE` becomes `LOCAL_GET_USER_PROFILE`, `ASSIGN_ROLE` in `USER_MANAGEMENT` becomes `LOCAL_USER_MANAGEMENT_ASSIGN_ROLE`. Your slugs cannot start with `LOCAL_` — this prefix is reserved.
494 +<Callout type="info">
495 +Custom tools are not supported in Workbench.
496 +</Callout>
497
224 -For more best practices, see [How to Build Tools for AI Agents: A Field Guide](https://composio.dev/blog/how-to-build-tools-for-ai-agents-a-field-guide).
498 +## Context object (`ctx`)
499
226 -## Verifying registration
500 +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.
501
228 -Use `session.customTools()` / `session.customToolkits()` in TypeScript or `session.custom_tools()` / `session.custom_toolkits()` in Python to list registered tools and toolkits. Registered tool slugs include their final `LOCAL_` prefix, and toolkit-scoped tools also include the toolkit slug.
502 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
503 +<Tab value="TypeScript">
504
230 -Reference: [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python ToolRouterSession](/reference/sdk-reference/python/tool-router-session)
505 +| Property / Method | Description |
506 +|-------------------|-------------|
507 +| `ctx.userId` | The user ID for the current session |
508 +| `ctx.proxyExecute({ toolkit, endpoint, method, body?, parameters? })` | Make an authenticated HTTP request via Composio's auth layer |
509 +| `ctx.execute(toolSlug, args)` | Execute any Composio native tool from within your custom tool |
510
232 -## Programmatic execution
511 +</Tab>
512 +<Tab value="Python">
513
234 -Use `session.execute()` to run custom tools directly, outside of an agent loop (e.g. `session.execute("GET_USER_PROFILE")`). Custom tools execute in-process; remote tools are sent to the backend automatically.
514 +| Property / Method | Description |
515 +|-------------------|-------------|
516 +| `ctx.user_id` | The user ID for the current session |
517 +| `ctx.proxy_execute(toolkit, endpoint, method, body=None, parameters=[])` | Make an authenticated HTTP request via Composio's auth layer |
518 +| `ctx.execute(tool_slug, arguments)` | Execute any Composio native tool from within your custom tool |
519
236 -Reference: [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python ToolRouterSession](/reference/sdk-reference/python/tool-router-session)
520 +</Tab>
521 +</Tabs>
522 +
523 +See the full API in the SDK reference: [TypeScript](/reference/sdk-reference/typescript/session-context-impl) | [Python](/reference/sdk-reference/python/session-context-impl)
524
238 -## SessionContext
525 +## Verifying registration
526
240 -Every custom tool's `execute` function receives `(input, ctx)`. The `ctx` object provides:
527 +Use these methods to list registered tools and toolkits. Slugs include their final `LOCAL_` prefix, and toolkit-scoped tools also include the toolkit slug.
528
529 <Tabs groupId="language" items={['TypeScript', 'Python']} persist>
530 <Tab value="TypeScript">
244 -
245 -| Method | Description |
246 -|--------|-------------|
247 -| `ctx.userId` | The user ID for the current session. |
248 -| `ctx.proxyExecute(params)` | Authenticated HTTP request via Composio's auth layer. Params: `toolkit`, `endpoint`, `method`, `body?`, `parameters?` (array of `{ in: "query" \| "header", name, value }`). |
249 -| `ctx.execute(toolSlug, args)` | Execute any Composio native tool from within your custom tool. |
250 -
531 +```typescript
532 +import { Composio } from "@composio/core";
533 +const composio = new Composio({ apiKey: "your_api_key" });
534 +const session = await composio.create("user_1");
535 +// ---cut---
536 +const customTools = session.customTools();
537 +const customToolkits = session.customToolkits();
538 +```
539 </Tab>
540 <Tab value="Python">
541 +```python
542 +custom_tools = session.custom_tools()
543 +custom_toolkits = session.custom_toolkits()
544 +```
545 +</Tab>
546 +</Tabs>
547
254 -| Method | Description |
255 -|--------|-------------|
256 -| `ctx.user_id` | The user ID for the current session. |
257 -| `ctx.proxy_execute(...)` | Authenticated HTTP request via Composio's auth layer. Params: `toolkit`, `endpoint`, `method`, `body=None`, `parameters=[{"in": "query" \| "header", "name": ..., "value": ...}]`. |
258 -| `ctx.execute(tool_slug, arguments)` | Execute any Composio native tool from within your custom tool. |
548 +## Programmatic execution
549
550 +Use `session.execute()` to run custom tools directly, outside of an agent loop. Custom tools execute in-process; remote tools are sent to the backend automatically.
551 +
552 +<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
553 +<Tab value="TypeScript">
554 +```typescript
555 +import { Composio } from "@composio/core";
556 +const composio = new Composio({ apiKey: "your_api_key" });
557 +const session = await composio.create("user_1");
558 +// ---cut---
559 +const result = await session.execute("GET_USER_PROFILE");
560 +```
561 +</Tab>
562 +<Tab value="Python">
563 +```python
564 +result = session.execute("GET_USER_PROFILE")
565 +```
566 </Tab>
567 </Tabs>
568
263 -In Python, `parameters` dictionaries accept both `in` and `type`; this guide uses `in` to match the TypeScript examples.
569 +## Best practices
570 +
571 +### Naming and descriptions
572
265 -Reference: [TypeScript SessionContextImpl](/reference/sdk-reference/typescript/session-context-impl) · [Python SessionContextImpl](/reference/sdk-reference/python/session-context-impl)
573 +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.
574 +
575 +In TypeScript, use uppercase slugs like `SEND_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.
576 +
577 +### Accessing authenticated APIs
578 +
579 +If your tool needs to call an API that requires user credentials (Gmail, GitHub, etc.), set `extendsToolkit` / `extends_toolkit` to the toolkit name. Composio will handle authentication automatically, and the agent can prompt users to connect their account if needed.
580 +
581 +### Defining inputs in Python
582 +
583 +Your tool's first parameter must be a Pydantic `BaseModel`. 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.
584 +
585 +### Tool names get prefixed
586 +
587 +Slugs exposed to the agent are automatically prefixed with `LOCAL_` and the toolkit name (if applicable):
588 +
589 +- `GET_USER_PROFILE` becomes `LOCAL_GET_USER_PROFILE`
590 +- `ASSIGN_ROLE` in `USER_MANAGEMENT` becomes `LOCAL_USER_MANAGEMENT_ASSIGN_ROLE`
591 +
592 +Your slugs cannot start with `LOCAL_`. This prefix is reserved.
593 +
594 +For more best practices, see [How to Build Tools for AI Agents: A Field Guide](https://composio.dev/blog/how-to-build-tools-for-ai-agents-a-field-guide).