Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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

Musthaq Ahamad087385d8a26b
diff --git a/.changeset/slimy-snakes-behave.md b/.changeset/slimy-snakes-behave.md
new file mode 100644
index 000000000..d7ede24f5
--- /dev/null
+++ b/.changeset/slimy-snakes-behave.md
@@ -0,0 +1,5 @@
+---
+'@composio/core': patch
+---
+
+Remove important tag auto apply when limit is set
diff --git a/docs/content/changelog/02-04-26-limit-prevents-important-auto-apply.mdx b/docs/content/changelog/02-04-26-limit-prevents-important-auto-apply.mdx
new file mode 100644
index 000000000..0fc57b240
--- /dev/null
+++ b/docs/content/changelog/02-04-26-limit-prevents-important-auto-apply.mdx
@@ -0,0 +1,150 @@
+---
+title: 'Limit Parameter Now Prevents Important Flag Auto-Apply'
+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'
+date: '2026-02-04'
+---
+
+## Version Information
+
+### TypeScript/JavaScript
+
+- Package: `@composio/core` and all provider packages
+- Version: `0.6.3`+
+- PR: [#2570](https://github.com/ComposioHQ/composio/pull/2570)
+
+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.
+
+## What Changed
+
+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.
+
+**Before:**
+
+```typescript
+// @noErrors
+// Could return < 50 tools if only 10 important tools exist
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ limit: 50,
+});
+// Result: Only 10 tools (important ones only)
+```
+
+**After:**
+
+```typescript
+// @noErrors
+// Returns exactly 50 tools (or all available if < 50)
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ limit: 50,
+});
+// Result: 50 tools (including non-important)
+```
+
+## Auto-Apply Logic
+
+The `important` flag is now auto-applied **only when ALL** of these conditions are met:
+
+- `toolkits` is provided
+- `tools` is NOT provided
+- `tags` is NOT provided
+- `search` is NOT provided
+- **`limit` is NOT provided** ← NEW
+- `important` is NOT explicitly set to `false`
+
+## Examples
+
+### Auto-Applies Important (No Limit)
+
+```typescript
+// @noErrors
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+});
+// Returns: ~10-20 important tools
+```
+
+### Does NOT Auto-Apply (Limit Provided)
+
+```typescript
+// @noErrors
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ limit: 50,
+});
+// Returns: Exactly 50 tools (or all available)
+```
+
+### Explicit Important Overrides
+
+```typescript
+// @noErrors
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ limit: 50,
+ important: true,
+});
+// Returns: Up to 50 important tools
+```
+
+### Prevents Auto-Apply (Tags Provided)
+
+```typescript
+// @noErrors
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ tags: ['important'],
+});
+// Returns: GitHub tools with 'important' tag (no auto-apply)
+```
+
+### Prevents Auto-Apply (Search Provided)
+
+```typescript
+// @noErrors
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ search: 'repository',
+});
+// Returns: GitHub tools matching search (no auto-apply)
+```
+
+## Why This Matters
+
+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.
+
+**Use cases:**
+
+1. **Pagination**: Get exactly N tools per page
+2. **Performance**: Limit tool count for faster responses
+3. **UI constraints**: Display a specific number of tools in your interface
+
+## Backward Compatibility
+
+This change is **backward compatible** with one caveat:
+
+- **No code changes needed** for most users
+- If you were relying on automatic `important` filtering with `limit`, you now need to explicitly pass `important: true`
+
+**Migration (if needed):**
+
+```typescript
+// @noErrors
+// Before (relied on auto-apply even with limit)
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ limit: 20,
+});
+
+// After (explicit important flag)
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ limit: 20,
+ important: true, // Explicitly set if you want important tools
+});
+```
+
+## Documentation
+
+Full documentation with more examples is available in the [Tools API Reference](/reference/sdk-reference/typescript/tools).
diff --git a/ts/docs/api/tools.md b/ts/docs/api/tools.md
index f71e7faa8..6f12ca72f 100644
--- a/ts/docs/api/tools.md
+++ b/ts/docs/api/tools.md
@@ -11,21 +11,25 @@ Retrieves and wraps tools based on the provided filters. Tool versions are contr
#### Overload 1: Get multiple tools with filters
```typescript
-// Get tools from a specific toolkit
+// Get important tools from a toolkit (auto-applies important filter)
+const importantGithubTools = await composio.tools.get('default', {
+ toolkits: ['github']
+});
+
+// Get a limited number of tools (does NOT auto-apply important filter)
const githubTools = await composio.tools.get('default', {
toolkits: ['github'],
limit: 10
});
-// Get tools with search
+// Get tools with search (does NOT auto-apply important filter)
const searchTools = await composio.tools.get('default', {
search: 'user'
});
// Get tools with schema modifications
const customizedTools = await composio.tools.get('default', {
- toolkits: ['github'],
- limit: 5
+ toolkits: ['github']
}, {
modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
return { ...schema, description: 'Custom description' };
@@ -216,8 +220,13 @@ const customTool = await composio.tools.createCustomTool({
Lists all tools available in the Composio SDK including custom tools. This method provides direct access to tool data without provider-specific wrapping.
```typescript
-// Get tools from specific toolkits
-const githubTools = await composio.tools.getRawComposioTools({
+// Get important tools from a toolkit (auto-applies important filter)
+const importantGithubTools = await composio.tools.getRawComposioTools({
+ toolkits: ['github']
+});
+
+// Get a limited number of tools (does NOT auto-apply important)
+const limitedTools = await composio.tools.getRawComposioTools({
toolkits: ['github'],
limit: 10
});
@@ -227,12 +236,6 @@ const specificTools = await composio.tools.getRawComposioTools({
tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
});
-// Get tools from specific toolkits
-const githubTools = await composio.tools.getRawComposioTools({
- toolkits: ['github'],
- limit: 10
-});
-
// Get tools with schema transformation
const customizedTools = await composio.tools.getRawComposioTools({
toolkits: ['github'],
@@ -326,10 +329,10 @@ type ToolsOnlyParams = {
type ToolkitsOnlyParams = {
tools?: never; // Cannot be used with toolkits
toolkits: string[]; // List of toolkit slugs to filter by
- limit?: number; // Limit the number of results
- search?: string; // Optional search term
- tags?: string[]; // Optional tags filter
- important?: boolean; // Filter to only important/featured tools
+ limit?: number; // Limit the number of results (prevents auto-applying important)
+ search?: string; // Optional search term (prevents auto-applying important)
+ tags?: string[]; // Optional tags filter (prevents auto-applying important)
+ important?: boolean; // Filter to only important/featured tools (auto-applied when no limit/tags/search)
scopes?: never;
};
@@ -337,10 +340,10 @@ type ToolkitScopeOnlyParams = {
tools?: never;
toolkits: [string];
scopes: string[];
- limit?: number;
- search?: string;
- tags?: string[];
- important?: boolean; // Filter to only important/featured tools
+ limit?: number; // Prevents auto-applying important
+ search?: string; // Prevents auto-applying important
+ tags?: string[]; // Prevents auto-applying important
+ important?: boolean; // Filter to only important/featured tools (auto-applied when no limit/tags/search)
};
type ToolkitSearchOnlyParams = {
@@ -354,7 +357,67 @@ type ToolkitSearchOnlyParams = {
type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | ToolkitScopeOnlyParams | ToolkitSearchOnlyParams;
```
-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.
+#### Auto-applying the `important` Filter
+
+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.
+
+**Auto-apply conditions:**
+- ✅ `toolkits` is provided
+- ✅ `tools` is NOT provided
+- ✅ `tags` is NOT provided
+- ✅ `search` is NOT provided
+- ✅ `limit` is NOT provided
+- ✅ `important` is NOT explicitly set to `false`
+
+**Examples:**
+
+```typescript
+// Auto-applies important: true
+const tools = await composio.tools.getRawComposioTools({
+ toolkits: ['github']
+});
+// Result: Only important GitHub tools
+
+// Does NOT auto-apply important (limit provided)
+const tools = await composio.tools.getRawComposioTools({
+ toolkits: ['github'],
+ limit: 50
+});
+// Result: First 50 GitHub tools (including non-important)
+
+// Does NOT auto-apply important (tags provided)
+const tools = await composio.tools.getRawComposioTools({
+ toolkits: ['github'],
+ tags: ['important']
+});
+// Result: GitHub tools with 'important' tag
+
+// Does NOT auto-apply important (search provided)
+const tools = await composio.tools.getRawComposioTools({
+ toolkits: ['github'],
+ search: 'repository'
+});
+// Result: GitHub tools matching 'repository' search
+
+// Explicitly disable auto-apply
+const tools = await composio.tools.getRawComposioTools({
+ toolkits: ['github'],
+ important: false
+});
+// Result: All GitHub tools (including non-important)
+
+// Explicitly enable important even with limit
+const tools = await composio.tools.getRawComposioTools({
+ toolkits: ['github'],
+ limit: 20,
+ important: true
+});
+// Result: First 20 important GitHub tools
+```
+
+**Why does `limit` prevent auto-applying `important`?**
+
+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.
Note: The parameters are organized into three mutually exclusive combinations:
diff --git a/ts/packages/core/src/models/Tools.ts b/ts/packages/core/src/models/Tools.ts
index b5c2b0ecb..1b17f32b7 100644
--- a/ts/packages/core/src/models/Tools.ts
+++ b/ts/packages/core/src/models/Tools.ts
@@ -331,6 +331,8 @@ export class Tools<
!('tools' in queryParams.data) &&
!('tags' in queryParams.data) &&
!('search' in queryParams.data) &&
+ // if the user provides a limit, do not apply the important flag
+ !('limit' in queryParams.data) &&
queryParams.data.important !== false;
const effectiveImportant =
diff --git a/ts/packages/core/test/tools/tools.test.ts b/ts/packages/core/test/tools/tools.test.ts
index cc60f8d30..e634d6a69 100644
--- a/ts/packages/core/test/tools/tools.test.ts
+++ b/ts/packages/core/test/tools/tools.test.ts
@@ -37,8 +37,6 @@ describe('Tools', () => {
describe('getRawComposioTools', () => {
it('should fetch tools from the API', async () => {
- const userId = 'test-user';
-
mockClient.tools.list.mockResolvedValueOnce({
items: [toolMocks.rawTool],
totalPages: 1,
@@ -53,7 +51,6 @@ describe('Tools', () => {
});
it('should handle query parameters correctly', async () => {
- const userId = 'test-user';
const query = {
tools: ['TOOL1', 'TOOL2'],
};
@@ -73,10 +70,8 @@ describe('Tools', () => {
});
it('should handle toolkit query parameters correctly', async () => {
- const userId = 'test-user';
const query = {
toolkits: ['github'],
- limit: 10,
};
mockClient.tools.list.mockResolvedValueOnce({
@@ -89,13 +84,11 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
toolkit_slug: 'github',
important: 'true',
- limit: 10,
toolkit_versions: 'latest',
});
});
it('should respect explicit important=false to opt-out', async () => {
- const userId = 'test-user';
const query = {
toolkits: ['github'],
important: false,
@@ -117,7 +110,6 @@ describe('Tools', () => {
});
it('should handle toolkit search parameters correctly', async () => {
- const userId = 'test-user';
const query = {
toolkits: ['github'],
search: 'test',
@@ -140,11 +132,9 @@ describe('Tools', () => {
});
it('should handle toolkit scopes parameters correctly', async () => {
- const userId = 'test-user';
const query: ToolListParams = {
toolkits: ['todoist'],
scopes: ['task:add', 'task:read'],
- limit: 10,
};
mockClient.tools.list.mockResolvedValueOnce({
@@ -157,14 +147,12 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
toolkit_slug: 'todoist',
important: 'true',
- limit: 10,
scopes: ['task:add', 'task:read'],
toolkit_versions: 'latest',
});
});
it('should handle toolkit scopes with search parameters correctly', async () => {
- const userId = 'test-user';
const query: ToolListParams = {
toolkits: ['todoist'],
scopes: ['task:add'],
@@ -189,7 +177,6 @@ describe('Tools', () => {
});
it('should respect explicit important=true', async () => {
- const userId = 'test-user';
const query: ToolListParams = {
toolkits: ['github'],
important: true,
@@ -211,8 +198,72 @@ describe('Tools', () => {
});
});
+ it('should NOT auto-apply important when tags are passed with values', async () => {
+ const query: ToolListParams = {
+ toolkits: ['github'],
+ tags: ['important', 'custom'],
+ limit: 10,
+ };
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await context.tools.getRawComposioTools(query);
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ toolkit_slug: 'github',
+ tags: ['important', 'custom'],
+ limit: 10,
+ toolkit_versions: 'latest',
+ });
+ // Should NOT include important: 'true' when tags are provided
+ });
+
+ it('should NOT auto-apply important when tags are passed as empty array', async () => {
+ const query: ToolListParams = {
+ toolkits: ['github'],
+ tags: [],
+ };
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await context.tools.getRawComposioTools(query);
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ toolkit_slug: 'github',
+ tags: [],
+ toolkit_versions: 'latest',
+ });
+ // Should NOT include important: 'true' when tags array is present (even if empty)
+ });
+
+ it('should NOT auto-apply important when limit is provided', async () => {
+ const query: ToolListParams = {
+ toolkits: ['github'],
+ limit: 10,
+ };
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await context.tools.getRawComposioTools(query);
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ toolkit_slug: 'github',
+ limit: 10,
+ toolkit_versions: 'latest',
+ });
+ // Should NOT include important: 'true' when limit is provided
+ });
+
it('should throw a validation error when scopes are provided without toolkits', async () => {
- const userId = 'test-user';
const invalidQuery = {
scopes: ['task:add'],
} as any;
@@ -223,8 +274,6 @@ describe('Tools', () => {
});
it('should transform tool case correctly', async () => {
- const userId = 'test-user';
-
mockClient.tools.list.mockResolvedValueOnce({
items: [toolMocks.rawTool],
totalPages: 1,
@@ -237,8 +286,6 @@ describe('Tools', () => {
});
it('should include custom tools in the results', async () => {
- const userId = 'test-user';
-
mockClient.tools.list.mockResolvedValueOnce({
items: [toolMocks.rawTool],
totalPages: 1,
@@ -254,7 +301,6 @@ describe('Tools', () => {
});
it('should apply schema modifiers when provided', async () => {
- const userId = 'test-user';
const schemaModifier = createSchemaModifier({
description: 'Modified description',
});
@@ -274,7 +320,6 @@ describe('Tools', () => {
});
it('should throw an error if schema modifier is not a function', async () => {
- const userId = 'test-user';
const invalidModifier = 'not a function' as any;
mockClient.tools.list.mockResolvedValueOnce({
@@ -293,7 +338,6 @@ describe('Tools', () => {
});
it('should throw a validation error when both tools and toolkits are provided', async () => {
- const userId = 'test-user';
const invalidQuery = {
tools: ['TOOL1'],
toolkits: ['github'],
@@ -305,7 +349,6 @@ describe('Tools', () => {
});
it('should throw a validation error when no required parameters are provided', async () => {
- const userId = 'test-user';
const emptyQuery = {} as any;
await expect(context.tools.getRawComposioTools(emptyQuery)).rejects.toThrow(ValidationError);
@@ -314,7 +357,6 @@ describe('Tools', () => {
describe('getRawComposioToolBySlug', () => {
it('should fetch a tool by slug from the API', async () => {
- const userId = 'test-user';
const slug = 'TOOL_SLUG';
mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
@@ -326,7 +368,6 @@ describe('Tools', () => {
});
it('should check for custom tools first', async () => {
- const userId = 'test-user';
const slug = 'CUSTOM_TOOL';
const getCustomToolBySlugSpy = vi.spyOn(context.tools['customTools'], 'getCustomToolBySlug');
@@ -340,7 +381,6 @@ describe('Tools', () => {
});
it('should throw an error if tool is not found', async () => {
- const userId = 'test-user';
const slug = 'NONEXISTENT_TOOL';
const getCustomToolBySlugSpy = vi.spyOn(context.tools['customTools'], 'getCustomToolBySlug');
@@ -353,7 +393,6 @@ describe('Tools', () => {
});
it('should apply schema modifiers when provided', async () => {
- const userId = 'test-user';
const slug = 'TOOL_SLUG';
const schemaModifier = createSchemaModifier({
description: 'Modified description',