Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # Tools API |
| 2 | |
| 3 | The `Tools` class provides methods to list, retrieve, and execute tools from various toolkits. It is one of the core components of the Composio SDK. |
| 4 | |
| 5 | ## Methods |
| 6 | |
| 7 | ### get(userId, filters, options?) |
| 8 | |
| 9 | Retrieves and wraps tools based on the provided filters. Tool versions are controlled at the Composio SDK initialization level through the `toolkitVersions` configuration. See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for more details on version management. |
| 10 | |
| 11 | #### Overload 1: Get multiple tools with filters |
| 12 | |
| 13 | ```typescript |
| 14 | // Get important tools from a toolkit (auto-applies important filter) |
| 15 | const importantGithubTools = await composio.tools.get('default', { |
| 16 | toolkits: ['github'] |
| 17 | }); |
| 18 | |
| 19 | // Get a limited number of tools (does NOT auto-apply important filter) |
| 20 | const githubTools = await composio.tools.get('default', { |
| 21 | toolkits: ['github'], |
| 22 | limit: 10 |
| 23 | }); |
| 24 | |
| 25 | // Get tools with search (does NOT auto-apply important filter) |
| 26 | const searchTools = await composio.tools.get('default', { |
| 27 | search: 'user' |
| 28 | }); |
| 29 | |
| 30 | // Get tools with schema modifications |
| 31 | const customizedTools = await composio.tools.get('default', { |
| 32 | toolkits: ['github'] |
| 33 | }, { |
| 34 | modifySchema: ({ toolSlug, toolkitSlug, schema }) => { |
| 35 | return { ...schema, description: 'Custom description' }; |
| 36 | } |
| 37 | }); |
| 38 | ``` |
| 39 | |
| 40 | **Parameters:** |
| 41 | - `userId` (string): The user ID to get the tools for |
| 42 | - `filters` (ToolListParams): Filters object to specify which tools to retrieve |
| 43 | - `options` (ProviderOptions): Optional provider options including modifiers |
| 44 | |
| 45 | #### Overload 2: Get a specific tool by slug |
| 46 | |
| 47 | ```typescript |
| 48 | // Get a specific tool by slug |
| 49 | const tool = await composio.tools.get('default', 'GITHUB_GET_REPO'); |
| 50 | |
| 51 | // Get a tool with schema modifications |
| 52 | const customTool = await composio.tools.get('default', 'GITHUB_GET_REPOS', { |
| 53 | modifySchema: ({ toolSlug, toolkitSlug, schema }) => { |
| 54 | return { ...schema, description: 'Enhanced GitHub repository tool' }; |
| 55 | } |
| 56 | }); |
| 57 | ``` |
| 58 | |
| 59 | **Parameters:** |
| 60 | - `userId` (string): The user ID to get the tool for |
| 61 | - `slug` (string): The slug of the specific tool to fetch |
| 62 | - `options` (ProviderOptions): Optional provider options including modifiers |
| 63 | |
| 64 | **Returns:** The wrapped tools collection, formatted according to the provider being used |
| 65 | |
| 66 | ### execute(slug, body, modifiers?) |
| 67 | |
| 68 | Executes a given tool with the provided parameters manually. |
| 69 | |
| 70 | > **Important:** When manually executing tools (especially in workflows), a specific version is **required**. The method will throw an error if toolkitVersion is not provided or `latest` is used as the version. This ensures there are no mismatches in tool arguments when new versions are released. You can bypass this requirement using `dangerouslySkipVersionCheck: true`, but this is **not recommended for production**. |
| 71 | |
| 72 | ```typescript |
| 73 | // Execute with a pinned version (REQUIRED for workflows and manual execution) |
| 74 | const result = await composio.tools.execute('GITHUB_GET_ISSUES', { |
| 75 | userId: 'default', |
| 76 | arguments: { owner: 'composio', repo: 'sdk' }, |
| 77 | version: '12082025_00', // Specific version required |
| 78 | }); |
| 79 | |
| 80 | // Or configure versions at initialization (RECOMMENDED) |
| 81 | const composio = new Composio({ |
| 82 | toolkitVersions: { |
| 83 | github: '12082025_00', |
| 84 | slack: '10082025_01' |
| 85 | } |
| 86 | }); |
| 87 | |
| 88 | const result = await composio.tools.execute('GITHUB_GET_ISSUES', { |
| 89 | userId: 'default', |
| 90 | arguments: { owner: 'composio', repo: 'sdk' }, |
| 91 | // Uses pinned version from initialization |
| 92 | }); |
| 93 | |
| 94 | // Execute with dangerouslySkipVersionCheck (NOT recommended for production) |
| 95 | // This allows using 'latest' version and bypasses version validation |
| 96 | const result = await composio.tools.execute('SLACK_SEND_MESSAGE', { |
| 97 | userId: 'default', |
| 98 | arguments: { channel: '#general', text: 'Hello!' }, |
| 99 | dangerouslySkipVersionCheck: true, // Skip version validation (use with caution) |
| 100 | }); |
| 101 | |
| 102 | // Execute with modifiers |
| 103 | const result = await composio.tools.execute( |
| 104 | 'GITHUB_GET_ISSUES', |
| 105 | { |
| 106 | userId: 'default', |
| 107 | arguments: { owner: 'composio', repo: 'sdk' }, |
| 108 | version: '12082025_00', // Always specify version |
| 109 | }, |
| 110 | { |
| 111 | beforeExecute: ({ toolSlug, toolkitSlug, params }) => { |
| 112 | // Modify params before execution |
| 113 | return params; |
| 114 | }, |
| 115 | afterExecute: ({ toolSlug, toolkitSlug, result }) => { |
| 116 | // Transform result after execution |
| 117 | return result; |
| 118 | }, |
| 119 | } |
| 120 | ); |
| 121 | ``` |
| 122 | |
| 123 | **Parameters:** |
| 124 | |
| 125 | - `slug` (string): The slug/ID of the tool to be executed |
| 126 | - `body` (ToolExecuteParams): The parameters to be passed to the tool |
| 127 | - `modifiers` (ExecuteToolModifiers): Optional modifiers to transform the request or response |
| 128 | |
| 129 | #### Version Requirements for Manual Tool Execution |
| 130 | |
| 131 | When building workflows that require manually executing tools, **a specific pinned version is mandatory**. Using `'latest'` is not allowed and will throw an error. This strict requirement prevents argument mismatches that can occur when tool schemas change in newer versions. |
| 132 | |
| 133 | **Why Version Pinning is Required:** |
| 134 | - Tool argument schemas can change between versions |
| 135 | - Using `'latest'` in workflows can cause runtime errors when tools are updated |
| 136 | - Pinned versions ensure workflow stability and predictability |
| 137 | - Version validation prevents production issues from schema mismatches |
| 138 | |
| 139 | **Three Approaches to Handle Versions:** |
| 140 | |
| 141 | **1. Specify a concrete version in the execute call** (Recommended): |
| 142 | ```typescript |
| 143 | const result = await composio.tools.execute('GITHUB_GET_ISSUES', { |
| 144 | userId: 'default', |
| 145 | arguments: { owner: 'composio', repo: 'sdk' }, |
| 146 | version: '12082025_00', // Explicit version for this tool |
| 147 | }); |
| 148 | ``` |
| 149 | |
| 150 | **2. Configure toolkit versions at initialization** (Recommended for production): |
| 151 | ```typescript |
| 152 | const composio = new Composio({ |
| 153 | toolkitVersions: { |
| 154 | github: '12082025_00', |
| 155 | slack: '10082025_01' |
| 156 | } |
| 157 | }); |
| 158 | |
| 159 | // Now execute without version parameter - uses pinned version from config |
| 160 | const result = await composio.tools.execute('GITHUB_GET_ISSUES', { |
| 161 | userId: 'default', |
| 162 | arguments: { owner: 'composio', repo: 'sdk' }, |
| 163 | }); |
| 164 | ``` |
| 165 | |
| 166 | **3. Use `dangerouslySkipVersionCheck: true`** (NOT recommended for production): |
| 167 | ```typescript |
| 168 | const result = await composio.tools.execute('GITHUB_GET_ISSUES', { |
| 169 | userId: 'default', |
| 170 | arguments: { owner: 'composio', repo: 'sdk' }, |
| 171 | dangerouslySkipVersionCheck: true, // Bypasses version validation and uses 'latest' |
| 172 | }); |
| 173 | ``` |
| 174 | |
| 175 | > ⚠️ **Warning:** Using `dangerouslySkipVersionCheck: true` bypasses version validation and allows the use of `'latest'` version. This can lead to unexpected behavior and argument mismatches when tool schemas change. **Only use this flag during development or testing.** Always pin specific versions in production environments to ensure workflow stability. |
| 176 | |
| 177 | **Returns:** Promise<ToolExecuteResponse> - The response from the tool execution |
| 178 | |
| 179 | **Throws:** |
| 180 | |
| 181 | - `ComposioToolNotFoundError`: If the tool with the given slug is not found |
| 182 | - `ComposioToolExecutionError`: If there is an error during tool execution |
| 183 | |
| 184 | ### getRawComposioTools(query, options?) |
| 185 | |
| 186 | Lists all tools available from the Composio API. This method provides direct access to tool data without provider-specific wrapping. |
| 187 | |
| 188 | ```typescript |
| 189 | // Get important tools from a toolkit (auto-applies important filter) |
| 190 | const importantGithubTools = await composio.tools.getRawComposioTools({ |
| 191 | toolkits: ['github'] |
| 192 | }); |
| 193 | |
| 194 | // Get a limited number of tools (does NOT auto-apply important) |
| 195 | const limitedTools = await composio.tools.getRawComposioTools({ |
| 196 | toolkits: ['github'], |
| 197 | limit: 10 |
| 198 | }); |
| 199 | |
| 200 | // Get specific tools by slug |
| 201 | const specificTools = await composio.tools.getRawComposioTools({ |
| 202 | tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER'] |
| 203 | }); |
| 204 | |
| 205 | // Get tools with schema transformation |
| 206 | const customizedTools = await composio.tools.getRawComposioTools({ |
| 207 | toolkits: ['github'], |
| 208 | limit: 5 |
| 209 | }, { |
| 210 | modifySchema: ({ toolSlug, toolkitSlug, schema }) => { |
| 211 | return { |
| 212 | ...schema, |
| 213 | customProperty: `Modified ${toolSlug} from ${toolkitSlug}`, |
| 214 | tags: [...(schema.tags || []), 'customized'] |
| 215 | }; |
| 216 | } |
| 217 | }); |
| 218 | |
| 219 | // Search for tools |
| 220 | const searchResults = await composio.tools.getRawComposioTools({ |
| 221 | search: 'user management' |
| 222 | }); |
| 223 | ``` |
| 224 | |
| 225 | **Parameters:** |
| 226 | |
| 227 | - `query` (ToolListParams): Query parameters to filter the tools (required) |
| 228 | - `options` (GetRawComposioToolsOptions): Optional configuration for tool retrieval |
| 229 | - `modifySchema` (TransformToolSchemaModifier): Function to transform tool schemas |
| 230 | |
| 231 | **Returns:** Promise<ToolList> - List of tools matching the query criteria |
| 232 | |
| 233 | ### getRawComposioToolBySlug(slug, options?) |
| 234 | |
| 235 | Retrieves a specific tool by its slug from the Composio API. This method provides direct access to tool schema and metadata without provider-specific wrapping. |
| 236 | |
| 237 | ```typescript |
| 238 | // Get a tool by slug |
| 239 | const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS'); |
| 240 | |
| 241 | // Get a tool with schema transformation |
| 242 | const customizedTool = await composio.tools.getRawComposioToolBySlug( |
| 243 | 'SLACK_SEND_MESSAGE', |
| 244 | { |
| 245 | modifySchema: ({ toolSlug, toolkitSlug, schema }) => { |
| 246 | return { |
| 247 | ...schema, |
| 248 | description: `Enhanced ${schema.description} with custom modifications`, |
| 249 | customMetadata: { |
| 250 | lastModified: new Date().toISOString(), |
| 251 | toolkit: toolkitSlug |
| 252 | } |
| 253 | }; |
| 254 | } |
| 255 | } |
| 256 | ); |
| 257 | |
| 258 | // Access tool properties |
| 259 | const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_AN_ISSUE'); |
| 260 | console.log({ |
| 261 | slug: githubTool.slug, |
| 262 | name: githubTool.name, |
| 263 | toolkit: githubTool.toolkit?.name, |
| 264 | version: githubTool.version, |
| 265 | availableVersions: githubTool.availableVersions |
| 266 | }); |
| 267 | ``` |
| 268 | |
| 269 | **Parameters:** |
| 270 | |
| 271 | - `slug` (string): The unique identifier of the tool (e.g., 'GITHUB_GET_REPOS') |
| 272 | - `options` (GetRawComposioToolBySlugOptions): Optional configuration for tool retrieval |
| 273 | - `modifySchema` (TransformToolSchemaModifier): Function to transform the tool schema |
| 274 | |
| 275 | **Returns:** Promise<Tool> - The requested tool with its complete schema and metadata |
| 276 | |
| 277 | ## Types |
| 278 | |
| 279 | ### ToolListParams |
| 280 | |
| 281 | ```typescript |
| 282 | // You must provide one of the following parameter combinations: |
| 283 | // 1. tools array only |
| 284 | // 2. toolkits (optionally filter to important tools) |
| 285 | // 3. toolkits with search functionality |
| 286 | |
| 287 | type ToolsOnlyParams = { |
| 288 | tools: string[]; // List of tool slugs to filter by |
| 289 | toolkits?: never; // Cannot be used with tools |
| 290 | limit?: never; |
| 291 | search?: never; |
| 292 | scopes?: never; |
| 293 | } |
| 294 | |
| 295 | type ToolkitsOnlyParams = { |
| 296 | tools?: never; // Cannot be used with toolkits |
| 297 | toolkits: string[]; // List of toolkit slugs to filter by |
| 298 | limit?: number; // Limit the number of results (prevents auto-applying important) |
| 299 | search?: string; // Optional search term (prevents auto-applying important) |
| 300 | tags?: string[]; // Optional tags filter (prevents auto-applying important) |
| 301 | important?: boolean; // Filter to only important/featured tools (auto-applied when no limit/tags/search) |
| 302 | scopes?: never; |
| 303 | }; |
| 304 | |
| 305 | type ToolkitScopeOnlyParams = { |
| 306 | tools?: never; |
| 307 | toolkits: [string]; |
| 308 | scopes: string[]; |
| 309 | limit?: number; // Prevents auto-applying important |
| 310 | search?: string; // Prevents auto-applying important |
| 311 | tags?: string[]; // Prevents auto-applying important |
| 312 | important?: boolean; // Filter to only important/featured tools (auto-applied when no limit/tags/search) |
| 313 | }; |
| 314 | |
| 315 | type ToolkitSearchOnlyParams = { |
| 316 | tools?: never; // Cannot be used with search |
| 317 | toolkits?: string[]; // Optional list of toolkit slugs to filter by |
| 318 | limit?: number; // Limit the number of results |
| 319 | search: string; // Search term |
| 320 | scopes?: never; |
| 321 | }; |
| 322 | |
| 323 | type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | ToolkitScopeOnlyParams | ToolkitSearchOnlyParams; |
| 324 | ``` |
| 325 | |
| 326 | #### Auto-applying the `important` Filter |
| 327 | |
| 328 | 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. |
| 329 | |
| 330 | **Auto-apply conditions:** |
| 331 | - ✅ `toolkits` is provided |
| 332 | - ✅ `tools` is NOT provided |
| 333 | - ✅ `tags` is NOT provided |
| 334 | - ✅ `search` is NOT provided |
| 335 | - ✅ `limit` is NOT provided |
| 336 | - ✅ `important` is NOT explicitly set to `false` |
| 337 | |
| 338 | **Examples:** |
| 339 | |
| 340 | ```typescript |
| 341 | // Auto-applies important: true |
| 342 | const tools = await composio.tools.getRawComposioTools({ |
| 343 | toolkits: ['github'] |
| 344 | }); |
| 345 | // Result: Only important GitHub tools |
| 346 | |
| 347 | // Does NOT auto-apply important (limit provided) |
| 348 | const tools = await composio.tools.getRawComposioTools({ |
| 349 | toolkits: ['github'], |
| 350 | limit: 50 |
| 351 | }); |
| 352 | // Result: First 50 GitHub tools (including non-important) |
| 353 | |
| 354 | // Does NOT auto-apply important (tags provided) |
| 355 | const tools = await composio.tools.getRawComposioTools({ |
| 356 | toolkits: ['github'], |
| 357 | tags: ['important'] |
| 358 | }); |
| 359 | // Result: GitHub tools with 'important' tag |
| 360 | |
| 361 | // Does NOT auto-apply important (search provided) |
| 362 | const tools = await composio.tools.getRawComposioTools({ |
| 363 | toolkits: ['github'], |
| 364 | search: 'repository' |
| 365 | }); |
| 366 | // Result: GitHub tools matching 'repository' search |
| 367 | |
| 368 | // Explicitly disable auto-apply |
| 369 | const tools = await composio.tools.getRawComposioTools({ |
| 370 | toolkits: ['github'], |
| 371 | important: false |
| 372 | }); |
| 373 | // Result: All GitHub tools (including non-important) |
| 374 | |
| 375 | // Explicitly enable important even with limit |
| 376 | const tools = await composio.tools.getRawComposioTools({ |
| 377 | toolkits: ['github'], |
| 378 | limit: 20, |
| 379 | important: true |
| 380 | }); |
| 381 | // Result: First 20 important GitHub tools |
| 382 | ``` |
| 383 | |
| 384 | **Why does `limit` prevent auto-applying `important`?** |
| 385 | |
| 386 | 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. |
| 387 | |
| 388 | Note: The parameters are organized into three mutually exclusive combinations: |
| 389 | |
| 390 | 1. Using `tools` array to fetch specific tools by their slugs |
| 391 | 2. Using `toolkits` with optional `important` flag to fetch tools from specific toolkits |
| 392 | 3. Using `search` with optional `toolkits` to search for tools by name/description |
| 393 | 4. Using `scopes` can only be done with a single `toolkits` slug |
| 394 | |
| 395 | You can also filter tools by their scopes: |
| 396 | |
| 397 | ```typescript |
| 398 | // Get tools with specific scopes |
| 399 | const scopedTools = await composio.tools.get('default', { |
| 400 | toolkits: ['github'], |
| 401 | scopes: ['read:repo', 'write:repo'], // Only get tools requiring these scopes |
| 402 | }); |
| 403 | |
| 404 | // Search tools with specific scopes |
| 405 | const searchedScopedTools = await composio.tools.get('default', { |
| 406 | search: 'repository', |
| 407 | scopes: ['read:repo'], // Only get tools requiring read:repo scope |
| 408 | limit: 10, |
| 409 | }); |
| 410 | ``` |
| 411 | |
| 412 | The `scopes` parameter allows you to: |
| 413 | - Filter tools based on their required OAuth scopes |
| 414 | - Get tools that match specific permission levels |
| 415 | - Ensure tools align with available user permissions |
| 416 | |
| 417 | Examples: |
| 418 | |
| 419 | ```typescript |
| 420 | // Get specific tools by slug |
| 421 | const specificTools = await composio.tools.get('default', { |
| 422 | tools: ['GITHUB_GET_REPO', 'GITHUB_LIST_ISSUES'], |
| 423 | }); |
| 424 | |
| 425 | // Search for tools across all or specific toolkits |
| 426 | const searchResults = await composio.tools.get('default', { |
| 427 | search: 'repository', |
| 428 | toolkits: ['github'], // optional |
| 429 | limit: 10, |
| 430 | }); |
| 431 | ``` |
| 432 | |
| 433 | ### ToolExecuteParams |
| 434 | |
| 435 | ```typescript |
| 436 | interface ToolExecuteParams { |
| 437 | allowTracing?: boolean; // Enable/disable tracing |
| 438 | connectedAccountId?: string; // Connected account ID |
| 439 | customAuthParams?: CustomAuthParams; // Custom auth parameters |
| 440 | customConnectionData?: CustomConnectionData; // Custom connection data |
| 441 | arguments?: Record<string, unknown>; // Tool arguments |
| 442 | userId: string; // User ID (required) |
| 443 | version?: string; // Tool version (e.g., '12082025_00') - overrides global toolkit version |
| 444 | dangerouslySkipVersionCheck?: boolean; // Skip version validation (NOT recommended for production) |
| 445 | text?: string; // Text input |
| 446 | } |
| 447 | ``` |
| 448 | |
| 449 | **Parameter Details:** |
| 450 | |
| 451 | - **`version`** (string, conditionally required): Specifies the toolkit version to use for this tool execution. **Required when manually executing tools** unless a specific version is configured at initialization or `dangerouslySkipVersionCheck` is set to `true`. Using `'latest'` will throw a `ValidationError` to prevent schema mismatches in workflows. Format: `'DDMMYYYY_NN'` (e.g., `'12082025_00'`). See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for more details. |
| 452 | |
| 453 | - **`dangerouslySkipVersionCheck`** (boolean, optional): When set to `true`, bypasses version validation during tool execution and allows using `'latest'` version. This is useful for development and testing but **NOT recommended for production** as it can lead to unexpected behavior and argument mismatches when tool schemas change. Always pin specific toolkit versions at initialization or pass a `version` parameter in production environments. |
| 454 | |
| 455 | ### ToolExecuteResponse |
| 456 | |
| 457 | ```typescript |
| 458 | interface ToolExecuteResponse { |
| 459 | data: Record<string, unknown>; // Tool execution data |
| 460 | error: string | null; // Error message (if any) |
| 461 | successful: boolean; // Whether the execution was successful |
| 462 | logId?: string; // Log ID for debugging |
| 463 | sessionInfo?: unknown; // Session information |
| 464 | } |
| 465 | ``` |