Tools API

List, retrieve, and execute tools from the Composio SDK

The tools API provides methods to discover and execute tools across 250+ integrations. Tools are individual actions like GITHUB_CREATE_ISSUE or GMAIL_SEND_EMAIL.

Methods

get()

Fetch tools wrapped in your provider’s format.

// Get tools by filters
async get<T extends TProvider>(
  userId: string,
  filters: ToolListParams,
  options?: ProviderOptions<TProvider>
): Promise<ReturnType<T['wrapTools']>>

// Get a single tool by slug
async get<T extends TProvider>(
  userId: string,
  slug: string,
  options?: ProviderOptions<TProvider>
): Promise<ReturnType<T['wrapTools']>>

userId · string · required

User ID for authentication and tracking

filters · ToolListParams

Show properties

toolkits · string[]

Filter by toolkit slugs (e.g., ['github', 'slack'])

tools · string[]

Specific tool slugs to fetch

tags · string[]

Filter by tags (e.g., ['important'])

search · string

Search tools by name or description

authConfigIds · string[]

Filter by auth config IDs

limit · number

Maximum number of tools to return

important · boolean

Auto-set to true when fetching by toolkit. Set to false to get all tools.

options · ProviderOptions

Show properties

modifySchema · TransformToolSchemaModifier

Transform tool schemas before wrapping

Get tools from toolkit

import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';

const composio = new Composio({
  apiKey: 'your-key',
  provider: new OpenAIProvider()
});

const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 10
});

// Use with OpenAI
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  tools,
  messages: [{ role: 'user', content: 'Create an issue' }]
});

Get specific tool

const tool = await composio.tools.get('default', 'GITHUB_CREATE_ISSUE');

Search tools

const tools = await composio.tools.get('default', {
  search: 'send email',
  limit: 5
});

With schema transformation

const tools = await composio.tools.get('default', {
  toolkits: ['github']
}, {
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => ({
    ...schema,
    description: `[${toolkitSlug}] ${schema.description}`
  })
});

execute()

Execute a tool directly.

async execute(
  slug: string,
  body: ToolExecuteParams,
  modifiers?: ExecuteToolModifiers
): Promise<ToolExecuteResponse>

slug · string · required

Tool slug to execute (e.g., GITHUB_CREATE_ISSUE)

body · ToolExecuteParams · required

Show properties

userId · string

User ID for authentication

connectedAccountId · string

Specific connected account to use

arguments · Record<string, unknown> · required

Tool input parameters

version · string

Specific toolkit version (e.g., 20250909_00)

dangerouslySkipVersionCheck · boolean

Skip version validation for “latest”. Not recommended for production.

modifiers · ExecuteToolModifiers

Show properties

beforeExecute · function

Transform parameters before execution

afterExecute · function

Transform results after execution

Basic execution

const result = await composio.tools.execute('GITHUB_CREATE_ISSUE', {
  userId: 'default',
  arguments: {
    owner: 'composio',
    repo: 'sdk',
    title: 'Bug report',
    body: 'Description of the bug'
  }
});

console.log(result.data); // Created issue
console.log(result.successful); // true

With version

const result = await composio.tools.execute('GITHUB_CREATE_ISSUE', {
  userId: 'default',
  version: '20250909_00',
  arguments: { owner: 'composio', repo: 'sdk', title: 'Issue' }
});

With modifiers

const result = await composio.tools.execute('GITHUB_GET_REPOS', {
  userId: 'default',
  arguments: { owner: 'composio' }
}, {
  beforeExecute: ({ params }) => {
    console.log('Executing with:', params.arguments);
    return params;
  },
  afterExecute: ({ result }) => {
    console.log('Got:', result.data);
    return result;
  }
});

getRawComposioTools()

Fetch tools in raw Composio format without provider wrapping.

async getRawComposioTools(
  query: ToolListParams,
  options?: SchemaModifierOptions
): Promise<ToolList>

Example:

const tools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 5
});

console.log(tools[0].slug); // GITHUB_CREATE_ISSUE
console.log(tools[0].inputParameters); // JSON Schema

getRawComposioToolBySlug()

Fetch a single tool in raw format.

async getRawComposioToolBySlug(
  slug: string,
  options?: ToolRetrievalOptions
): Promise<Tool>

Example:

const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');

console.log(tool.name); // "Create Issue"
console.log(tool.version); // "20250909_00"
console.log(tool.inputParameters); // JSON Schema

createCustomTool()

Create a custom tool with your own logic.

async createCustomTool<T extends CustomToolInputParameter>(
  body: CustomToolOptions<T>
): Promise<Tool>

body · CustomToolOptions · required

Show properties

name · string · required

Human-readable tool name

slug · string · required

Unique tool identifier (uppercase snake_case)

description · string · required

What the tool does

inputParams · ZodSchema · required

Zod schema for input validation

execute · function · required

Async function that executes the tool

toolkitSlug · string

Associate with a toolkit for auth

Simple custom tool

import { z } from 'zod';

const tool = await composio.tools.createCustomTool({
  name: 'Weather Search',
  slug: 'WEATHER_SEARCH',
  description: 'Get current weather for a location',
  inputParams: z.object({
    location: z.string().describe('City name')
  }),
  execute: async (input) => {
    const weather = await fetch(`https://api.weather.com/${input.location}`);
    return {
      data: await weather.json(),
      error: null,
      successful: true
    };
  }
});

With toolkit integration

const tool = await composio.tools.createCustomTool({
  name: 'GitHub Advanced Search',
  slug: 'GITHUB_ADVANCED_SEARCH',
  description: 'Custom GitHub search with filters',
  toolkitSlug: 'github', // Use GitHub auth
  userId: 'default',
  connectedAccountId: 'conn_123',
  inputParams: z.object({
    query: z.string(),
    language: z.string().optional()
  }),
  execute: async (input, connectionConfig, executeToolRequest) => {
    // Use executeToolRequest to make authenticated calls
    const result = await executeToolRequest({
      endpoint: '/search/repositories',
      method: 'GET',
      parameters: [
        { name: 'q', in: 'query', value: input.query },
        { name: 'language', in: 'query', value: input.language || '' }
      ]
    });
    return result;
  }
});

getToolsEnum()

Get a list of all available tool slugs.

async getToolsEnum(): Promise<ToolRetrieveEnumResponse>

Example:

const allTools = await composio.tools.getToolsEnum();
console.log(allTools.items); // ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE', ...]

Types

ToolExecuteResponse

Result from tool execution.

interface ToolExecuteResponse {
  data: Record<string, unknown>; // Tool output
  error: string | null; // Error message if failed
  successful: boolean; // Whether execution succeeded
  logId?: string; // Log ID for debugging
  sessionInfo?: Record<string, unknown>; // Session metadata
}

Tool

Raw tool schema.

interface Tool {
  slug: string; // Tool identifier
  name: string; // Human-readable name
  description: string; // What the tool does
  inputParameters: JSONSchema; // Input schema
  outputParameters: JSONSchema; // Output schema
  toolkit?: { // Associated toolkit
    name: string;
    slug: string;
  };
  version?: string; // Toolkit version
  availableVersions?: string[]; // All available versions
  isDeprecated?: boolean; // Deprecated status
  isNoAuth?: boolean; // Requires no authentication
}

Next Steps

Toolkits API

Discover available toolkits

Connected Accounts

Manage user authentication

Custom Tools

Create custom tools

Providers

Choose your AI framework