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',