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 tool fetching issues when executing tools with specific version (#2518)
Musthaq Ahamad committed
Jan 29, 2026 at 12:16 UTC
e9e8db0147c3faeef767b0ac256f52d47931862c
3 files changed
+211
-5
ts/packages/core/src/models/Tools.ts
+13
-5
@@ -14,6 +14,7 @@ import {
14
ToolExecuteParamsSchema,
15
ToolkitVersionParam,
16
SchemaModifierOptions,
17
+ ToolRetrievalOptions,
18
ToolExecuteMetaParamsSchema,
19
} from '../types/tool.types';
20
import {
@@ -501,7 +502,7 @@ export class Tools<
502
* });
503
* ```
504
*/
504
- async getRawComposioToolBySlug(slug: string, options?: SchemaModifierOptions): Promise<Tool> {
505
+ async getRawComposioToolBySlug(slug: string, options?: ToolRetrievalOptions): Promise<Tool> {
506
// check if the tool is a custom tool
507
const customTool = await this.customTools.getCustomToolBySlug(slug);
508
if (customTool) {
@@ -513,9 +514,12 @@ export class Tools<
514
// if not, fetch the tool from the Composio API
515
let tool: ToolRetrieveResponse;
516
try {
516
- tool = await this.client.tools.retrieve(slug, {
517
- toolkit_versions: this.toolkitVersions,
518
- });
517
+ // Build API call parameters based on version source
518
+ const retrieveParams = options?.version
519
+ ? { version: options.version } // Explicit version → use 'version' param
520
+ : { toolkit_versions: this.toolkitVersions }; // SDK config → use 'toolkit_versions' param
521
+
522
+ tool = await this.client.tools.retrieve(slug, retrieveParams);
523
} catch (error) {
524
throw new ComposioToolNotFoundError(`Unable to retrieve tool with slug ${slug}`, {
525
cause: error,
@@ -892,7 +896,11 @@ export class Tools<
896
897
// Determine if it's a custom tool or composio tool
898
const customTool = await this.customTools.getCustomToolBySlug(slug);
895
- const tool = customTool ?? (await this.getRawComposioToolBySlug(slug));
899
+ const tool =
900
+ customTool ??
901
+ (await this.getRawComposioToolBySlug(slug, {
902
+ version: body.version,
903
+ }));
904
const toolkitSlug = tool.toolkit?.slug ?? 'unknown';
905
906
// Apply before execute modifiers
ts/packages/core/src/types/tool.types.ts
+24
@@ -364,3 +364,27 @@ export type ToolProxyParams = z.infer<typeof ToolProxyParamsSchema>;
364
export type SchemaModifierOptions = {
365
modifySchema: TransformToolSchemaModifier;
366
};
367
+
368
+/**
369
+ * Options for retrieving tools from Composio API
370
+ */
371
+export type ToolRetrievalOptions = {
372
+ /**
373
+ * Optional function to transform the tool schema after retrieval
374
+ */
375
+ modifySchema?: TransformToolSchemaModifier;
376
+
377
+ /**
378
+ * Override the toolkit version for tool retrieval.
379
+ * Takes precedence over SDK-level toolkitVersions.
380
+ *
381
+ * @example Override with specific version
382
+ * ```typescript
383
+ * const tool = await tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE', {
384
+ * version: '20250909_00'
385
+ * });
386
+ * ```
387
+ * ```
388
+ */
389
+ version?: ToolkitVersion;
390
+};
ts/packages/core/test/tools/tools.test.ts
+174
@@ -368,6 +368,116 @@ describe('Tools', () => {
368
expect(schemaModifier).toHaveBeenCalled();
369
expect(result.description).toEqual('Modified description');
370
});
371
+
372
+ it('should use version parameter when provided (explicit version string)', async () => {
373
+ const slug = 'GITHUB_CREATE_ISSUE';
374
+ const explicitVersion = '20250909_00';
375
+
376
+ mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
377
+
378
+ await context.tools.getRawComposioToolBySlug(slug, {
379
+ version: explicitVersion,
380
+ });
381
+
382
+ // Should use 'version' param, not 'toolkit_versions'
383
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug, {
384
+ version: explicitVersion,
385
+ });
386
+ });
387
+
388
+ it('should use version parameter when provided (latest string)', async () => {
389
+ const slug = 'GITHUB_CREATE_ISSUE';
390
+
391
+ mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
392
+
393
+ await context.tools.getRawComposioToolBySlug(slug, {
394
+ version: 'latest',
395
+ });
396
+
397
+ // Should use 'version' param with 'latest'
398
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug, {
399
+ version: 'latest',
400
+ });
401
+ });
402
+
403
+ it('should use version parameter when provided (version mapping object)', async () => {
404
+ const slug = 'GITHUB_CREATE_ISSUE';
405
+ const versionMapping = { github: '20250909_00', slack: 'latest' };
406
+
407
+ mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
408
+
409
+ // Create a Tools instance with SDK-level toolkitVersions as mapping object
410
+ const toolsWithVersions = new Tools(mockClient as any, {
411
+ provider: context.mockProvider,
412
+ toolkitVersions: versionMapping,
413
+ });
414
+
415
+ await toolsWithVersions.getRawComposioToolBySlug(slug);
416
+
417
+ // Should use 'toolkit_versions' param with mapping object (not 'version')
418
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug, {
419
+ toolkit_versions: versionMapping,
420
+ });
421
+ });
422
+
423
+ it('should fallback to SDK toolkitVersions when version not provided', async () => {
424
+ const slug = 'GITHUB_CREATE_ISSUE';
425
+
426
+ mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
427
+
428
+ // Call without version option
429
+ await context.tools.getRawComposioToolBySlug(slug);
430
+
431
+ // Should use 'toolkit_versions' param with SDK-level config
432
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug, {
433
+ toolkit_versions: 'latest',
434
+ });
435
+ });
436
+
437
+ it('should prioritize explicit version over SDK toolkitVersions', async () => {
438
+ const slug = 'GITHUB_CREATE_ISSUE';
439
+ const explicitVersion = '20250909_00';
440
+
441
+ // Create a Tools instance with SDK-level toolkitVersions
442
+ const toolsWithVersions = new Tools(mockClient as any, {
443
+ provider: context.mockProvider,
444
+ toolkitVersions: { github: explicitVersion },
445
+ });
446
+
447
+ mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
448
+
449
+ await toolsWithVersions.getRawComposioToolBySlug(slug, {
450
+ version: explicitVersion,
451
+ });
452
+
453
+ // Explicit version should take precedence, using 'version' param
454
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug, {
455
+ version: explicitVersion,
456
+ });
457
+ });
458
+
459
+ it('should support combining version and modifySchema options', async () => {
460
+ const slug = 'GITHUB_CREATE_ISSUE';
461
+ const explicitVersion = '20250909_00';
462
+ const schemaModifier = createSchemaModifier({
463
+ description: 'Modified description',
464
+ });
465
+
466
+ mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
467
+
468
+ const result = await context.tools.getRawComposioToolBySlug(slug, {
469
+ version: explicitVersion,
470
+ modifySchema: schemaModifier,
471
+ });
472
+
473
+ // Should use version param
474
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug, {
475
+ version: explicitVersion,
476
+ });
477
+ // Should also apply schema modifier
478
+ expect(schemaModifier).toHaveBeenCalled();
479
+ expect(result.description).toEqual('Modified description');
480
+ });
481
});
482
483
describe('get', () => {
@@ -500,6 +610,70 @@ describe('Tools', () => {
610
});
611
expect(result).toEqual(toolMocks.toolExecuteResponse);
612
});
613
+
614
+ it('should pass version parameter from execute() to getRawComposioToolBySlug()', async () => {
615
+ const slug = 'COMPOSIO_TOOL';
616
+ const explicitVersion = '20250909_00';
617
+ const body = {
618
+ userId: 'test-user',
619
+ version: explicitVersion,
620
+ arguments: { title: 'Test Issue' },
621
+ };
622
+
623
+ const { getRawComposioToolBySlugSpy } = await mockToolExecution(context.tools);
624
+
625
+ await context.tools.execute(slug, body);
626
+
627
+ // Verify getRawComposioToolBySlug was called with version
628
+ expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, {
629
+ version: explicitVersion,
630
+ });
631
+
632
+ // Verify the API execute call received the version
633
+ expect(mockClient.tools.execute).toHaveBeenCalledWith(
634
+ slug,
635
+ expect.objectContaining({
636
+ version: explicitVersion,
637
+ })
638
+ );
639
+ });
640
+
641
+ it('should pass version: latest from execute() to getRawComposioToolBySlug()', async () => {
642
+ const slug = 'COMPOSIO_TOOL';
643
+ const body = {
644
+ userId: 'test-user',
645
+ version: 'latest' as const,
646
+ dangerouslySkipVersionCheck: true,
647
+ arguments: { title: 'Test Issue' },
648
+ };
649
+
650
+ const { getRawComposioToolBySlugSpy } = await mockToolExecution(context.tools);
651
+
652
+ await context.tools.execute(slug, body);
653
+
654
+ // Verify getRawComposioToolBySlug was called with version: 'latest'
655
+ expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, {
656
+ version: 'latest',
657
+ });
658
+ });
659
+
660
+ it('should not pass version to getRawComposioToolBySlug() when not provided in execute()', async () => {
661
+ const slug = 'COMPOSIO_TOOL';
662
+ const body = {
663
+ userId: 'test-user',
664
+ arguments: { title: 'Test Issue' },
665
+ dangerouslySkipVersionCheck: true,
666
+ };
667
+
668
+ const { getRawComposioToolBySlugSpy } = await mockToolExecution(context.tools);
669
+
670
+ await context.tools.execute(slug, body);
671
+
672
+ // Verify getRawComposioToolBySlug was called without version (should fallback to SDK config)
673
+ expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, {
674
+ version: undefined,
675
+ });
676
+ });
677
});
678
679
describe('proxyExecute', () => {