Tools

← Back to API Reference

Webhook tools are functions the LLM can call during a conversation. When the LLM decides to invoke a tool, the platform sends an HTTP request to your endpoint and injects the response back as the tool result.

Two ways to assign tools to agents:

• Flow agents — set tool_ids per node in the flow. See Flow Nodes.
• Freeform agents — set tool_ids on the agent itself. Mention the tool in prompt to tell the LLM when to call it.

Pre-call tools (pre_call_tool_ids on the agent) fire automatically in parallel with the greeting — before any conversation starts. Use these to fetch caller context.

---

Contents

• List tools
• Get tool
• Create tool
• Update tool
• Delete tool
• Test tool
• Field reference
• How webhook calls work

---

GET /api/tools

List all webhook tools.

---

GET /api/tools/{tool_id}

Get a single tool.

---

POST /api/tools

Create a webhook tool.

{
  "name": "lookup_order",
  "description": "Look up an order by ID and return its current status and tracking info",
  "parameters": {
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order ID provided by the customer"
      }
    },
    "required": ["order_id"]
  },
  "webhook_url": "https://api.example.com/orders/lookup",
  "webhook_method": "POST",
  "headers": {
    "Authorization": "Bearer token123"
  },
  "timeout_secs": 10
}

---

PATCH /api/tools/{tool_id}

Update a tool. All fields except name are optional. To rename, delete and recreate.

---

DELETE /api/tools/{tool_id}

Delete a tool. First remove it from any agent tool_ids to avoid call failures.

---

POST /api/tools/{tool_id}/test

Test a tool by firing its webhook with sample arguments.

Request:

{
  "args": { "order_id": "ORD-12345" }
}

Response:

{
  "status_code": 200,
  "response": { "status": "shipped", "tracking": "TRK987654" },
  "duration_ms": 342,
  "error": null
}

error is null on success, or an error string (timeout, DNS failure, etc.) on failure.

---

Field Reference

Field	Required	Description
name	Yes	Unique function name the LLM sees. Use snake_case.
description	Yes	The LLM uses this to decide when to call the tool — be specific and action-oriented.
parameters	Yes	JSON Schema: { "properties": { ... }, "required": [...] }
webhook_url	Yes	Your server endpoint
webhook_method	No	POST (default) or GET
headers	No	Custom HTTP headers sent with every call (auth tokens, API keys, etc.)
timeout_secs	No	Request timeout in seconds (default: 10)

---

How Webhook Calls Work

When the LLM invokes a tool:

1. Platform sends a POST (or GET) to webhook_url
2. Request body is the tool arguments as JSON: { "order_id": "ORD-12345" }
3. Your endpoint returns any JSON object or plain string
4. The full response body is stringified and given to the LLM as the tool result
5. The LLM continues the conversation using that result

If the webhook times out or returns a non-2xx status, the LLM receives an error message and continues the conversation.

Example tool prompt instruction:

When the user provides their order number, call lookup_order with the order_id.
Tell the user the order status and tracking number from the result.