@devries-cameron20 / composio-1 / commits / f1b1eebe6
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: Fetch and filter tools refactor (#2178)

Sushmitha Mallesh committed Nov 14, 2025 at 23:44 UTC f1b1eebe6ad77e3ff82d675f384e556697a4a727
4 files changed +221 -168
fern/docs.yml
+1 -1
@@ -135,7 +135,7 @@ navigation:
135 - page: Authenticating Tools
136 path: pages/dist/tool-calling/authenticating-tools.mdx
137 slug: authenticating-tools
138 - - page: Fetch and Filter Tools
138 + - page: Fetching tools and schemas
139 path: pages/dist/tool-calling/fetching-tools.mdx
140 slug: fetching-tools
141 - page: Executing Tools
fern/pages/src/tool-calling/fetching-tools.mdx
+94 -167
@@ -1,210 +1,137 @@
1 ---
2 -title: Fetching and Filtering Tools
3 -image: "https://og.composio.dev/api/og?title=Fetching%20and%20Filtering%20Tools" # image for socials
4 -keywords: "fetch tool, filter tool"
5 -subtitle: "Learn how to fetch and filter Composio's tools and toolsets"
2 +title: Fetching tools and schemas
3 +image: "https://og.composio.dev/api/og?title=Fetching%20tools%20and%20schemas" # image for socials
4 +keywords: "fetch tool, filter tool, tool schema, tool types, inspect schema, raw tools"
5 +subtitle: "Fetch and filter tools, and inspect schemas"
6 hide-nav-links: false
7 ---
8
9 -To effectively use tools, it is recommended to fetch, inspect, and filter them based on your criteria.
9 +Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.
10
11 -This process returns a union of all tools that match the specified criteria, ensuring you provide the most relevant tools to the agents.
12 -
13 -When fetching tools, they are automatically formatted to match the requirements of the provider you are using. This means you do not need to manually convert or adapt the tool format.
14 -
15 -## Filtering by toolkit
16 -Toolkits are collections of tools from a specific app!
17 -
18 -Fetching tools from a toolkit is a good way to get a sense of the tools available.
19 -
20 -<Tip title="Tools are ordered by importance" icon="info">
21 -When you fetch tools from a toolkit, the most important tools are returned first.
22 -
23 -Composio determines the importance of a tool based on the usage and relevance of the tool.
24 -</Tip>
11 +## Basic usage
12
13 <CodeGroup>
27 -```python Python maxLines=60 wordWrap
28 -tools = composio.tools.get(
29 - user_id,
30 - toolkits=["GITHUB", "HACKERNEWS"],
31 -)
32 -```
33 -
34 -```typescript TypeScript maxLines=60 wordWrap
35 -const tools = await composio.tools.get(
36 - userId,
37 - {
38 - toolkits: ["GITHUB", "LINEAR"],
39 - }
40 -);
41 -```
14 +<SnippetCode
15 + src="fern/snippets/tool-calling/python/fetching-tools.py"
16 + title="Python"
17 + startLine={6}
18 + endLine={9}
19 +/>
20 +<SnippetCode
21 + src="fern/snippets/tool-calling/typescript/fetching-tools.ts"
22 + title="TypeScript"
23 + startLine={6}
24 + endLine={8}
25 +/>
26 </CodeGroup>
27
44 -**Limiting the results**
28 +Returns top 20 tools by default. Tools require a `user_id` because they're scoped to authenticated accounts. See [User management](./user-management) and [Authentication](./authenticating-tools).
29
46 -Multiple toolkits have 100s of tools. These can easily overwhelm the LLM. Hence, the SDK allows you to limit the number of tools returned.
30 +## Tool schemas
31
48 -The default `limit` is 20 -- meaning you get the top 20 important tools from the toolkit.
32 +Inspect tool parameters and types without a user_id:
33
34 <CodeGroup>
51 -```python Python maxLines=60 wordWrap
52 -tools = composio.tools.get(
53 - user_id,
54 - toolkits=["GITHUB"],
55 - limit=5, # Returns the top 5 important tools from the toolkit
56 -)
57 -```
58 -```typescript TypeScript maxLines=60 wordWrap
59 -const tools = await composio.tools.get(userId, {
60 - toolkits: ["GITHUB"],
61 - limit: 5, // Returns the top 5 important tools from the toolkit
62 -});
63 -```
35 +<SnippetCode
36 + src="fern/snippets/tool-calling/python/fetching-tools.py"
37 + title="Python"
38 + startLine={66}
39 + endLine={66}
40 +/>
41 +<SnippetCode
42 + src="fern/snippets/tool-calling/typescript/fetching-tools.ts"
43 + title="TypeScript"
44 + startLine={60}
45 + endLine={60}
46 +/>
47 </CodeGroup>
48
66 -**Filtering by scopes**
49 +Generate type-safe code for direct SDK execution with [`composio generate`](/docs/cli#generate-type-definitions). This creates TypeScript or Python types from tool schemas.
50
68 -When working with OAuth-based toolkits, you can filter tools based on their required scopes. This is useful when you want to:
69 -- Get tools that match specific permission levels
70 -- Ensure tools align with available user permissions
71 -- Filter tools based on their required OAuth scopes
72 -
73 -<Tip title="Single Toolkit Requirement" icon="warning">
74 -Scope filtering can only be used with a single toolkit at a time.
51 +<Tip>
52 +View tool parameters and schemas visually in the [Composio platform](https://platform.composio.dev). Navigate to any toolkit and select a tool to see its input/output parameters.
53 </Tip>
54
77 -<CodeGroup>
78 -```python Python maxLines=60 wordWrap
79 -# Get GitHub tools that require specific scopes
80 -tools = composio.tools.get(
81 - user_id,
82 - toolkits=["GITHUB"],
83 - scopes=["repo"], # Only get tools requiring these scopes
84 - limit=10
85 -)
86 -```
87 -```typescript TypeScript maxLines=60 wordWrap
88 -// Get GitHub tools that require specific scopes
89 -const tools = await composio.tools.get(userId, {
90 - toolkits: ["GITHUB"],
91 - scopes: ["repo"], // Only get tools requiring these scopes
92 - limit: 10
93 -});
94 -```
95 -</CodeGroup>
96 -
97 -## Tool versions
55 +## Filtering tools
56
99 -You can configure toolkit versions at SDK initialization to ensure consistent tool behavior across environments. When fetching tools, you can also [inspect which version each tool is using](/docs/toolkit-versioning#inspect-current-versions).
57 +### By toolkit
58
101 -## Filtering by tool
102 -You may specify the list of tools to fetch by directly providing the tool names. Browse the list of tools [here](/tools) to view and inspect the tools for each toolkit.
59 +Get tools from specific apps. Returns top 20 tools by default.
60
61 <CodeGroup>
105 -
106 -```python Python maxLines=60 wordWrap
107 -tools = composio.tools.get(
108 - user_id,
109 - tools=[
110 - "GITHUB_CREATE_AN_ISSUE",
111 - "GITHUB_CREATE_AN_ISSUE_COMMENT",
112 - "GITHUB_CREATE_A_COMMIT",
113 - ],
114 -)
115 -```
116 -
117 -```typescript TypeScript maxLines=60 wordWrap
118 -const tools = await composio.tools.get(userId, {
119 - tools: [
120 - "GITHUB_CREATE_AN_ISSUE",
121 - "GITHUB_CREATE_AN_ISSUE_COMMENT",
122 - "GITHUB_CREATE_A_COMMIT",
123 - ],
124 -});
125 -```
62 +<SnippetCode
63 + src="fern/snippets/tool-calling/python/fetching-tools.py"
64 + title="Python"
65 + startLine={12}
66 + endLine={23}
67 +/>
68 +<SnippetCode
69 + src="fern/snippets/tool-calling/typescript/fetching-tools.ts"
70 + title="TypeScript"
71 + startLine={11}
72 + endLine={21}
73 +/>
74 </CodeGroup>
75
128 -## Fetching raw tools
129 -To examine the raw schema definition of a tool to understand the input/output parameters or to build custom logic around tool definitions, you can use the following methods. This can be useful for:
130 -- Understanding exact input parameters and output structures.
131 -- Building custom logic around tool definitions.
132 -- Debugging tool interactions.
133 -- Research and experimentation.
76 +
77 +### By name
78 +
79 +Fetch specific tools when you know their names.
80
81 <CodeGroup>
82 <SnippetCode
137 - src="fern/snippets/tool-calling/python/raw_tools.py"
138 - startLine={5}
139 - endLine={7}
83 + src="fern/snippets/tool-calling/python/fetching-tools.py"
84 title="Python"
85 + startLine={25}
86 + endLine={34}
87 />
88 <SnippetCode
143 - src="fern/snippets/tool-calling/typescript/raw_tools.ts"
144 - startLine={5}
145 - endLine={7}
89 + src="fern/snippets/tool-calling/typescript/fetching-tools.ts"
90 title="TypeScript"
91 + startLine={23}
92 + endLine={31}
93 />
94 </CodeGroup>
95
96
151 -## Filtering by search (Experimental)
152 -You may also filter tools by searching for them. This is a good way to find tools that are relevant to a given use case.
97 +### By scopes
98
154 -This step runs a semantic search on the tool names and descriptions and returns the most relevant tools.
99 +Filter OAuth tools by permission level. Only works with a single toolkit.
100
101 <CodeGroup>
157 -```python Python maxLines=60 wordWrap
158 -tools = composio.tools.get(
159 - user_id,
160 - search="hubspot organize contacts",
161 -)
162 -
163 -# Search within a specific toolkit
164 -tools = composio.tools.get(
165 - user_id,
166 - search="repository issues",
167 - toolkits=["GITHUB"], # Optional: limit search to specific toolkit
168 - limit=5 # Optional: limit number of results
169 -)
170 -```
171 -
172 -```typescript TypeScript maxLines=60 wordWrap
173 -const tools = await composio.tools.get(userId, {
174 - search: "hubspot organize contacts",
175 -});
176 -
177 -// Search within a specific toolkit
178 -const tools = await composio.tools.get(userId, {
179 - search: "repository issues",
180 - toolkits: ["GITHUB"], // Optional: limit search to specific toolkit
181 - limit: 5 // Optional: limit number of results
182 -});
183 -```
102 +<SnippetCode
103 + src="fern/snippets/tool-calling/python/fetching-tools.py"
104 + title="Python"
105 + startLine={36}
106 + endLine={41}
107 +/>
108 +<SnippetCode
109 + src="fern/snippets/tool-calling/typescript/fetching-tools.ts"
110 + title="TypeScript"
111 + startLine={33}
112 + endLine={37}
113 +/>
114 </CodeGroup>
115
186 -## Filter Combinations
187 -
188 -When fetching tools, you must use one of these filter combinations:
189 -
190 -1. **Tools Only**: Fetch specific tools by their slugs
191 - ```typescript
192 - { tools: ["TOOL_1", "TOOL_2"] }
193 - ```
116 +### By search (experimental)
117
195 -2. **Toolkits Only**: Fetch tools from specific toolkits
196 - ```typescript
197 - { toolkits: ["TOOLKIT_1", "TOOLKIT_2"], limit?: number }
198 - ```
118 +Find tools semantically.
119
200 -3. **Single Toolkit with Scopes**: Fetch tools requiring specific OAuth scopes
201 - ```typescript
202 - { toolkits: ["GITHUB"], scopes: ["read:repo"], limit?: number }
203 - ```
204 -
205 -4. **Search**: Search across all tools or within specific toolkits
206 - ```typescript
207 - { search: "query", toolkits?: string[], limit?: number }
208 - ```
120 +<CodeGroup>
121 +<SnippetCode
122 + src="fern/snippets/tool-calling/python/fetching-tools.py"
123 + title="Python"
124 + startLine={43}
125 + endLine={65}
126 +/>
127 +<SnippetCode
128 + src="fern/snippets/tool-calling/typescript/fetching-tools.ts"
129 + title="TypeScript"
130 + startLine={39}
131 + endLine={59}
132 +/>
133 +</CodeGroup>
134
210 -These combinations are mutually exclusive - you can't mix `tools` with `search` or use `scopes` with multiple toolkits.
\ No newline at end of file
135 +<Tip>
136 +Use specific toolkit versions in production to prevent breaking changes. See [toolkit versioning](./toolkit-versioning).
137 +</Tip>
\ No newline at end of file
fern/snippets/tool-calling/python/fetching-tools.py new
+66
@@ -0,0 +1,66 @@
1 +from composio import Composio
2 +
3 +composio = Composio()
4 +user_id = "uuid-1234-5678-9012"
5 +
6 +tools = composio.tools.get(
7 + user_id,
8 + toolkits=["GITHUB"]
9 +)
10 +
11 +# Fetch with limit for a specific user
12 +tools = composio.tools.get(
13 + user_id,
14 + toolkits=["GITHUB"],
15 + limit=5 # Get top 5 tools
16 +)
17 +
18 +# Same filter but without user_id (for schemas)
19 +raw_tools = composio.tools.get_raw_composio_tools(
20 + toolkits=["GITHUB"],
21 + limit=5
22 +)
23 +
24 +# Fetch specific tools by name
25 +tools = composio.tools.get(
26 + user_id,
27 + tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
28 +)
29 +
30 +# Get schemas without user_id
31 +raw_tools = composio.tools.get_raw_composio_tools(
32 + tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
33 +)
34 +
35 +# Filter by OAuth scopes (single toolkit only)
36 +tools = composio.tools.get(
37 + user_id,
38 + toolkits=["GITHUB"],
39 + scopes=["write:org"]
40 +)
41 +
42 +# Search tools semantically
43 +tools = composio.tools.get(
44 + user_id,
45 + search="create calendar event"
46 +)
47 +
48 +# Search schemas without user_id
49 +raw_tools = composio.tools.get_raw_composio_tools(
50 + search="create calendar event"
51 +)
52 +
53 +# Search within a specific toolkit
54 +tools = composio.tools.get(
55 + user_id,
56 + search="issues",
57 + toolkits=["GITHUB"],
58 +)
59 +
60 +# Search toolkit schemas without user_id
61 +raw_tools = composio.tools.get_raw_composio_tools(
62 + search="issues",
63 + toolkits=["GITHUB"]
64 +)
65 +
66 +tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
\ No newline at end of file
fern/snippets/tool-calling/typescript/fetching-tools.ts new
+60
@@ -0,0 +1,60 @@
1 +import { Composio } from '@composio/core';
2 +
3 +const composio = new Composio();
4 +const userId = "uuid-1234-5678-9012";
5 +
6 +const tools = await composio.tools.get(userId, {
7 + toolkits: ["GITHUB"]
8 +});
9 +
10 +// Fetch with limit for a specific user
11 +const limitedTools = await composio.tools.get(userId, {
12 + toolkits: ["GITHUB"],
13 + limit: 5 // Get top 5 tools
14 +});
15 +
16 +// Same filter but without userId (for schemas)
17 +const rawTools = await composio.tools.getRawComposioTools({
18 + toolkits: ["GITHUB"],
19 + limit: 5
20 +});
21 +
22 +// Fetch specific tools by name
23 +const specificTools = await composio.tools.get(userId, {
24 + tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]
25 +});
26 +
27 +// Get schemas without userId
28 +const specificRawTools = await composio.tools.getRawComposioTools({
29 + tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]
30 +});
31 +
32 +// Filter by OAuth scopes (single toolkit only)
33 +const scopedTools = await composio.tools.get(userId, {
34 + toolkits: ["GITHUB"],
35 + scopes: ["write:org"]
36 +});
37 +
38 +// Search tools semantically
39 +const searchResults = await composio.tools.get(userId, {
40 + search: "create google calendar event"
41 +});
42 +
43 +// Search schemas without userId
44 +const searchRawTools = await composio.tools.getRawComposioTools({
45 + search: "create google calendar event"
46 +});
47 +
48 +// Search within a specific toolkit
49 +const toolkitSearch = await composio.tools.get(userId, {
50 + search: "star a repository",
51 + toolkits: ["GITHUB"]
52 +});
53 +
54 +// Search toolkit schemas without userId
55 +const toolkitSearchRaw = await composio.tools.getRawComposioTools({
56 + search: "star a repository",
57 + toolkits: ["GITHUB"]
58 +});
59 +
60 +const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");
\ No newline at end of file