> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trugen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Tools

> Build API, MCP, and client-side tools to extend your agent with custom actions and integrations.

Custom tools let you connect your agent to any system not covered by a pre-built integration. TruGen supports three types of custom tools — choose based on where the action happens and how your system communicates.

***

## API & Webhook

Call any external HTTP endpoint during a conversation. The agent uses function calling to decide when the tool is relevant, fires the request, and incorporates the response into its reply.

### Configuration

| Field               | Required | Description                                                                                                                              |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Tool Name**       | Yes      | Internal identifier used by the LLM (e.g., `getUserData`, `sendNotification`). Use camelCase with no spaces.                             |
| **Description**     | Yes      | Explains what the tool does and when to use it. The clearer this is, the better the agent will know when to invoke it.                   |
| **Request URL**     | Yes      | The full endpoint URL the request will be sent to (e.g., `https://api.example.com/users`).                                               |
| **HTTP Method**     | Yes      | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.                                                                                              |
| **Request Headers** | No       | Custom headers such as `Authorization`, `Content-Type`, or any other headers your endpoint requires.                                     |
| **Parameters**      | No       | The inputs the tool accepts. Define each as a named property with a type and description — the agent uses these to populate the request. |
| **Messages**        | No       | Status messages shown at different stages of tool execution (e.g., a message while the request is in flight, or on success/failure).     |

### Example

```json theme={null}
{
  "name": "getOrderStatus",
  "description": "Use this tool when the user asks about the status of their order. Requires the order ID.",
  "url": "https://api.yourstore.com/orders/{orderId}/status",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
  "parameters": {
    "orderId": {
      "type": "string",
      "description": "The unique identifier for the customer's order"
    }
  }
}
```

<Tip>Write your **Description** as if you're telling a smart colleague exactly when to pick up this tool. Specificity matters — vague descriptions lead to missed or incorrect invocations.</Tip>

***

## MCP

Connect your own **Model Context Protocol** server to give the agent access to tools via a standardised interface. Use this if you already run an MCP-compatible server or want a protocol-native integration.

### Configuration

| Field               | Required | Description                                                                        |
| ------------------- | -------- | ---------------------------------------------------------------------------------- |
| **Tool Name**       | Yes      | Name used to identify this MCP connection internally.                              |
| **Description**     | Yes      | What this MCP server provides — used to help the agent understand when to call it. |
| **Server URL**      | Yes      | The base URL of your MCP server (e.g., `https://mcp.yourcompany.com`).             |
| **Transport Type**  | Yes      | How the client communicates with the server — see below.                           |
| **Request Headers** | No       | Auth headers or any custom headers your MCP server requires.                       |

### Transport Types

| Type                         | When to Use                                                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Streamable HTTP (SHTTP)**  | Standard HTTP-based streaming. Best for most deployments — simpler infrastructure with support for streamed responses. |
| **Server-Sent Events (SSE)** | Event-driven, long-lived connection. Best when your server pushes updates to the client in real time.                  |

<Note>Your MCP server must be publicly reachable from TruGen's infrastructure. If it's behind a private network, expose it via a secure tunnel or deploy it to a public endpoint first.</Note>

***

## Client Tools

Client tools execute inside your **frontend application** at runtime — not on a server. Use them to trigger UI actions during a conversation, such as opening a modal, navigating to a page, or updating an on-screen element.

Client tools are defined in the Developer Studio and implemented as matching handlers in your npm package integration.

### Configuration

| Field           | Required | Description                                                                                    |
| --------------- | -------- | ---------------------------------------------------------------------------------------------- |
| **Tool Name**   | Yes      | Must match the handler name in your npm package (e.g., `openHelpPanel`, `navigateToCheckout`). |
| **Description** | Yes      | Describes what the client action does — the agent uses this to decide when to trigger it.      |
| **Parameters**  | No       | Inputs the tool passes to your client handler (e.g., `{ "panelId": "billing" }`).              |
| **Messages**    | No       | Messages for different lifecycle stages of the tool — invocation, completion, or error.        |

### Implementing the Handler

After defining a client tool in the studio, implement the matching handler in your npm package:

<CodeGroup>
  ```js JavaScript theme={null}
  import { TrugenClient } from '@trugen/sdk';

  const client = new TrugenClient({ agentId: 'YOUR_AGENT_ID' });

  client.on('tool:openHelpPanel', (params) => {
    // params contains whatever the agent passed
    openPanel(params.panelId);
  });
  ```

  ```ts TypeScript theme={null}
  import { TrugenClient, ToolEvent } from '@trugen/sdk';

  const client = new TrugenClient({ agentId: 'YOUR_AGENT_ID' });

  client.on('tool:openHelpPanel', (params: { panelId: string }) => {
    openPanel(params.panelId);
  });
  ```
</CodeGroup>

<Note>The tool name defined in the studio must exactly match the event name used in your handler — including casing.</Note>

### Testing a Client Tool

Use the **Test** button in the Developer Studio to fire the tool with sample inputs and verify the handler receives and processes them correctly before going live.

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Integrations" icon="plug" href="/docs/agents/tools/integrations">
    Connect 1,000+ apps via Composio without writing API code.
  </Card>

  <Card title="Event Callbacks" icon="webhook" href="/docs/agents/callback">
    Receive real-time webhook events from active conversations.
  </Card>
</CardGroup>