Tools

Creating custom tools

Learn how to extend Composio's toolkits with your own tools

Custom tools allow you to create your own tools that can be used with Composio.

  1. Standalone tools - Simple tools that don’t require any authentication
  2. Toolkit-based tools - Tools that require authentication and can use toolkit credentials

Creating a Custom Tool

Standalone Tool

A standalone tool is the simplest form of custom tool. It only requires input parameters and an execute function:

1from pydantic import BaseModel, Field
2
3from composio import Composio
4from composio.types import ExecuteRequestFn
5
6composio = Composio()
7
8
9class AddTwoNumbersInput(BaseModel):
10    a: int = Field(
11        ...,
12        description="The first number to add",
13    )
14    b: int = Field(
15        ...,
16        description="The second number to add",
17    )
18
19# function name will be used as slug
20@composio.tools.custom_tool
21def add_two_numbers(request: AddTwoNumbersInput) -> int:
22    """Add two numbers."""
23    return request.a + request.b

Toolkit-based Tool

A toolkit-based tool has access to two ways of making authenticated requests:

  1. Using executeToolRequest - The recommended way to make authenticated requests to the toolkit’s API endpoints. Composio automatically handles credential injection and baseURL resolution:
1class GetIssueInfoInput(BaseModel):
2    issue_number: int = Field(
3        ...,
4        description="The number of the issue to get information about",
5    )
6
7# function name will be used as slug
8@composio.tools.custom_tool(toolkit="github")
9def get_issue_info(
10    request: GetIssueInfoInput,
11    execute_request: ExecuteRequestFn,
12    auth_credentials: dict,
13) -> dict:
14    """Get information about a GitHub issue."""
15    response = execute_request(
16        endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
17        method="GET",
18        parameters=[
19            {
20                "name": "Accept",
21                "value": "application/vnd.github.v3+json",
22                "type": "header",
23            },
24            {
25                "name": "Authorization",
26                "value": f"Bearer {auth_credentials['access_token']}",
27                "type": "header",
28            },
29        ],
30    )
31    return {"data": response.data}
  1. Using connectionConfig - For making direct API calls when needed:
1import requests
2
3@composio.tools.custom_tool(toolkit="github")
4def get_issue_info_direct(
5    request: GetIssueInfoInput,
6    execute_request: ExecuteRequestFn,
7    auth_credentials: dict,
8) -> dict:
9    """Get information about a GitHub issue."""
10    response = requests.get(
11        f"https://api.github.com/repos/composiohq/composio/issues/{request.issue_number}",
12        headers={
13            "Accept": "application/vnd.github.v3+json",
14            "Authorization": f"Bearer {auth_credentials['access_token']}",
15        },
16    )
17    return {"data": response.json()}

Using Custom Headers and Query Parameters

You can add custom headers and query parameters to your toolkit-based tools using the parameters option in executeToolRequest:

1@composio.tools.custom_tool(toolkit="github")
2def get_issue_info(
3    request: GetIssueInfoInput,
4    execute_request: ExecuteRequestFn,
5    auth_credentials: dict,
6) -> dict:
7    """Get information about a GitHub issue."""
8    response = execute_request(
9        endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
10        method="GET",
11        parameters=[
12            {
13                "name": "Accept",
14                "value": "application/vnd.github.v3+json",
15                "type": "header",
16            },
17            {
18                "name": "Authorization",
19                "value": f"Bearer {auth_credentials['access_token']}",
20                "type": "header",
21            },
22            {
23                "name": 'X-Custom-Header',
24                "value": 'custom-value',
25                "type": 'header',
26            },
27        ],
28    )
29    return {"data": response.data}

Executing Custom Tools

You can execute custom tools just like any other tool:

1response = composio.tools.execute(
2    user_id="default",
3    slug="TOOL_SLUG", # For the tool above you can use `get_issue_info.slug`
4    arguments={"issue_number": 1},
5)

Best Practices

  1. Use descriptive names and slugs for your tools
  2. Always provide descriptions for input parameters using describe()
  3. Handle errors gracefully in your execute function
  4. For toolkit-based tools:
    • Prefer executeToolRequest over direct API calls when possible
    • Use relative paths with executeToolRequest - Composio will automatically inject the correct baseURL
    • Use the parameters option to add custom headers or query parameters: 
      1parameters: [
      2  { name: 'page', value: '1', in: 'query' }, // Adds ?page=1 to URL
      3  { name: 'x-custom', value: 'value', in: 'header' }, // Adds header
      4];
    • Remember that executeToolRequest can only call tools from the same toolkit
    • Use executeToolRequest to leverage Composio’s automatic credential handling
    • Only use connectionConfig when you need to make direct API calls or interact with different services
  5. Chain multiple toolkit operations using executeToolRequest for better maintainability

Limitations

  1. Custom tools are stored in memory and are not persisted
  2. They need to be recreated when the application restarts
  3. Toolkit-based tools require a valid connected account with the specified toolkit
  4. executeToolRequest can only execute tools from the same toolkit that the custom tool belongs to
  5. Each toolkit-based tool can only use one connected account at a time