Custom Tools

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

{
  "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"
    }
  }
}

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.

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.

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.

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:

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);
});

import { TrugenClient, ToolEvent } from '@trugen/sdk';

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

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

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

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.

Introduction

AI Teammates

Video Generation

API & Webhook

Configuration

Example

MCP

Configuration

Transport Types

Client Tools

Configuration

Implementing the Handler

Testing a Client Tool

What’s Next?

Integrations

Event Callbacks

​API & Webhook

​Configuration

​Example

​MCP

​Configuration

​Transport Types

​Client Tools

​Configuration

​Implementing the Handler

​Testing a Client Tool

​What’s Next?

Integrations

Event Callbacks

API & Webhook

Configuration

Example

MCP

Configuration

Transport Types

Client Tools

Configuration

Implementing the Handler

Testing a Client Tool

What’s Next?