@devries-cameron20 / composio Mirror · read-only / commits / 087385d8a
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 22, 10:45 UTC

fix(core): prevent auto-applying important flag when limit is provided (#2570)

Musthaq Ahamad committed Feb 4, 2026 at 16:40 UTC 087385d8a26b747f6e64aa7f3146458fbcd34ff3
5 files changed +306 -47
.changeset/slimy-snakes-behave.md new
+5
@@ -0,0 +1,5 @@
1 +---
2 +'@composio/core': patch
3 +---
4 +
5 +Remove important tag auto apply when limit is set
docs/content/changelog/02-04-26-limit-prevents-important-auto-apply.mdx new
+150
@@ -0,0 +1,150 @@
1 +---
2 +title: 'Limit Parameter Now Prevents Important Flag Auto-Apply'
3 +description: 'When fetching tools with a limit parameter, the important flag is no longer automatically applied, ensuring users get the exact number of tools requested'
4 +date: '2026-02-04'
5 +---
6 +
7 +## Version Information
8 +
9 +### TypeScript/JavaScript
10 +
11 +- Package: `@composio/core` and all provider packages
12 +- Version: `0.6.3`+
13 +- PR: [#2570](https://github.com/ComposioHQ/composio/pull/2570)
14 +
15 +The `important` flag auto-apply logic has been updated to respect the `limit` parameter. When you provide a `limit`, the SDK no longer automatically applies `important: true`, ensuring you get the exact number of tools you requested.
16 +
17 +## What Changed
18 +
19 +Previously, when querying tools by toolkit with both `toolkits` and `limit` parameters, the SDK would auto-apply `important: true`. This could result in returning fewer tools than the requested limit if the toolkit had limited important tools.
20 +
21 +**Before:**
22 +
23 +```typescript
24 +// @noErrors
25 +// Could return < 50 tools if only 10 important tools exist
26 +const tools = await composio.tools.get('default', {
27 + toolkits: ['github'],
28 + limit: 50,
29 +});
30 +// Result: Only 10 tools (important ones only)
31 +```
32 +
33 +**After:**
34 +
35 +```typescript
36 +// @noErrors
37 +// Returns exactly 50 tools (or all available if < 50)
38 +const tools = await composio.tools.get('default', {
39 + toolkits: ['github'],
40 + limit: 50,
41 +});
42 +// Result: 50 tools (including non-important)
43 +```
44 +
45 +## Auto-Apply Logic
46 +
47 +The `important` flag is now auto-applied **only when ALL** of these conditions are met:
48 +
49 +- `toolkits` is provided
50 +- `tools` is NOT provided
51 +- `tags` is NOT provided
52 +- `search` is NOT provided
53 +- **`limit` is NOT provided** ← NEW
54 +- `important` is NOT explicitly set to `false`
55 +
56 +## Examples
57 +
58 +### Auto-Applies Important (No Limit)
59 +
60 +```typescript
61 +// @noErrors
62 +const tools = await composio.tools.get('default', {
63 + toolkits: ['github'],
64 +});
65 +// Returns: ~10-20 important tools
66 +```
67 +
68 +### Does NOT Auto-Apply (Limit Provided)
69 +
70 +```typescript
71 +// @noErrors
72 +const tools = await composio.tools.get('default', {
73 + toolkits: ['github'],
74 + limit: 50,
75 +});
76 +// Returns: Exactly 50 tools (or all available)
77 +```
78 +
79 +### Explicit Important Overrides
80 +
81 +```typescript
82 +// @noErrors
83 +const tools = await composio.tools.get('default', {
84 + toolkits: ['github'],
85 + limit: 50,
86 + important: true,
87 +});
88 +// Returns: Up to 50 important tools
89 +```
90 +
91 +### Prevents Auto-Apply (Tags Provided)
92 +
93 +```typescript
94 +// @noErrors
95 +const tools = await composio.tools.get('default', {
96 + toolkits: ['github'],
97 + tags: ['important'],
98 +});
99 +// Returns: GitHub tools with 'important' tag (no auto-apply)
100 +```
101 +
102 +### Prevents Auto-Apply (Search Provided)
103 +
104 +```typescript
105 +// @noErrors
106 +const tools = await composio.tools.get('default', {
107 + toolkits: ['github'],
108 + search: 'repository',
109 +});
110 +// Returns: GitHub tools matching search (no auto-apply)
111 +```
112 +
113 +## Why This Matters
114 +
115 +When you provide a `limit`, you're explicitly requesting a specific number of tools. Auto-applying the `important` filter could prevent you from getting the requested number of tools. This change respects user intent and makes the SDK behavior more predictable.
116 +
117 +**Use cases:**
118 +
119 +1. **Pagination**: Get exactly N tools per page
120 +2. **Performance**: Limit tool count for faster responses
121 +3. **UI constraints**: Display a specific number of tools in your interface
122 +
123 +## Backward Compatibility
124 +
125 +This change is **backward compatible** with one caveat:
126 +
127 +- **No code changes needed** for most users
128 +- If you were relying on automatic `important` filtering with `limit`, you now need to explicitly pass `important: true`
129 +
130 +**Migration (if needed):**
131 +
132 +```typescript
133 +// @noErrors
134 +// Before (relied on auto-apply even with limit)
135 +const tools = await composio.tools.get('default', {
136 + toolkits: ['github'],
137 + limit: 20,
138 +});
139 +
140 +// After (explicit important flag)
141 +const tools = await composio.tools.get('default', {
142 + toolkits: ['github'],
143 + limit: 20,
144 + important: true, // Explicitly set if you want important tools
145 +});
146 +```
147 +
148 +## Documentation
149 +
150 +Full documentation with more examples is available in the [Tools API Reference](/reference/sdk-reference/typescript/tools).
ts/docs/api/tools.md
+84 -21
@@ -11,21 +11,25 @@ Retrieves and wraps tools based on the provided filters. Tool versions are contr
11 #### Overload 1: Get multiple tools with filters
12
13 ```typescript
14 -// Get tools from a specific toolkit
14 +// Get important tools from a toolkit (auto-applies important filter)
15 +const importantGithubTools = await composio.tools.get('default', {
16 + toolkits: ['github']
17 +});
18 +
19 +// Get a limited number of tools (does NOT auto-apply important filter)
20 const githubTools = await composio.tools.get('default', {
21 toolkits: ['github'],
22 limit: 10
23 });
24
20 -// Get tools with search
25 +// Get tools with search (does NOT auto-apply important filter)
26 const searchTools = await composio.tools.get('default', {
27 search: 'user'
28 });
29
30 // Get tools with schema modifications
31 const customizedTools = await composio.tools.get('default', {
27 - toolkits: ['github'],
28 - limit: 5
32 + toolkits: ['github']
33 }, {
34 modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
35 return { ...schema, description: 'Custom description' };
@@ -216,8 +220,13 @@ const customTool = await composio.tools.createCustomTool({
220 Lists all tools available in the Composio SDK including custom tools. This method provides direct access to tool data without provider-specific wrapping.
221
222 ```typescript
219 -// Get tools from specific toolkits
220 -const githubTools = await composio.tools.getRawComposioTools({
223 +// Get important tools from a toolkit (auto-applies important filter)
224 +const importantGithubTools = await composio.tools.getRawComposioTools({
225 + toolkits: ['github']
226 +});
227 +
228 +// Get a limited number of tools (does NOT auto-apply important)
229 +const limitedTools = await composio.tools.getRawComposioTools({
230 toolkits: ['github'],
231 limit: 10
232 });
@@ -227,12 +236,6 @@ const specificTools = await composio.tools.getRawComposioTools({
236 tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
237 });
238
230 -// Get tools from specific toolkits
231 -const githubTools = await composio.tools.getRawComposioTools({
232 - toolkits: ['github'],
233 - limit: 10
234 -});
235 -
239 // Get tools with schema transformation
240 const customizedTools = await composio.tools.getRawComposioTools({
241 toolkits: ['github'],
@@ -326,10 +329,10 @@ type ToolsOnlyParams = {
329 type ToolkitsOnlyParams = {
330 tools?: never; // Cannot be used with toolkits
331 toolkits: string[]; // List of toolkit slugs to filter by
329 - limit?: number; // Limit the number of results
330 - search?: string; // Optional search term
331 - tags?: string[]; // Optional tags filter
332 - important?: boolean; // Filter to only important/featured tools
332 + limit?: number; // Limit the number of results (prevents auto-applying important)
333 + search?: string; // Optional search term (prevents auto-applying important)
334 + tags?: string[]; // Optional tags filter (prevents auto-applying important)
335 + important?: boolean; // Filter to only important/featured tools (auto-applied when no limit/tags/search)
336 scopes?: never;
337 };
338
@@ -337,10 +340,10 @@ type ToolkitScopeOnlyParams = {
340 tools?: never;
341 toolkits: [string];
342 scopes: string[];
340 - limit?: number;
341 - search?: string;
342 - tags?: string[];
343 - important?: boolean; // Filter to only important/featured tools
343 + limit?: number; // Prevents auto-applying important
344 + search?: string; // Prevents auto-applying important
345 + tags?: string[]; // Prevents auto-applying important
346 + important?: boolean; // Filter to only important/featured tools (auto-applied when no limit/tags/search)
347 };
348
349 type ToolkitSearchOnlyParams = {
@@ -354,7 +357,67 @@ type ToolkitSearchOnlyParams = {
357 type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | ToolkitScopeOnlyParams | ToolkitSearchOnlyParams;
358 ```
359
357 -Note: When querying by `toolkits` only (without `tools`, `tags`, or `search`), the SDK automatically applies `important: true` to prioritize the most useful tools. Set `important: false` explicitly to opt-out.
360 +#### Auto-applying the `important` Filter
361 +
362 +When querying by `toolkits` only (without `tools`, `tags`, `search`, or `limit`), the SDK automatically applies `important: true` to prioritize the most useful tools from that toolkit. This helps reduce the number of tools returned and focuses on the most commonly used ones.
363 +
364 +**Auto-apply conditions:**
365 +- ✅ `toolkits` is provided
366 +- ✅ `tools` is NOT provided
367 +- ✅ `tags` is NOT provided
368 +- ✅ `search` is NOT provided
369 +- ✅ `limit` is NOT provided
370 +- ✅ `important` is NOT explicitly set to `false`
371 +
372 +**Examples:**
373 +
374 +```typescript
375 +// Auto-applies important: true
376 +const tools = await composio.tools.getRawComposioTools({
377 + toolkits: ['github']
378 +});
379 +// Result: Only important GitHub tools
380 +
381 +// Does NOT auto-apply important (limit provided)
382 +const tools = await composio.tools.getRawComposioTools({
383 + toolkits: ['github'],
384 + limit: 50
385 +});
386 +// Result: First 50 GitHub tools (including non-important)
387 +
388 +// Does NOT auto-apply important (tags provided)
389 +const tools = await composio.tools.getRawComposioTools({
390 + toolkits: ['github'],
391 + tags: ['important']
392 +});
393 +// Result: GitHub tools with 'important' tag
394 +
395 +// Does NOT auto-apply important (search provided)
396 +const tools = await composio.tools.getRawComposioTools({
397 + toolkits: ['github'],
398 + search: 'repository'
399 +});
400 +// Result: GitHub tools matching 'repository' search
401 +
402 +// Explicitly disable auto-apply
403 +const tools = await composio.tools.getRawComposioTools({
404 + toolkits: ['github'],
405 + important: false
406 +});
407 +// Result: All GitHub tools (including non-important)
408 +
409 +// Explicitly enable important even with limit
410 +const tools = await composio.tools.getRawComposioTools({
411 + toolkits: ['github'],
412 + limit: 20,
413 + important: true
414 +});
415 +// Result: First 20 important GitHub tools
416 +```
417 +
418 +**Why does `limit` prevent auto-applying `important`?**
419 +
420 +When you provide a `limit`, you're indicating that you want a specific number of tools. Auto-applying the `important` filter could result in fewer tools than your limit if the toolkit has limited important tools. By not auto-applying, you get the exact number of tools you requested.
421
422 Note: The parameters are organized into three mutually exclusive combinations:
423
ts/packages/core/src/models/Tools.ts
+2
@@ -331,6 +331,8 @@ export class Tools<
331 !('tools' in queryParams.data) &&
332 !('tags' in queryParams.data) &&
333 !('search' in queryParams.data) &&
334 + // if the user provides a limit, do not apply the important flag
335 + !('limit' in queryParams.data) &&
336 queryParams.data.important !== false;
337
338 const effectiveImportant =
ts/packages/core/test/tools/tools.test.ts
+65 -26
@@ -37,8 +37,6 @@ describe('Tools', () => {
37
38 describe('getRawComposioTools', () => {
39 it('should fetch tools from the API', async () => {
40 - const userId = 'test-user';
41 -
40 mockClient.tools.list.mockResolvedValueOnce({
41 items: [toolMocks.rawTool],
42 totalPages: 1,
@@ -53,7 +51,6 @@ describe('Tools', () => {
51 });
52
53 it('should handle query parameters correctly', async () => {
56 - const userId = 'test-user';
54 const query = {
55 tools: ['TOOL1', 'TOOL2'],
56 };
@@ -73,10 +70,8 @@ describe('Tools', () => {
70 });
71
72 it('should handle toolkit query parameters correctly', async () => {
76 - const userId = 'test-user';
73 const query = {
74 toolkits: ['github'],
79 - limit: 10,
75 };
76
77 mockClient.tools.list.mockResolvedValueOnce({
@@ -89,13 +84,11 @@ describe('Tools', () => {
84 expect(mockClient.tools.list).toHaveBeenCalledWith({
85 toolkit_slug: 'github',
86 important: 'true',
92 - limit: 10,
87 toolkit_versions: 'latest',
88 });
89 });
90
91 it('should respect explicit important=false to opt-out', async () => {
98 - const userId = 'test-user';
92 const query = {
93 toolkits: ['github'],
94 important: false,
@@ -117,7 +110,6 @@ describe('Tools', () => {
110 });
111
112 it('should handle toolkit search parameters correctly', async () => {
120 - const userId = 'test-user';
113 const query = {
114 toolkits: ['github'],
115 search: 'test',
@@ -140,11 +132,9 @@ describe('Tools', () => {
132 });
133
134 it('should handle toolkit scopes parameters correctly', async () => {
143 - const userId = 'test-user';
135 const query: ToolListParams = {
136 toolkits: ['todoist'],
137 scopes: ['task:add', 'task:read'],
147 - limit: 10,
138 };
139
140 mockClient.tools.list.mockResolvedValueOnce({
@@ -157,14 +147,12 @@ describe('Tools', () => {
147 expect(mockClient.tools.list).toHaveBeenCalledWith({
148 toolkit_slug: 'todoist',
149 important: 'true',
160 - limit: 10,
150 scopes: ['task:add', 'task:read'],
151 toolkit_versions: 'latest',
152 });
153 });
154
155 it('should handle toolkit scopes with search parameters correctly', async () => {
167 - const userId = 'test-user';
156 const query: ToolListParams = {
157 toolkits: ['todoist'],
158 scopes: ['task:add'],
@@ -189,7 +177,6 @@ describe('Tools', () => {
177 });
178
179 it('should respect explicit important=true', async () => {
192 - const userId = 'test-user';
180 const query: ToolListParams = {
181 toolkits: ['github'],
182 important: true,
@@ -211,8 +198,72 @@ describe('Tools', () => {
198 });
199 });
200
201 + it('should NOT auto-apply important when tags are passed with values', async () => {
202 + const query: ToolListParams = {
203 + toolkits: ['github'],
204 + tags: ['important', 'custom'],
205 + limit: 10,
206 + };
207 +
208 + mockClient.tools.list.mockResolvedValueOnce({
209 + items: [toolMocks.rawTool],
210 + totalPages: 1,
211 + });
212 +
213 + await context.tools.getRawComposioTools(query);
214 +
215 + expect(mockClient.tools.list).toHaveBeenCalledWith({
216 + toolkit_slug: 'github',
217 + tags: ['important', 'custom'],
218 + limit: 10,
219 + toolkit_versions: 'latest',
220 + });
221 + // Should NOT include important: 'true' when tags are provided
222 + });
223 +
224 + it('should NOT auto-apply important when tags are passed as empty array', async () => {
225 + const query: ToolListParams = {
226 + toolkits: ['github'],
227 + tags: [],
228 + };
229 +
230 + mockClient.tools.list.mockResolvedValueOnce({
231 + items: [toolMocks.rawTool],
232 + totalPages: 1,
233 + });
234 +
235 + await context.tools.getRawComposioTools(query);
236 +
237 + expect(mockClient.tools.list).toHaveBeenCalledWith({
238 + toolkit_slug: 'github',
239 + tags: [],
240 + toolkit_versions: 'latest',
241 + });
242 + // Should NOT include important: 'true' when tags array is present (even if empty)
243 + });
244 +
245 + it('should NOT auto-apply important when limit is provided', async () => {
246 + const query: ToolListParams = {
247 + toolkits: ['github'],
248 + limit: 10,
249 + };
250 +
251 + mockClient.tools.list.mockResolvedValueOnce({
252 + items: [toolMocks.rawTool],
253 + totalPages: 1,
254 + });
255 +
256 + await context.tools.getRawComposioTools(query);
257 +
258 + expect(mockClient.tools.list).toHaveBeenCalledWith({
259 + toolkit_slug: 'github',
260 + limit: 10,
261 + toolkit_versions: 'latest',
262 + });
263 + // Should NOT include important: 'true' when limit is provided
264 + });
265 +
266 it('should throw a validation error when scopes are provided without toolkits', async () => {
215 - const userId = 'test-user';
267 const invalidQuery = {
268 scopes: ['task:add'],
269 } as any;
@@ -223,8 +274,6 @@ describe('Tools', () => {
274 });
275
276 it('should transform tool case correctly', async () => {
226 - const userId = 'test-user';
227 -
277 mockClient.tools.list.mockResolvedValueOnce({
278 items: [toolMocks.rawTool],
279 totalPages: 1,
@@ -237,8 +286,6 @@ describe('Tools', () => {
286 });
287
288 it('should include custom tools in the results', async () => {
240 - const userId = 'test-user';
241 -
289 mockClient.tools.list.mockResolvedValueOnce({
290 items: [toolMocks.rawTool],
291 totalPages: 1,
@@ -254,7 +301,6 @@ describe('Tools', () => {
301 });
302
303 it('should apply schema modifiers when provided', async () => {
257 - const userId = 'test-user';
304 const schemaModifier = createSchemaModifier({
305 description: 'Modified description',
306 });
@@ -274,7 +320,6 @@ describe('Tools', () => {
320 });
321
322 it('should throw an error if schema modifier is not a function', async () => {
277 - const userId = 'test-user';
323 const invalidModifier = 'not a function' as any;
324
325 mockClient.tools.list.mockResolvedValueOnce({
@@ -293,7 +338,6 @@ describe('Tools', () => {
338 });
339
340 it('should throw a validation error when both tools and toolkits are provided', async () => {
296 - const userId = 'test-user';
341 const invalidQuery = {
342 tools: ['TOOL1'],
343 toolkits: ['github'],
@@ -305,7 +349,6 @@ describe('Tools', () => {
349 });
350
351 it('should throw a validation error when no required parameters are provided', async () => {
308 - const userId = 'test-user';
352 const emptyQuery = {} as any;
353
354 await expect(context.tools.getRawComposioTools(emptyQuery)).rejects.toThrow(ValidationError);
@@ -314,7 +357,6 @@ describe('Tools', () => {
357
358 describe('getRawComposioToolBySlug', () => {
359 it('should fetch a tool by slug from the API', async () => {
317 - const userId = 'test-user';
360 const slug = 'TOOL_SLUG';
361
362 mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
@@ -326,7 +368,6 @@ describe('Tools', () => {
368 });
369
370 it('should check for custom tools first', async () => {
329 - const userId = 'test-user';
371 const slug = 'CUSTOM_TOOL';
372
373 const getCustomToolBySlugSpy = vi.spyOn(context.tools['customTools'], 'getCustomToolBySlug');
@@ -340,7 +381,6 @@ describe('Tools', () => {
381 });
382
383 it('should throw an error if tool is not found', async () => {
343 - const userId = 'test-user';
384 const slug = 'NONEXISTENT_TOOL';
385
386 const getCustomToolBySlugSpy = vi.spyOn(context.tools['customTools'], 'getCustomToolBySlug');
@@ -353,7 +393,6 @@ describe('Tools', () => {
393 });
394
395 it('should apply schema modifiers when provided', async () => {
356 - const userId = 'test-user';
396 const slug = 'TOOL_SLUG';
397 const schemaModifier = createSchemaModifier({
398 description: 'Modified description',