Custom Tools API

Custom tools allow you to extend Composio with your own implementations while keeping a consistent interface with built-in tools. Custom tools can be standalone or integrate with existing toolkits for authentication.

Creating Custom Tools

createCustomTool()

Create a custom tool with your own execution 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 (shown to AI models)

inputParams

ZodSchema

required

Zod schema for input validation

execute

function

required

Async function that executes the tool

toolkitSlug

string

Associate with a toolkit for authentication

userId

string

User ID (required if toolkitSlug is provided)

connectedAccountId

string

Specific connected account to use

Examples

Simple Custom Tool
With Toolkit Integration
Database Query Tool
API Wrapper Tool

import { z } from 'zod';

const weatherTool = await composio.tools.createCustomTool({
  name: 'Get Weather',
  slug: 'GET_WEATHER',
  description: 'Get current weather for a city',
  inputParams: z.object({
    city: z.string().describe('City name'),
    units: z.enum(['celsius', 'fahrenheit']).optional().describe('Temperature units')
  }),
  execute: async (input) => {
    // Your custom logic
    const response = await fetch(
      `https://api.weather.com/v1/current?city=${input.city}&units=${input.units || 'celsius'}`
    );
    const data = await response.json();

    return {
      data: {
        temperature: data.temp,
        condition: data.condition,
        humidity: data.humidity
      },
      error: null,
      successful: true
    };
  }
});

// Use with any provider
const tools = await composio.tools.get('default', {
  tools: ['GET_WEATHER']
});

import { z } from 'zod';

// Create a custom tool that uses GitHub authentication
const advancedSearchTool = await composio.tools.createCustomTool({
  name: 'GitHub Advanced Search',
  slug: 'GITHUB_ADVANCED_SEARCH',
  description: 'Search GitHub repositories with advanced filters',
  toolkitSlug: 'github', // Use GitHub auth
  userId: 'user_123',
  inputParams: z.object({
    query: z.string().describe('Search query'),
    language: z.string().optional().describe('Programming language'),
    minStars: z.number().optional().describe('Minimum stars')
  }),
  execute: async (input, connectionConfig, executeToolRequest) => {
    // executeToolRequest makes authenticated API calls
    const searchQuery = [
      input.query,
      input.language ? `language:${input.language}` : '',
      input.minStars ? `stars:>=${input.minStars}` : ''
    ].filter(Boolean).join(' ');

    const result = await executeToolRequest({
      endpoint: '/search/repositories',
      method: 'GET',
      parameters: [
        { name: 'q', in: 'query', value: searchQuery },
        { name: 'sort', in: 'query', value: 'stars' },
        { name: 'order', in: 'query', value: 'desc' }
      ]
    });

    return result;
  }
});

import { z } from 'zod';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL
});

const dbQueryTool = await composio.tools.createCustomTool({
  name: 'Database Query',
  slug: 'DB_QUERY',
  description: 'Execute a read-only database query',
  inputParams: z.object({
    table: z.string().describe('Table name'),
    columns: z.array(z.string()).describe('Columns to select'),
    where: z.record(z.unknown()).optional().describe('WHERE conditions')
  }),
  execute: async (input) => {
    try {
      const columns = input.columns.join(', ');
      let query = `SELECT ${columns} FROM ${input.table}`;
      const values: unknown[] = [];

      if (input.where) {
        const conditions = Object.entries(input.where)
          .map(([key, _], i) => `${key} = $${i + 1}`)
          .join(' AND ');
        query += ` WHERE ${conditions}`;
        values.push(...Object.values(input.where));
      }

      const result = await pool.query(query, values);

      return {
        data: {
          rows: result.rows,
          count: result.rowCount
        },
        error: null,
        successful: true
      };
    } catch (error) {
      return {
        data: {},
        error: error instanceof Error ? error.message : 'Unknown error',
        successful: false
      };
    }
  }
});

import { z } from 'zod';

const cryptoPriceTool = await composio.tools.createCustomTool({
  name: 'Get Crypto Price',
  slug: 'GET_CRYPTO_PRICE',
  description: 'Get current cryptocurrency price',
  inputParams: z.object({
    symbol: z.string().describe('Crypto symbol (e.g., BTC, ETH)'),
    currency: z.string().default('USD').describe('Target currency')
  }),
  execute: async (input) => {
    const response = await fetch(
      `https://api.coingecko.com/api/v3/simple/price?ids=${input.symbol}&vs_currencies=${input.currency}`
    );

    if (!response.ok) {
      return {
        data: {},
        error: 'Failed to fetch crypto price',
        successful: false
      };
    }

    const data = await response.json();

    return {
      data: {
        symbol: input.symbol,
        price: data[input.symbol.toLowerCase()]?.[input.currency.toLowerCase()],
        currency: input.currency,
        timestamp: new Date().toISOString()
      },
      error: null,
      successful: true
    };
  }
});

Execute Function Signature

The execute function receives three parameters:

execute: async (
  input: T, // Parsed and validated input
  connectionConfig: ConnectionData | null, // Auth credentials (if toolkitSlug provided)
  executeToolRequest: (data: ToolProxyParams) => Promise<ToolExecuteResponse> // Make authenticated API calls
) => Promise<ToolExecuteResponse>

Input Parameter

Parsed and validated input matching your Zod schema:

const input = {
  city: 'New York',
  units: 'celsius'
};

Connection Config

Auth credentials when toolkitSlug is provided:

const connectionConfig = {
  access_token: 'ghp_...',
  token_type: 'Bearer',
  // ... other auth fields
};

Execute Tool Request

Make authenticated API calls to the toolkit:

const result = await executeToolRequest({
  endpoint: '/repos/owner/repo/issues',
  method: 'POST',
  body: {
    title: 'Issue title',
    body: 'Issue description'
  },
  parameters: [
    { name: 'state', in: 'query', value: 'open' }
  ]
});

data

ToolProxyParams

required

Show properties

endpoint

string

required

API endpoint path

method

string

required

HTTP method: GET, POST, PUT, DELETE, etc.

body

Record<string, unknown>

Request body

parameters

Parameter[]

Query or header parameters

Return Value

The execute function must return a ToolExecuteResponse:

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

Using Custom Tools

Once created, custom tools work like any built-in tool:

// Get the custom tool wrapped for your provider
const tools = await composio.tools.get('default', {
  tools: ['GET_WEATHER', 'GITHUB_ADVANCED_SEARCH']
});

// Execute directly
const result = await composio.tools.execute('GET_WEATHER', {
  userId: 'default',
  arguments: {
    city: 'San Francisco',
    units: 'fahrenheit'
  }
});

console.log(result.data);

Best Practices

Clear Descriptions: Write clear tool descriptions for AI models
Input Validation: Use Zod for robust input validation
Error Handling: Return proper error messages in the response
Type Safety: Use TypeScript for type-safe implementations
Idempotency: Make tools idempotent when possible
Rate Limiting: Handle rate limits in your implementation
Logging: Log errors for debugging

Limitations

Custom tools are stored in-memory (not persisted)
Re-create custom tools on each SDK initialization
Cannot use executeToolRequest without toolkitSlug
Custom tools require manual version management

Next Steps

Tools API

Learn about built-in tools

Toolkits

Browse available toolkits

Connected Accounts

Set up authentication

Providers

Choose your AI framework

Overview

Core API

Providers

Advanced

Creating Custom Tools

createCustomTool()

Examples

Execute Function Signature

Input Parameter

Connection Config

Execute Tool Request

Return Value

Using Custom Tools

Best Practices

Limitations

Next Steps

Tools API

Toolkits

Connected Accounts

Providers

Build docs developers (and LLMs) love

Overview

Core API

Providers

Advanced

​Creating Custom Tools

​createCustomTool()

​Examples

​Execute Function Signature

​Input Parameter

​Connection Config

​Execute Tool Request

​Return Value

​Using Custom Tools

​Best Practices

​Limitations

​Next Steps

Tools API

Toolkits

Connected Accounts

Providers

Build docs developers (and LLMs) love

Creating Custom Tools

createCustomTool()

Examples

Execute Function Signature

Input Parameter

Connection Config

Execute Tool Request

Return Value

Using Custom Tools

Best Practices

Limitations

Next Steps