# Setting up agent tools

> How to add tools (APIs the AI calls during a call, on your side or a third party's) to an agent in the dashboard and try them before saving, plus viewing and rotating the signing secret.

Source: https://voicast.jp/en/docs/dashboard-agent-tools

A tool is an API the AI calls during a call, for example to check open slots or look up a customer. Set tools up under **Tools** on the agent's page, with the developer role or above. For how tools work and how to build your API, see [Tools](https://voicast.jp/en/docs/tools.md).

## Add a tool

1. Under **Tools** on the agent's page, press **+ Add tool** (up to 10).
2. Fill in the settings below.
3. Press **Save as v…** at the bottom of the page.

| Setting | What |
| --- | --- |
| Tool name | Up to 40 lowercase letters, digits and `_`, starting with a letter |
| Description | What the tool does and when to use it. The AI uses this to decide whether to call it (up to 500 characters) |
| URL | A URL starting with `https` |
| Method | GET or POST |
| Sign requests | Adds the voicast signature (Standard Webhooks) and POSTs the tool name, arguments and call details as JSON. Use for your own API |
| Authentication | None or an API key. The API key goes in Authorization (Bearer) or another header |
| Arguments | Values the AI takes from the conversation: name, description, required (up to 20) |
| Confirm before use | Reads out what will happen and gets the caller's consent first. Use for tools that change data, such as booking or canceling |
| Confirmation and completion messages | What is read out when confirming (up to 200 characters). Insert values with `{argument name}` |
| No lead-in | Only the `say` text from the tool's response is spoken |
| Include the caller's words | Adds what the caller just said (up to 5 utterances) as `heard` in the request body (signed requests only) |

API keys are stored encrypted and not shown after saving. They are not kept in agent versions. Enter one only when changing it.

## Try a tool

You can call a tool once with the form's current content, even before saving.

1. Press **Try** on the tool.
2. Enter argument values and press **Try**.
3. Check the result (success or failure, status code, elapsed time, body).

Trying a tool isn't charged and isn't kept in the call history. Tools that change data really change it. If the API doesn't respond within 8 seconds, the call times out.

## View the signing secret

Signed tool requests are signed with a secret per environment. Your server uses it to verify `webhook-signature` ([Tools](https://voicast.jp/en/docs/tools.md#verifying-the-signature)). Requires the admin role or above.

1. Open **Environment settings** in the left menu.
2. Under **Tools signing secret**, press **Show** to see the value, or **Copy** to copy it.

## Rotate the signing secret

Rotate the secret if it may have leaked.

1. Press **Rotate secret** under **Tools signing secret**.
2. Press **Rotate secret** in the confirmation dialog.

For 24 hours after rotating, requests are also signed with the previous secret. Switch your server to the new secret within that time.

The live and test environments have separate secrets.
