@devries-cameron20 / composio Mirror · read-only / commits / c30c8d64f
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 11:00 UTC

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 }