Tools API — Composio TypeScript SDK Reference Guide

The Tools class manages tool retrieval and execution. Use composio.tools.get() to retrieve tools formatted for your AI provider, and composio.tools.execute() to run any tool directly. All tools — both built-in Composio tools and custom tools registered via createCustomTool() — are accessible through this interface.

tools.get()

Retrieve tools formatted for your AI provider. The returned collection depends on the active provider — for OpenAIProvider this is an array of OpenAI function-calling tool definitions.

composio.tools.get(
  userId: string,
  filters: ToolListParams,
  options?: ProviderOptions
): Promise<TToolCollection>

You can also retrieve a single tool by slug:

composio.tools.get(
  userId: string,
  slug: string,
  options?: ProviderOptions
): Promise<TToolCollection>

userId

string

required

External user identifier whose connected accounts are used to scope tool execution.

filters

ToolListParams

Filters that control which tools are returned. Provide one of toolkits, tools, search, or authConfigIds.

Show ToolListParams fields

toolkits

string[]

Filter by toolkit slugs (e.g. ['github', 'slack']). Cannot be combined with tools.

tools

string[]

Filter by specific tool slugs (e.g. ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE']). Cannot be combined with toolkits.

tools.execute()

Execute any tool directly by slug. This bypasses the provider and returns a raw ToolExecuteResponse. By default, manual execution requires a pinned toolkit version — pass dangerouslySkipVersionCheck: true or configure toolkitVersions at SDK initialization to avoid the version check.

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

slug

string

required

Tool identifier (e.g. 'GITHUB_CREATE_ISSUE').

body

ToolExecuteParams

required

Execution parameters.

Show ToolExecuteParams fields

userId

string

User ID whose connected account is used for authenticated tool calls.

arguments

Record<string, unknown>

Input arguments matching the tool’s input schema.

connectedAccountId

string

Specific connected account ID to use, overriding automatic account selection.

version

string

Specific toolkit version to execute against (e.g. '20250902_00'). Takes precedence over SDK-level toolkitVersions.

dangerouslySkipVersionCheck

boolean

Skip the version check that prevents execution when the resolved version is 'latest'. Not recommended for production.

modifiers

ExecuteToolModifiers

Lifecycle hooks for the execution.

Show ExecuteToolModifiers fields

beforeExecute

function

Called before execution. Receives { toolSlug, toolkitSlug, params }, returns modified params.

afterExecute

function

Called after execution. Receives { toolSlug, toolkitSlug, result }, returns modified result.

beforeFileUpload

function

Called before each file is uploaded during automatic file upload (requires dangerouslyAllowAutoUploadDownloadFiles: true).

ToolExecuteResponse

data

Record<string, unknown>

The tool’s output data.

error

string | null

Error message if the tool failed, otherwise null.

successful

boolean

true when the tool executed without errors.

logId

string | undefined

Composio log identifier for this execution, useful for debugging.

sessionInfo

unknown | undefined

Optional session metadata returned by the backend for tool router session executions.

tools.getRawComposioTools()

Fetch tools in the internal SDK format without provider wrapping. Useful when you need to inspect tool schemas directly or build custom provider integrations.

composio.tools.getRawComposioTools(
  query: ToolListParams,
  options?: { modifySchema?: TransformToolSchemaModifier }
): Promise<Tool[]>

tools.getRawComposioToolBySlug()

Fetch a single tool by slug in the internal SDK format.

composio.tools.getRawComposioToolBySlug(
  slug: string,
  options?: { modifySchema?: TransformToolSchemaModifier; version?: string }
): Promise<Tool>

tools.proxyExecute()

Proxy a custom HTTP request through a toolkit’s connected account authentication layer, without calling a specific tool.

composio.tools.proxyExecute(body: ToolProxyParams): Promise<ToolProxyResponse>

body.endpoint

string

required

The API endpoint URL to call.

body.method

string

required

HTTP method ('GET', 'POST', 'PUT', 'DELETE', 'PATCH').

body.connectedAccountId

string

required

Connected account whose credentials are injected.

body.body

unknown

Request body for POST/PUT/PATCH requests.

body.parameters

array

Additional query or header parameters to inject.

Modifiers

Modifiers are hooks that transform tool inputs and outputs globally for all provider-dispatched calls.

Modifier	When it runs	Use case
`beforeExecute`	Before tool execution	Inject extra arguments, log requests, enforce policies
`afterExecute`	After tool execution	Sanitize responses, log results, transform output
`modifySchema`	During tool retrieval	Add/remove schema fields, override descriptions

Examples

Get tools for OpenAI
Execute a tool directly
Schema modifier
Execute with lifecycle hooks

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

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const openai = new OpenAI();

// Get GitHub tools for a user — provider formats them as OpenAI function definitions
const tools = await composio.tools.get('user_123', {
  toolkits: ['github'],
  limit: 10,
});

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'List my GitHub repositories.' }],
  tools,
});

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

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  toolkitVersions: { github: '20250902_00' },
});

const result = await composio.tools.execute('GITHUB_CREATE_ISSUE', {
  userId: 'user_123',
  arguments: {
    owner: 'my-org',
    repo: 'my-repo',
    title: 'Bug: something is broken',
    body: 'Steps to reproduce...',
  },
});

if (result.successful) {
  console.log('Issue created:', result.data);
} else {
  console.error('Error:', result.error);
}

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

const result = await composio.tools.execute(
  'SLACK_SEND_MESSAGE',
  {
    userId: 'user_123',
    version: '20250902_00',
    arguments: { channel: '#general', text: 'Hello!' },
  },
  {
    beforeExecute: ({ toolSlug, params }) => {
      console.log(`Calling ${toolSlug}`, params.arguments);
      return params;
    },
    afterExecute: ({ toolSlug, result }) => {
      console.log(`${toolSlug} completed:`, result.successful);
      return result;
    },
  }
);

TypeScript SDK

Python SDK

REST API

Tools API — Composio TypeScript SDK Reference Guide

tools.get()

tools.execute()

ToolExecuteResponse

tools.getRawComposioTools()

tools.getRawComposioToolBySlug()

tools.proxyExecute()

Modifiers

Examples

Build docs developers (and LLMs) love

TypeScript SDK

Python SDK

REST API

Documentation Index

​tools.get()

​tools.execute()

​ToolExecuteResponse

​tools.getRawComposioTools()

​tools.getRawComposioToolBySlug()

​tools.proxyExecute()

​Modifiers

​Examples

Build docs developers (and LLMs) love

tools.get()

tools.execute()

ToolExecuteResponse

tools.getRawComposioTools()

tools.getRawComposioToolBySlug()

tools.proxyExecute()

Modifiers

Examples