Tools
Tools are the fundamental building blocks of the Composio SDK. They represent individual actions that can be executed on third-party services, such as creating a GitHub repository, sending a Slack message, or retrieving Hacker News data.
Overview
The Tools class manages tool operations in the Composio SDK. It provides methods to list, retrieve, and execute tools, along with support for custom tools and execution modifiers.
Source: ts/packages/core/src/models/Tools.ts
Retrieve tools from specific toolkits with optional filtering:
// Get tools from the GitHub toolkit
const githubTools = await composio.tools.getRawComposioTools({
toolkits: ['github'],
limit: 10
});
// Get all important tools from multiple toolkits
const tools = await composio.tools.getRawComposioTools({
toolkits: ['github', 'slack'],
important: true
});
When fetching tools by toolkit without specifying tools, tags, search, or limit parameters, the SDK automatically sets important: true to return only the most commonly used tools.
// Get specific tools by slug
const specificTools = await composio.tools.getRawComposioTools({
tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
});
// Search for tools by keyword
const searchResults = await composio.tools.getRawComposioTools({
search: 'user management'
});
Filter by Authentication
// Get tools by authentication config
const authSpecificTools = await composio.tools.getRawComposioTools({
authConfigIds: ['auth_config_123']
});
// Get a tool by slug
const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS');
console.log(tool.name, tool.description);
// Access tool properties
const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
console.log({
slug: githubTool.slug,
name: githubTool.name,
toolkit: githubTool.toolkit?.name,
version: githubTool.version,
availableVersions: githubTool.availableVersions,
inputParameters: githubTool.inputParameters
});
get method fetches tools and wraps them in provider-specific format:
// Get tools from the GitHub toolkit
const tools = await composio.tools.get('default', {
toolkits: ['github'],
limit: 10
});
// Get tools with search
const searchTools = await composio.tools.get('default', {
search: 'user',
limit: 10
});
// Get a specific tool by slug
const hackerNewsUserTool = await composio.tools.get('default', 'HACKERNEWS_GET_USER');
Basic Execution
By default, manual tool execution requires a specific toolkit version. If the version resolves to “latest”, execution will throw a ComposioToolVersionRequiredError unless dangerouslySkipVersionCheck is set to true.
// Execute with a specific version (recommended for production)
const result = await composio.tools.execute('GITHUB_GET_REPOS', {
userId: 'default',
version: '20250909_00',
arguments: { owner: 'composio' }
});
Version Control Options
// Execute with SDK-level toolkit versions configuration
const composio = new Composio({
toolkitVersions: { github: '20250909_00' }
});
const result = await composio.tools.execute('GITHUB_GET_REPOS', {
userId: 'default',
arguments: { owner: 'composio' }
});
// Execute with dangerouslySkipVersionCheck (not recommended for production)
const result = await composio.tools.execute('HACKERNEWS_GET_USER', {
userId: 'default',
arguments: { userId: 'pg' },
dangerouslySkipVersionCheck: true // Allows execution with "latest" version
});
Execution with Modifiers
Modifiers allow you to transform inputs and outputs during tool execution:
const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
userId: 'default',
version: '20250909_00',
arguments: { owner: 'composio', repo: 'sdk' }
}, {
beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
console.log(`Executing ${toolSlug} from ${toolkitSlug}`);
return params;
},
afterExecute: ({ toolSlug, toolkitSlug, result }) => {
console.log(`Completed ${toolSlug}`);
return result;
}
});
// Get a tool with schema transformation
const customizedTool = await composio.tools.getRawComposioToolBySlug(
'SLACK_SEND_MESSAGE',
{
modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
return {
...schema,
description: `Enhanced ${schema.description} with custom modifications`,
customMetadata: {
lastModified: new Date().toISOString(),
toolkit: toolkitSlug
}
};
}
}
);
// Get tools with schema modification
const customizedTools = await composio.tools.getRawComposioTools({
toolkits: ['github'],
limit: 5
}, {
modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
return {
...schema,
customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
tags: [...(schema.tags || []), 'customized']
};
}
});
slug - Unique identifier (e.g., ‘GITHUB_GET_REPOS’)name - Human-readable namedescription - Tool descriptioninputParameters - JSON Schema for input parametersoutputParameters - JSON Schema for output responsetoolkit - Associated toolkit informationversion - Current tool versionavailableVersions - List of available versionsisDeprecated - Whether the tool is deprecatedisNoAuth - Whether authentication is requiredtags - Categorization tags
Advanced Features
Fetch meta tools for tool router sessions:
const metaTools = await composio.tools.getRawToolRouterMetaTools('session_123');
console.log(metaTools);
const result = await composio.tools.executeMetaTool(
'TOOL_SLUG',
{
sessionId: 'session_123',
arguments: { param: 'value' }
},
{
beforeExecute: ({ toolSlug, sessionId, params }) => {
console.log(`Executing meta tool ${toolSlug}`);
return params;
}
}
);
Proxy Execute
Send custom requests to toolkits:
const response = await composio.tools.proxyExecute({
toolkitSlug: 'github',
userId: 'default',
endpoint: '/repos/owner/repo/issues',
method: 'GET',
parameters: [
{ name: 'state', in: 'query', value: 'open' }
]
});
console.log(response.data);
// Get input parameters for a specific tool
const inputParams = await composio.tools.getInput('GITHUB_CREATE_ISSUE', {
userId: 'default'
});
console.log(inputParams.schema);
// Get all available tools as an enum (used primarily by CLI)
const toolsEnum = await composio.tools.getToolsEnum();
console.log(toolsEnum.items);
Auto File Upload/Download
The SDK supports automatic file handling for tools that work with files:
const composio = new Composio({
apiKey: 'your-key',
autoUploadDownloadFiles: true // Enable automatic file handling
});
When autoUploadDownloadFiles is enabled, the SDK automatically uploads files before execution and downloads result files after execution.
Error Handling
Common errors when working with tools:
ComposioToolNotFoundError - Tool with the given slug doesn’t existComposioToolVersionRequiredError - Version resolves to “latest” and dangerouslySkipVersionCheck is not trueComposioToolExecutionError - Error during tool executionValidationError - Invalid parameters passed to tool methodsComposioProviderNotDefinedError - Provider not configured when initializing Tools