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

# Tools

> Let the agent look things up and take actions during the call through your HTTPS endpoints.

A tool is an HTTPS endpoint of yours that the agent can call mid-conversation, with arguments it collects from the caller. Use tools to look up an order, check availability, book a meeting, open a ticket or update your CRM. The endpoint can be your own server, or a Zapier, Make or n8n webhook.

Set them up on the editor's **Tools** tab.

## Built-in: End call

**End call** (on by default) lets the agent hang up once it has said goodbye, or when the caller asks to end the call. The call ends after the goodbye has finished playing, and the caller sees *Call ended*.

## Add a custom tool

Click **Add tool** and fill in:

| Field | Description |
| - | - |
| **Function name** | What the agent calls it, such as `get_order_status`. Letters, numbers, `_` and `-`, up to 64 characters. Unique per agent, and not `end_call`. |
| **Endpoint (POST)** | Your URL. Must start with `https://`. |
| **When to use it** | A description the agent reads to decide when to call the tool. Up to 1,000 characters. |
| **Parameters (JSON Schema)** | The arguments to collect, as a JSON Schema object (`{ "type": "object", … }`). |
| **Headers** (optional) | Sent with every request, one per line as `Name: value`, such as your endpoint's auth. Up to 10. |

An agent can have up to **20** custom tools.

### Example

**Function name:** `get_order_status`

**When to use it:** Look up an order's delivery status by its order number.

**Parameters:**

```json theme={null}
{
  "type": "object",
  "properties": {
    "order_number": {
      "type": "string",
      "description": "The order number, e.g. A1234"
    }
  },
  "required": ["order_number"]
}
```

**Headers:**

```text theme={null}
Authorization: Bearer your-endpoint-token
```

> [!TIP]
>
> Write clear descriptions for the tool and for each parameter: the agent relies on them. Mention the tool in your prompt too, such as *Before answering delivery questions, look up the order with get\_order\_status*.

## What your endpoint receives

When the agent uses a tool, we send a `POST` to its endpoint with a JSON body:

```json theme={null}
{
  "tool": "get_order_status",
  "arguments": { "order_number": "A1234" },
  "call": { "id": "8b0c6c5e-…", "agentId": "3f1e2d4a-…" }
}
```

| Field | Description |
| - | - |
| `tool` | The function name |
| `arguments` | The arguments the agent collected, matching your JSON Schema |
| `call.id` | The call's ID. It matches the post-call webhook and the dashboard's **Calls** tab. |
| `call.agentId` | The voice agent's ID |

Headers: `Content-Type: application/json`, the headers you set, and the [signature headers](https://docs.talking-avatar.dev/api-reference/verify-signatures.md) `webhook-id`, `webhook-timestamp` and `webhook-signature`. Your own headers can't override the signature headers.

## What to send back

Reply within **10 seconds**. The response body, text or JSON, is what the agent learns, and the conversation carries on.

```json theme={null}
{ "status": "shipped", "carrier": "UPS", "eta": "Thursday" }
```

| Your response | What the agent gets |
| - | - |
| `2xx` with a body | The body (the first 8,000 characters) |
| `2xx` with an empty body | `Done.` |
| `4xx` or `5xx` | An error with the HTTP status and your response body, so it can tell the caller |
| No response within 10 seconds, or unreachable | An error telling it to say it can't do that right now |

> [!TIP]
>
> Keep responses short and to the point. Return only the facts the agent needs to say, in plain words or small JSON.

## Verify requests

Every tool request is signed with the agent's signing secret, so you can check it came from your agent. See [Verify signatures](https://docs.talking-avatar.dev/api-reference/verify-signatures.md).

```js Express theme={null}
import express from "express";
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.AGENT_SIGNING_SECRET); // whsec_…
const app = express();

app.post("/agent/orders", express.raw({ type: "application/json" }), async (req, res) => {
  let body;
  try {
    body = webhook.verify(req.body.toString(), req.headers); // throws if invalid or over 5 minutes old
  } catch {
    return res.status(401).send("Invalid signature");
  }
  const order = await findOrder(body.arguments.order_number);
  res.json(order ? { status: order.status, eta: order.eta } : { error: "No order with that number" });
});
```

## No-code endpoints

Point a tool at a Zapier **Catch Hook**, a Make **Custom webhook** or an n8n **Webhook** node, and finish the automation with a response step (for example n8n's **Respond to Webhook**) that returns what the agent should know. Keep the automation under 10 seconds.

## See tool calls

Each call on the **Calls** tab shows how many tool calls it made. The transcript shows what the agent said with the results.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.