Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdnew file mode 100644index 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 setdiff --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.mdxnew file mode 100644index 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.mdindex 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 modificationsconst 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 transformationconst customizedTools = await composio.tools.getRawComposioTools({toolkits: ['github'],@@ -326,10 +329,10 @@ type ToolsOnlyParams = {type ToolkitsOnlyParams = {tools?: never; // Cannot be used with toolkitstoolkits: 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.tsindex 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.tsindex 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',