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).