Custom tools · Documentation

In addition to built-in tools provided by the system, you can add custom tools. Custom tools communicate with external systems using the MCP or HTTP protocol. Custom tools significantly extend the capabilities of AI agents, allowing users to complete complex business workflows during conversations.

Custom tool fields

Fields required to create a custom HTTP tool:

Field	What it is
Status	When disabled, no AI agent can call this tool even if authorized.
Name	The function name sent to the model. Up to 64 characters, must match `[a-zA-Z_][a-zA-Z0-9_]*` (no spaces), for example `get_order_status`.
Description	Up to 500 characters. The model reads this to decide when to call the tool — describe the use case, not the implementation.
Input Schema (JSON)	A JSON Schema (draft-07) describing the arguments the tool accepts. Add your parameters under `properties`.
Endpoint URL	The HTTPS URL the system calls when the AI invokes this tool.
Method	`POST` or `GET`. Defaults to `POST`.
Timeout (ms)	How long to wait for your endpoint, between 1000 and 30000 milliseconds. Defaults to 10000.
Headers (JSON)	Optional custom HTTP headers as a JSON object, such as an `Authorization` header.

Input Schema and Headers must be valid JSON

Both fields must contain a valid JSON object. If either fails to parse, saving is blocked.

Example: order status lookup

The following example creates a tool that lets an AI agent look up the current status of a customer's order. The agent calls it whenever a user asks about order progress.

Field	Value
Name	get_order_status
Description	Look up the current shipping status and tracking number of an order. Use this when the user asks about their order progress or delivery.
Endpoint URL	https://api.example.com/tools/order-status
Method	POST
Timeout	5000 ms
Headers	{"Authorization": "Bearer YOUR_SECRET_TOKEN"}

Input Schema — describes the arguments the AI will extract from the conversation and pass to your endpoint:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order ID to query, e.g. ORD-20240101-001"
    }
  },
  "required": ["order_id"]
}

Request sent to your endpoint — the system POSTs the extracted arguments as a JSON body:

POST https://api.example.com/tools/order-status
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json

{
  "order_id": "ORD-20240101-001"
}

Expected response — your endpoint must return HTTP 200 with a JSON body. The AI reads this as the tool result and uses it to compose a reply:

{
  "status": "shipped",
  "tracking_number": "SF1234567890",
  "estimated_delivery": "2024-01-05",
  "carrier": "SF Express"
}

Disabling and deleting

Setting a tool to Disabledstops all AI agents from calling it without touching any agent's configuration — useful while fixing or rotating an endpoint. Deleting a tool removes it entirely; agents that had it authorized lose access on their next message, while conversations already in progress are not interrupted.