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.

feat(ts/core): default to important tools

jkomyno6c586f93d23f
diff --git a/ts/docs/api/tools.md b/ts/docs/api/tools.md
index 8b8de1e37..f71e7faa8 100644
--- a/ts/docs/api/tools.md
+++ b/ts/docs/api/tools.md
@@ -312,7 +312,7 @@ console.log({
```typescript
// You must provide one of the following parameter combinations:
// 1. tools array only
-// 2. toolkits with optional important flag
+// 2. toolkits (optionally filter to important tools)
// 3. toolkits with search functionality
type ToolsOnlyParams = {
@@ -327,8 +327,20 @@ 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?: never; // Cannot be used with important flag
- scopes?: string[]; // Optional list of required OAuth scopes
+ search?: string; // Optional search term
+ tags?: string[]; // Optional tags filter
+ important?: boolean; // Filter to only important/featured tools
+ scopes?: never;
+};
+
+type ToolkitScopeOnlyParams = {
+ tools?: never;
+ toolkits: [string];
+ scopes: string[];
+ limit?: number;
+ search?: string;
+ tags?: string[];
+ important?: boolean; // Filter to only important/featured tools
};
type ToolkitSearchOnlyParams = {
@@ -336,12 +348,14 @@ type ToolkitSearchOnlyParams = {
toolkits?: string[]; // Optional list of toolkit slugs to filter by
limit?: number; // Limit the number of results
search: string; // Search term
- scopes?: string[]; // Optional list of required OAuth scopes
+ scopes?: never;
};
-type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | 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.
+
Note: The parameters are organized into three mutually exclusive combinations:
1. Using `tools` array to fetch specific tools by their slugs
diff --git a/ts/packages/core/src/models/Tools.ts b/ts/packages/core/src/models/Tools.ts
index d4d28505c..8ca209ad7 100644
--- a/ts/packages/core/src/models/Tools.ts
+++ b/ts/packages/core/src/models/Tools.ts
@@ -323,6 +323,16 @@ export class Tools<
});
}
+ const shouldAutoApplyImportant =
+ 'toolkits' in queryParams.data &&
+ !('tools' in queryParams.data) &&
+ !('tags' in queryParams.data) &&
+ !('search' in queryParams.data) &&
+ queryParams.data.important !== false;
+
+ const effectiveImportant =
+ 'important' in queryParams.data ? queryParams.data.important : shouldAutoApplyImportant;
+
// check if the query params contains atleast one of the following: tools, toolkits, search, authConfigIds
if (
!(
@@ -355,6 +365,7 @@ export class Tools<
...('authConfigIds' in queryParams.data
? { auth_config_ids: queryParams.data.authConfigIds }
: {}),
+ ...(effectiveImportant ? { important: 'true' } : {}),
...{ toolkit_versions: this.toolkitVersions },
};
diff --git a/ts/packages/core/src/types/tool.types.ts b/ts/packages/core/src/types/tool.types.ts
index 6b74a73f1..e245aedf0 100644
--- a/ts/packages/core/src/types/tool.types.ts
+++ b/ts/packages/core/src/types/tool.types.ts
@@ -185,6 +185,7 @@ export const ToolListParamsSchema = z.object({
limit: z.number().optional(),
search: z.string().optional(),
authConfigIds: z.array(z.string()).optional(),
+ important: z.boolean().optional(),
});
type BaseParams = {
@@ -207,6 +208,7 @@ type ToolkitsOnlyParams = {
toolkits: string[];
tools?: never;
scopes?: never;
+ important?: boolean;
} & Pick<BaseParams, 'limit' | 'search' | 'tags'>;
// toolkit + scopes (single toolkit only)
@@ -214,6 +216,7 @@ type ToolkitScopeOnlyParams = {
toolkits: [string];
tools?: never;
scopes: string[];
+ important?: boolean;
} & Pick<BaseParams, 'limit' | 'search' | 'tags'>;
// tags only
diff --git a/ts/packages/core/test/tools/tools.test.ts b/ts/packages/core/test/tools/tools.test.ts
index 8184b0a46..9c2844ad6 100644
--- a/ts/packages/core/test/tools/tools.test.ts
+++ b/ts/packages/core/test/tools/tools.test.ts
@@ -86,6 +86,29 @@ describe('Tools', () => {
await context.tools.getRawComposioTools(query);
+ 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,
+ 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,
@@ -133,6 +156,7 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
toolkit_slug: 'todoist',
+ important: 'true',
limit: 10,
scopes: ['task:add', 'task:read'],
toolkit_versions: 'latest',
@@ -164,6 +188,29 @@ describe('Tools', () => {
});
});
+ it('should respect explicit important=true', async () => {
+ const userId = 'test-user';
+ const query: ToolListParams = {
+ toolkits: ['github'],
+ important: true,
+ limit: 10,
+ };
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await context.tools.getRawComposioTools(query);
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ toolkit_slug: 'github',
+ important: 'true',
+ limit: 10,
+ toolkit_versions: 'latest',
+ });
+ });
+
it('should throw a validation error when scopes are provided without toolkits', async () => {
const userId = 'test-user';
const invalidQuery = {
@@ -1079,6 +1126,7 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
toolkit_slug: 'github',
+ important: 'true',
toolkit_versions: '20251201_03',
});
});
@@ -1103,6 +1151,7 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
toolkit_slug: 'github',
+ important: 'true',
toolkit_versions: {
github: '20251201_01',
slack: 'latest',
@@ -1453,6 +1502,7 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
toolkit_slug: 'github',
+ important: 'true',
toolkit_versions: {
github: '20251201_08',
slack: 'latest',
@@ -1483,6 +1533,7 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
toolkit_slug: 'github',
+ important: 'true',
toolkit_versions: {
github: '20251201_04', // user config wins
gmail: '20251201_05', // from user config
@@ -1510,6 +1561,7 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
toolkit_slug: 'github',
+ important: 'true',
toolkit_versions: '20251201_09', // global version ignores env vars
});
});