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, 14:30 UTC
feat(ts/core): default to important tools
jkomyno committed
Jan 20, 2026 at 21:39 UTC
6c586f93d23f4bd5af7c28289eb6b3bb633f18b0
4 files changed
+85
-5
ts/docs/api/tools.md
+19
-5
@@ -312,7 +312,7 @@ console.log({
312
```typescript
313
// You must provide one of the following parameter combinations:
314
// 1. tools array only
315
-// 2. toolkits with optional important flag
315
+// 2. toolkits (optionally filter to important tools)
316
// 3. toolkits with search functionality
317
318
type ToolsOnlyParams = {
@@ -327,8 +327,20 @@ type ToolkitsOnlyParams = {
327
tools?: never; // Cannot be used with toolkits
328
toolkits: string[]; // List of toolkit slugs to filter by
329
limit?: number; // Limit the number of results
330
- search?: never; // Cannot be used with important flag
331
- scopes?: string[]; // Optional list of required OAuth scopes
330
+ search?: string; // Optional search term
331
+ tags?: string[]; // Optional tags filter
332
+ important?: boolean; // Filter to only important/featured tools
333
+ scopes?: never;
334
+};
335
+
336
+type ToolkitScopeOnlyParams = {
337
+ tools?: never;
338
+ toolkits: [string];
339
+ scopes: string[];
340
+ limit?: number;
341
+ search?: string;
342
+ tags?: string[];
343
+ important?: boolean; // Filter to only important/featured tools
344
};
345
346
type ToolkitSearchOnlyParams = {
@@ -336,12 +348,14 @@ type ToolkitSearchOnlyParams = {
348
toolkits?: string[]; // Optional list of toolkit slugs to filter by
349
limit?: number; // Limit the number of results
350
search: string; // Search term
339
- scopes?: string[]; // Optional list of required OAuth scopes
351
+ scopes?: never;
352
};
353
342
-type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | ToolkitSearchOnlyParams;
354
+type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | ToolkitScopeOnlyParams | ToolkitSearchOnlyParams;
355
```
356
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.
358
+
359
Note: The parameters are organized into three mutually exclusive combinations:
360
361
1. Using `tools` array to fetch specific tools by their slugs
ts/packages/core/src/models/Tools.ts
+11
@@ -323,6 +323,16 @@ export class Tools<
323
});
324
}
325
326
+ const shouldAutoApplyImportant =
327
+ 'toolkits' in queryParams.data &&
328
+ !('tools' in queryParams.data) &&
329
+ !('tags' in queryParams.data) &&
330
+ !('search' in queryParams.data) &&
331
+ queryParams.data.important !== false;
332
+
333
+ const effectiveImportant =
334
+ 'important' in queryParams.data ? queryParams.data.important : shouldAutoApplyImportant;
335
+
336
// check if the query params contains atleast one of the following: tools, toolkits, search, authConfigIds
337
if (
338
!(
@@ -355,6 +365,7 @@ export class Tools<
365
...('authConfigIds' in queryParams.data
366
? { auth_config_ids: queryParams.data.authConfigIds }
367
: {}),
368
+ ...(effectiveImportant ? { important: 'true' } : {}),
369
...{ toolkit_versions: this.toolkitVersions },
370
};
371
ts/packages/core/src/types/tool.types.ts
+3
@@ -185,6 +185,7 @@ export const ToolListParamsSchema = z.object({
185
limit: z.number().optional(),
186
search: z.string().optional(),
187
authConfigIds: z.array(z.string()).optional(),
188
+ important: z.boolean().optional(),
189
});
190
191
type BaseParams = {
@@ -207,6 +208,7 @@ type ToolkitsOnlyParams = {
208
toolkits: string[];
209
tools?: never;
210
scopes?: never;
211
+ important?: boolean;
212
} & Pick<BaseParams, 'limit' | 'search' | 'tags'>;
213
214
// toolkit + scopes (single toolkit only)
@@ -214,6 +216,7 @@ type ToolkitScopeOnlyParams = {
216
toolkits: [string];
217
tools?: never;
218
scopes: string[];
219
+ important?: boolean;
220
} & Pick<BaseParams, 'limit' | 'search' | 'tags'>;
221
222
// tags only
ts/packages/core/test/tools/tools.test.ts
+52
@@ -86,6 +86,29 @@ describe('Tools', () => {
86
87
await context.tools.getRawComposioTools(query);
88
89
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
90
+ toolkit_slug: 'github',
91
+ important: 'true',
92
+ limit: 10,
93
+ toolkit_versions: 'latest',
94
+ });
95
+ });
96
+
97
+ it('should respect explicit important=false to opt-out', async () => {
98
+ const userId = 'test-user';
99
+ const query = {
100
+ toolkits: ['github'],
101
+ important: false,
102
+ limit: 10,
103
+ };
104
+
105
+ mockClient.tools.list.mockResolvedValueOnce({
106
+ items: [toolMocks.rawTool],
107
+ totalPages: 1,
108
+ });
109
+
110
+ await context.tools.getRawComposioTools(query);
111
+
112
expect(mockClient.tools.list).toHaveBeenCalledWith({
113
toolkit_slug: 'github',
114
limit: 10,
@@ -133,6 +156,7 @@ describe('Tools', () => {
156
157
expect(mockClient.tools.list).toHaveBeenCalledWith({
158
toolkit_slug: 'todoist',
159
+ important: 'true',
160
limit: 10,
161
scopes: ['task:add', 'task:read'],
162
toolkit_versions: 'latest',
@@ -164,6 +188,29 @@ describe('Tools', () => {
188
});
189
});
190
191
+ it('should respect explicit important=true', async () => {
192
+ const userId = 'test-user';
193
+ const query: ToolListParams = {
194
+ toolkits: ['github'],
195
+ important: true,
196
+ limit: 10,
197
+ };
198
+
199
+ mockClient.tools.list.mockResolvedValueOnce({
200
+ items: [toolMocks.rawTool],
201
+ totalPages: 1,
202
+ });
203
+
204
+ await context.tools.getRawComposioTools(query);
205
+
206
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
207
+ toolkit_slug: 'github',
208
+ important: 'true',
209
+ limit: 10,
210
+ toolkit_versions: 'latest',
211
+ });
212
+ });
213
+
214
it('should throw a validation error when scopes are provided without toolkits', async () => {
215
const userId = 'test-user';
216
const invalidQuery = {
@@ -1079,6 +1126,7 @@ describe('Tools', () => {
1126
1127
expect(mockClient.tools.list).toHaveBeenCalledWith({
1128
toolkit_slug: 'github',
1129
+ important: 'true',
1130
toolkit_versions: '20251201_03',
1131
});
1132
});
@@ -1103,6 +1151,7 @@ describe('Tools', () => {
1151
1152
expect(mockClient.tools.list).toHaveBeenCalledWith({
1153
toolkit_slug: 'github',
1154
+ important: 'true',
1155
toolkit_versions: {
1156
github: '20251201_01',
1157
slack: 'latest',
@@ -1453,6 +1502,7 @@ describe('Tools', () => {
1502
1503
expect(mockClient.tools.list).toHaveBeenCalledWith({
1504
toolkit_slug: 'github',
1505
+ important: 'true',
1506
toolkit_versions: {
1507
github: '20251201_08',
1508
slack: 'latest',
@@ -1483,6 +1533,7 @@ describe('Tools', () => {
1533
1534
expect(mockClient.tools.list).toHaveBeenCalledWith({
1535
toolkit_slug: 'github',
1536
+ important: 'true',
1537
toolkit_versions: {
1538
github: '20251201_04', // user config wins
1539
gmail: '20251201_05', // from user config
@@ -1510,6 +1561,7 @@ describe('Tools', () => {
1561
1562
expect(mockClient.tools.list).toHaveBeenCalledWith({
1563
toolkit_slug: 'github',
1564
+ important: 'true',
1565
toolkit_versions: '20251201_09', // global version ignores env vars
1566
});
1567
});