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: clarify tool discovery and direct execution guidance
Brendan O'Leary committed
Sep 22, 2026 at 14:07 UTC
c30c8d64f65086792bb130f908ad4bd24d08bd27
10 files changed
+47
-28
docs/content/docs/meta.json
+1
-1
@@ -24,7 +24,7 @@
24
"extending-sessions",
25
"setting-up-triggers",
26
"poc-to-prod",
27
- "---Direct execution (legacy)---",
27
+ "---Direct execution---",
28
"sessions-vs-direct-execution",
29
"tools-direct",
30
"auth-configuration",
docs/content/docs/quickstart.mdx
+2
@@ -6,6 +6,8 @@ keywords: [tutorial, setup, first agent, sessions, tool router]
6
7
Build an agent that chooses Composio tools at runtime. Type a task, connect an app if needed, and continue in the same conversation.
8
9
+If your application needs to select and approve each app-tool call, compare [sessions and direct execution](/docs/sessions-vs-direct-execution) before choosing an integration.
10
+
11
12
<div className="not-prose my-6 grid grid-cols-1 items-start gap-4 md:grid-cols-2">
13
<div>
docs/content/docs/sessions-vs-direct-execution.mdx
+5
-4
@@ -2,14 +2,15 @@
2
title: Sessions vs Direct Execution
3
description: When to use session-based meta tools vs direct tool fetching and execution
4
keywords: [session, direct execution, tool router, meta tools, architecture, decision]
5
-legacy: true
5
---
6
7
A **session** is the runtime context Composio creates for one of your users with `composio.create(userId)`. It ties together the user, available toolkits, auth, and connected accounts. By default it gives your agent [meta tools](/docs/how-composio-works#meta-tools) so the agent discovers which app tools to use, authenticates users, and executes tools at runtime.
8
9
**Direct execution** skips the session. Your code fetches specific tool schemas, manages auth itself, and calls `tools.execute()` directly.
10
12
-Use sessions unless you need full control over which tools are available and when they run.
11
+Start with sessions for runtime tool discovery and managed authentication. Use direct execution when your application selects tool schemas and calls `tools.execute()` itself, including when you need to approve each app-tool call before it runs.
12
+
13
+These are two ways to use the current SDK. Choosing direct execution does not require an older SDK package. Deprecations such as the managed-OAuth `initiate()` endpoint apply to specific methods; see the [Connect Link migration guide](/docs/auth-configuration/migrating-initiate-to-link).
14
15
| | Sessions | Direct execution |
16
|---|---|---|
@@ -19,7 +20,7 @@ Use sessions unless you need full control over which tools are available and whe
20
| **Memory** | Meta tools share context across calls, storing discovered IDs and relationships | You manage state between calls |
21
| **Auth** | [In-chat](/docs/authentication#in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/authentication/manually-authenticating) | You build the auth flow with [connect links](/docs/tools-direct/authenticating-tools) |
22
| **[Sandbox](/docs/sandbox/remote)** | Built in, large responses offloaded automatically | Not available |
22
-| **Human approval** | You configure approval rules on the session. Harder to intercept individual calls since tools are discovered dynamically | You intercept before each call in your code |
23
+| **Human approval** | Your integration must account for meta tools that can execute multiple app-tool calls. See the direct-tools option below | You intercept before each call in your code |
24
| **Latency** | Multiple LLM turns (search, then execute) | Single call |
25
26
Sessions are configurable. [Restrict toolkits](/docs/configuring-sessions), set [auth configs](/docs/auth-configuration/custom-auth-configs) for white-labeled OAuth, and pin [connected accounts](/docs/configuring-sessions#account-selection). See [Configuring Sessions](/docs/configuring-sessions) for the full list.
@@ -182,7 +183,7 @@ const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
183
</Tabs>
184
185
<Callout type="warn">
185
-`tools.get()` returns 20 tools by default. When fetching from multiple toolkits (e.g., `toolkits=["gmail", "github", "tavily"]`), the limit may cut off tools from later toolkits. Increase `limit` or fetch each toolkit separately.
186
+`tools.get()` returns up to 20 tools by default. A limit caps the result count; it does not select tools by task relevance. When fetching from multiple toolkits (e.g., `toolkits=["gmail", "github", "tavily"]`), the limit may cut off tools from later toolkits. For a fixed workflow, fetch explicit tool names. See [tool filtering and the TypeScript important filter](/docs/tools-direct/fetching-tools#by-toolkit).
187
</Callout>
188
189
With direct execution, you manage [auth configs](/docs/auth-configuration/custom-auth-configs), [connect links](/docs/tools-direct/authenticating-tools), and [toolkit versioning](/docs/tools-direct/toolkit-versioning) yourself.
docs/content/docs/tools-direct/authenticating-tools.mdx
+4
-1
@@ -3,7 +3,6 @@ title: Authenticating Tools
3
description: Create auth configs and connect user accounts
4
keywords: [oauth, api key, auth config, connect account, credentials]
5
llmGuardrails: "direct-execution"
6
-legacy: true
6
---
7
8
<Callout type="info">
@@ -18,6 +17,10 @@ An **Auth Config** is a blueprint that defines how authentication works for a to
17
2. **Scopes** - what actions your tools can perform
18
3. **Credentials** - whether you'll use your own app credentials or Composio's managed auth
19
20
+<Callout type="info" title="Connecting accounts with managed OAuth">
21
+For Composio-managed OAuth, use `connectedAccounts.link()` in TypeScript or `connected_accounts.link()` in Python. Follow [Hosted Authentication](#hosted-authentication-connect-link) below. `initiate()` remains available for custom OAuth configs and non-OAuth schemes. See the [migration guide](/docs/auth-configuration/migrating-initiate-to-link).
22
+</Callout>
23
+
24
## Creating an auth config
25
26
### Using the Dashboard
docs/content/docs/tools-direct/executing-tools.mdx
+2
-3
@@ -1,9 +1,8 @@
1
---
2
title: Executing tools directly
3
-description: Maintain legacy code that calls composio.tools.execute() and other direct tool APIs
3
+description: Execute tools from your application with composio.tools.execute()
4
keywords: [execute, run, tool calling, function calling, direct execution]
5
llmGuardrails: "direct-execution"
6
-legacy: true
6
---
7
8
<Callout type="info">
@@ -218,7 +217,7 @@ See [toolkit versioning](/docs/tools-direct/toolkit-versioning) for the full tra
217
</Callout>
218
219
<Callout type="info">
221
-**Finding a toolkit and tool:** browse the [Toolkits catalog](/toolkits) — each toolkit page lists its tool slugs and current version — or search by task from the CLI: `composio search "send an email"`. You can also [search tools semantically](/docs/tools-direct/fetching-tools#by-search-experimental) from the SDK.
220
+**Finding a toolkit and tool:** browse the [Toolkits catalog](/toolkits) — each toolkit page lists its tool slugs and current version — or search by task from the CLI: `composio search "send an email"`. You can also [search tools by action keywords](/docs/tools-direct/fetching-tools#by-search-experimental) from the SDK.
221
222
**Finding tool parameters and types:**
223
docs/content/docs/tools-direct/fetching-tools.mdx
+26
-13
@@ -3,11 +3,10 @@ title: Fetching tools and schemas
3
description: Fetch and filter tools, and inspect schemas
4
keywords: [get tools, list tools, filter, schema]
5
llmGuardrails: "direct-execution"
6
-legacy: true
6
---
7
8
<Callout type="info">
10
-If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. See [Tools and toolkits](/docs/how-composio-works) for how sessions discover and fetch tools automatically.
9
+Use this guide when your code selects tools and controls execution. For runtime discovery through sessions, see [Tools and toolkits](/docs/how-composio-works). Compare both approaches in [Sessions vs direct execution](/docs/sessions-vs-direct-execution).
10
</Callout>
11
12
Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.
@@ -38,7 +37,7 @@ const tools = await composio.tools.get(userId, {
37
</Tab>
38
</Tabs>
39
41
-Returns top 20 tools by default. Tools require a `user_id` because they're scoped to authenticated accounts. See [User scoping](/docs/how-composio-works) and [Authentication](/docs/tools-direct/authenticating-tools).
40
+Returns up to 20 tools by default. Tools require a `user_id` because they're scoped to authenticated accounts. See [User scoping](/docs/how-composio-works) and [Authentication](/docs/tools-direct/authenticating-tools).
41
42
## Tool schemas
43
@@ -70,7 +69,13 @@ View tool parameters and schemas visually in the [Composio platform](https://das
69
70
### By toolkit
71
73
-Get tools from specific apps. Returns top 20 tools by default.
72
+Get tools from specific apps. Returns up to 20 tools by default.
73
+
74
+`limit` caps the number of returned tools. It does not select the tools needed for a task or guarantee relevance order. A small limit can exclude the tool you need. For a fixed workflow, [fetch explicit tool names](#by-name).
75
+
76
+<Callout type="info" title="TypeScript: limit and important tools">
77
+When you filter only by toolkit, the TypeScript SDK automatically requests tools marked `important` unless you set `important: false`. Supplying `limit`, `search`, or `tags` disables that automatic filter. To keep the important subset with a limit, pass `important: true` explicitly. The Python SDK does not expose this option.
78
+</Callout>
79
80
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
81
<Tab value="Python">
@@ -79,7 +84,7 @@ Get tools from specific apps. Returns top 20 tools by default.
84
tools = composio.tools.get(
85
user_id,
86
toolkits=["GITHUB"],
82
- limit=5 # Get top 5 tools
87
+ limit=5 # Return at most 5 tools
88
)
89
90
# Same filter but without user_id (for schemas)
@@ -98,12 +103,14 @@ const userId = 'user-123';
103
// Fetch with limit for a specific user
104
const limitedTools = await composio.tools.get(userId, {
105
toolkits: ["GITHUB"],
101
- limit: 5 // Get top 5 tools
106
+ important: true,
107
+ limit: 5 // Return at most 5 important tools
108
});
109
110
// Same filter but without userId (for schemas)
111
const rawTools = await composio.tools.getRawComposioTools({
112
toolkits: ["GITHUB"],
113
+ important: true,
114
limit: 5
115
});
116
```
@@ -180,20 +187,24 @@ const scopedTools = await composio.tools.get(userId, {
187
188
### By search (experimental)
189
183
-Find tools semantically.
190
+Search for tools with the `search` option. Start with short action keywords such as `create event`, `free busy`, or `send email`, and narrow the query with `toolkits` when you know the app.
191
+
192
+Inspect the returned descriptions and input schemas before selecting a tool. Do not assume the first result is the best match or that a natural-language goal returns every relevant tool. If you get no results, shorten the query or [fetch a known tool by name](#by-name).
193
194
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
195
<Tab value="Python">
196
```python
188
-# Search tools semantically
197
+# Search tools by action keywords
198
tools = composio.tools.get(
199
user_id,
191
- search="create calendar event"
200
+ search="create event",
201
+ toolkits=["googlecalendar"]
202
)
203
204
# Search schemas without user_id
205
raw_tools = composio.tools.get_raw_composio_tools(
196
- search="create calendar event"
206
+ search="create event",
207
+ toolkits=["googlecalendar"]
208
)
209
210
# Search within a specific toolkit
@@ -216,14 +227,16 @@ import { Composio } from '@composio/core';
227
const composio = new Composio({ apiKey: 'your_api_key' });
228
const userId = 'user-123';
229
// ---cut---
219
-// Search tools semantically
230
+// Search tools by action keywords
231
const searchResults = await composio.tools.get(userId, {
221
- search: "create google calendar event"
232
+ search: "create event",
233
+ toolkits: ["googlecalendar"]
234
});
235
236
// Search schemas without userId
237
const searchRawTools = await composio.tools.getRawComposioTools({
226
- search: "create google calendar event"
238
+ search: "create event",
239
+ toolkits: ["googlecalendar"]
240
});
241
242
// Search within a specific toolkit
docs/content/reference/sdk-reference/typescript/toolkits.mdx
+1
-1
@@ -9,7 +9,7 @@ Access this class through the `composio.toolkits` property:
9
10
```typescript
11
const composio = new Composio({ apiKey: 'your-api-key' });
12
-const result = await composio.toolkits.list();
12
+const result = await composio.toolkits.get({});
13
```
14
15
## Methods
docs/lib/home-navigation.ts
+1
-1
@@ -167,7 +167,7 @@ export const DOCS_PRODUCTS = {
167
],
168
},
169
{
170
- label: 'Migration and legacy',
170
+ label: 'Direct execution and migration',
171
items: [
172
{ type: 'folder', path: 'migration-guide' },
173
{ type: 'page', url: '/docs/sessions-vs-direct-execution' },
docs/tests/static/navigation.test.ts
+3
-3
@@ -49,7 +49,7 @@ async function exists(path: string): Promise<boolean> {
49
}
50
51
describe("Navigation - meta.json validity", () => {
52
- test("root navigation separates current and legacy paths", async () => {
52
+ test("root navigation separates sessions, direct execution, and migration", async () => {
53
const metaPath = join(CONTENT_DIR, "meta.json");
54
const meta = JSON.parse(await readFile(metaPath, "utf-8"));
55
const pages = meta.pages as string[];
@@ -59,7 +59,7 @@ describe("Navigation - meta.json validity", () => {
59
"---Get Started---",
60
"---Core concepts---",
61
"---Guides---",
62
- "---Direct execution (legacy)---",
62
+ "---Direct execution---",
63
"---Migration and security---",
64
]);
65
@@ -76,7 +76,7 @@ describe("Navigation - meta.json validity", () => {
76
77
expect(
78
pages.slice(
79
- pages.indexOf("---Direct execution (legacy)---") + 1,
79
+ pages.indexOf("---Direct execution---") + 1,
80
pages.indexOf("---Migration and security---")
81
)
82
).toEqual([
ts/packages/core/scripts/generate-docs.ts
+2
-1
@@ -1012,7 +1012,8 @@ function generateClassMdx(classDoc: ClassDoc): string {
1012
lines.push('');
1013
lines.push('```typescript');
1014
lines.push(`const composio = new Composio({ apiKey: 'your-api-key' });`);
1015
- lines.push(`const result = await composio.${accessorName}.list();`);
1015
+ const usageCall = classDoc.name === 'Toolkits' ? 'get({})' : 'list()';
1016
+ lines.push(`const result = await composio.${accessorName}.${usageCall};`);
1017
lines.push('```');
1018
lines.push('');
1019
}