> ## 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.

# Tool call

> What we POST to a voice agent tool's endpoint, and what to send back.

When a voice agent uses one of its [tools](https://docs.talking-avatar.dev/voice-agents/tools.md), we send a `POST` to the tool's endpoint.

```http theme={null}
POST /agent/orders HTTP/1.1
Host: api.acme.com
Content-Type: application/json
Authorization: Bearer your-endpoint-token
webhook-id: msg_2b7f9c1e-…
webhook-timestamp: 1793010428
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

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

## Headers

| Header | Description |
| - | - |
| `Content-Type` | `application/json` |
| Your tool's headers | The headers you set on the tool, such as `Authorization` |
| `webhook-id` | A unique ID for this request |
| `webhook-timestamp` | When it was sent, in seconds since the epoch |
| `webhook-signature` | `v1,` followed by the signature. See [Verify signatures](https://docs.talking-avatar.dev/api-reference/verify-signatures.md). |

Headers you set that start with `webhook-` are dropped, so they can't stand in for the signature.

## Body

**tool** `string` *required*

The tool's function name.

**arguments** `object` *required*

The arguments the agent collected, shaped by the tool's JSON Schema. If the model's arguments aren't valid JSON, this is the raw string.

**call** `object` *required*

**properties**

**id** `string`

The call's ID. The same as `call.id` in the post-call webhook, and the **Call ID** in the dashboard.

**agentId** `string`

The voice agent's ID.

## Your response

Reply within **10 seconds**, with any content type. The body is what the agent learns:

| Response | The agent gets |
| - | - |
| `2xx` with a body | The body, up to its first 8,000 characters |
| `2xx` with an empty body | `Done.` |
| `4xx` or `5xx` | `{"error": "The tool failed (HTTP <status>).", "response": "<your body>"}` |
| Timeout or network error | An error telling it to say it can't do that right now |

The agent may call several tools at once; each is a separate request.


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