Tools
Letting the AI call an API during a call: defining tools, signed requests (your own API), unsigned requests and API keys (third-party APIs), tools that need the caller's confirmation, trying tools, how responses are handled, error types and idempotency.
Add tools to an agent and the AI can call an API mid-call and answer with the result: check free slots, look up a customer by phone number, make a booking.
There are two ways to call:
| Kind | sign |
For | What is sent |
|---|---|---|---|
| Signed | true (default) |
Your own API | A signed tool.call JSON, POSTed by voicast |
| Unsigned | false |
Third-party APIs | The arguments as they are (query string for GET, JSON body for POST) |
Both can carry an API key. voicast's servers make the call; the URL and API key are never given to the voice connection or the AI. The AI only gets the agent's tools and the connection actions listed by name in connectors.
In the dashboard, add tools under Tools in the agent settings, and press Try on a tool to call it once (Trying tools).
Defining tools#
"tools": [
{
"name": "find_free_slots",
"description": "予約の空きを調べる。相手が希望の日を言ったときに使う",
"url": "https://saas.example.com/voicast/tools",
"parameters": {
"properties": {
"date": { "type": "string", "description": "希望の日(YYYY-MM-DD)" },
"menu": { "type": "string", "enum": ["検診", "治療", "クリーニング"] }
},
"required": ["date"]
}
},
{
"name": "create_booking",
"description": "予約を入れる。空きを伝えて、相手が日時を選んだら使う",
"url": "https://saas.example.com/voicast/tools",
"confirm": true,
"parameters": {
"properties": {
"start": { "type": "string", "description": "開始の日時(ISO 8601)" },
"name": { "type": "string" },
"phone": { "type": "string" }
},
"required": ["start", "name"]
}
},
{
"name": "find_customer",
"description": "電話番号で顧客を探す。会話の最初に、かけてきた番号で使う",
"url": "https://api.example-crm.com/v1/customers/search",
"method": "GET",
"sign": false,
"auth": { "type": "api_key", "header": "Authorization", "value": "sk_live_…" },
"parameters": {
"properties": {
"phone": { "type": "string", "description": "電話番号(数字だけ)" }
},
"required": ["phone"]
}
}
]| Field | Required | Description |
|---|---|---|
name |
yes | Starts with a lowercase letter; lowercase letters, digits and _, up to 40 chars. Reserved names cannot be used. Must not clash with connection tool names |
description |
yes | When to use it (up to 500 chars). The AI reads this to decide |
url |
yes | Where to call. https with a public host name only (no literal IP addresses, localhost or internal names). Up to 500 chars |
method |
GET or POST. Default POST. Signed tools must use POST |
|
sign |
Default true (signed). false for unsigned requests |
|
auth |
Sends an API key: { "type": "api_key", "header": "…", "value": "…" } (see API keys) |
|
parameters |
Arguments (see Arguments) | |
confirm |
When true, voicast asks the caller with a fixed confirmation message before calling, and tells the result in a fixed message (Tools that need confirmation). Use it for tools that change data, such as bookings and cancellations |
|
confirm_message |
Confirmation message for a confirm tool (up to 200 characters). {argument name} inserts the value |
|
done_message |
Message said when a confirm tool succeeds (up to 200 characters). {argument name} can be inserted. An empty string "" says no completion message |
An agent can have up to 10 tools. Before using a tool, the AI tells the caller it is checking (
Arguments#
parameters are the values the AI collects in the conversation and passes to the tool. Up to 20 properties of type string, number, integer or boolean; enum up to 50 values. Arguments listed in required are required.
- Only the arguments you defined are sent. Values the AI adds under other names are dropped, and so are empty values (empty strings and
null). - If a required argument is missing, the API is not called and the AI gets
invalid_arguments. - For a name-reading argument (
name_kana, furigana and so on), the AI fills in the reading it heard without asking the caller: as thedescriptionsays if it specifies the script, otherwise full-width katakana (Name readings). Name arguments (nameand so on) still get the name as recognized.
Signed requests (your own API)#
With sign left out or true, voicast POSTs a signed request to the tool's url. You can receive every tool on one URL and switch on the tool name.
POST https://saas.example.com/voicast/tools
content-type: application/json
user-agent: voicast-tools/1
webhook-id: msg_6f1c…
webhook-timestamp: 1790000042
webhook-signature: v1,Rk9x…
idempotency-key: tc_7f3a9c2e…
{
"type": "tool.call",
"tool": "find_free_slots",
"tool_call_id": "tc_7f3a9c2e…",
"arguments": { "date": "2026-10-07" },
"call": {
"id": "call_…",
"channel": "phone",
"provider_call_id": "CA…",
"from": "+819012345678",
"tenant": { "id": "ten_…", "external_id": "clinic-123" }
}
}| Field | Description |
|---|---|
tool |
The tool name |
tool_call_id |
Unique per tool call. Same as the idempotency-key header |
arguments |
The arguments the AI chose (only the ones you defined) |
call.channel |
phone or web; test when trying a tool |
call.tenant.external_id |
Your customer ID, to pick the right booking calendar and so on. When trying a tool without tenant_id, call.tenant is null |
call.from |
The caller's number (phone calls where your TwiML passed from) |
test |
true only when trying a tool |
Tools with auth also carry the API key header.
Unsigned requests (third-party APIs)#
With sign: false, voicast sends the arguments as they are, without a signature or the tool.call envelope, so you can call a third-party REST API directly. Authenticate with an API key.
GET https://api.example-crm.com/v1/customers/search?phone=09012345678
accept: application/json
user-agent: voicast-tools/1
idempotency-key: tc_7f3a9c2e…
authorization: Bearer sk_live_…GETsends the arguments in the query string. A query already inurlis kept; an argument with the same name replaces its value.POSTsends the arguments as the JSON body (for example{ "phone": "09012345678" }).idempotency-keyis unique per tool call, as for signed requests.
API keys#
With auth, every request carries an API key in a header. Signed tools can have one too.
"auth": { "type": "api_key", "header": "X-API-Key", "value": "…" }- With the
Authorizationheader the key is sent asBearer <key>; with any other header (such asX-API-Key) it is sent as is. headeris up to 64 letters, digits and-. Headers with a fixed meaning, such asContent-Type,Host,Cookie,Idempotency-Keyandwebhook-signature, are not allowed.valueis 1 to 2,000 characters. On save it is taken out of the settings and stored encrypted, per agent and tool name. It is not kept in the agent's version history and is never returned by the API or the dashboard.- The agent's
tool_keyslists the stored keys:name(the tool name),hint(the last 4 characters; empty for keys shorter than 12 characters) andupdated_at. - On later saves you can leave
valueout to keep the stored key. Passvalueonly to change the key. - A stored key belongs to the tool name and the origin of its URL (
https://and the host name). After renaming a tool, changing its URL origin, or copying it to another agent, enter the key again. Saving a tool withauthand no key returns 422invalid_config. - Saving deletes the stored key of a tool whose URL origin changed or that was removed (changing only the path keeps the key).
- When you roll back to an earlier version (save its settings again), a tool with the same name and URL origin uses the key stored now.
- Deleting the agent deletes its stored keys.
- For APIs that need no authentication, leave
authout.
How responses are handled#
The body of a 2xx response goes to the AI.
{ "slots": ["2026-10-07T10:00:00+09:00", "2026-10-07T14:30:00+09:00"] }| Body | What the AI gets |
|---|---|
| JSON | As is |
| Not JSON (plain text and so on) | { "text": "…" } |
| Empty | {} |
| Over 4,000 characters | The first 4,000 characters as { "text": "…", "truncated": true } |
- voicast waits up to 8 seconds, then treats the call as failed.
- Redirects (3xx) are not followed (
upstream_error). - A body over 4,000 characters is cut and no longer reaches the AI as JSON. Return only what the AI needs.
- Return expected outcomes such as "no free slots" or "not found" as 2xx, e.g.
{ "slots": [] }or{ "found": false, "message": "その番号の方は見つかりませんでした" }, so the AI can say so naturally.
Ending the conversation from a tool response (end_call)#
Put end_call in the response JSON to end the conversation right away, saying the closing words once, without handing control back to the AI. Use it when the tool has already done the follow-up (for example, it has already notified a staff member) and the AI should not keep talking.
{ "found": false, "end_call": { "outcome": "handoff", "message": "I'm sorry, we couldn't find that name. A staff member is on the way, please wait a moment.", "reason": "Name not in the directory", "fields": { "visitor_name": "Suzuki" } } }| Field | Meaning |
|---|---|
outcome |
The result: completed, answered or handoff (default handoff) |
message |
The closing words (up to 200 characters). Omit it for the standard closing of the outcome |
reason |
Why the conversation ended, kept in the call record |
fields |
Collected fields (only those in the agent's fields are kept) |
It works for voice replies and text replies (output: "text").
Error types#
When a call fails, the AI gets one of these error values. It apologizes and, for example, offers a callback from staff.
| What happened | error |
|---|---|
| 401 or 403 | unauthorized (check the API key) |
| 404 | not_found |
| Any other non-2xx (3xx, 429, 5xx…) or no connection | upstream_error |
| No response within 8 seconds | timeout |
| A required argument is missing | invalid_arguments (the API is not called) |
A tool with auth has no stored API key |
missing_api_key (the API is not called) |
Verifying the signature#
Signed requests carry a Standard Webhooks signature. The steps and code (Node.js, Python, PHP, Go) are the same as in Results; only the secret differs.
The tools signing secret (whsec_…) is one per environment. Read it in the environment settings in the dashboard (admin or above), with GET /v1/tools/secret, or with the MCP tool get_tools_secret; rotate it there, with POST /v1/tools/secret/rotate, or with rotate_tools_secret. For 24 hours after a rotation, requests carry signatures with both the old and new secret, so you have time to switch (libraries accept both secrets).
import express from 'express';
import { Webhook } from 'standardwebhooks';
const wh = new Webhook(process.env.VOICAST_TOOLS_SECRET); // whsec_…
const app = express();
app.post('/voicast/tools', express.raw({ type: 'application/json' }), async (req, res) => {
let body;
try {
body = wh.verify(req.body, req.headers);
} catch {
return res.sendStatus(401);
}
const clinic = body.call.tenant.external_id;
switch (body.tool) {
case 'find_free_slots':
return res.json({ slots: await findSlots(clinic, body.arguments.date) });
case 'create_booking':
// Run each tool_call_id only once
return res.json(await createBookingOnce(body.tool_call_id, clinic, body.arguments));
default:
return res.status(404).json({ error: 'unknown tool' });
}
});The SDK's verifyToolCall verifies them too.
Requests sent when trying a tool carry the same signature as real calls and add "test": true to the body. Without tenant_id, call.tenant is null, so body.call.tenant.external_id in the example above cannot be read. When your server receives tests, check body.test and return a test response, or pass tenant_id in the test.
Idempotency#
During a call, voicast itself runs each tool_call_id only once and returns the earlier result for a repeat. Even so, tools that change data, such as booking, should run once on your side too if the same request arrives twice. Store the tool_call_id (the idempotency-key header) and return the earlier result for a repeated ID.
async function createBookingOnce(toolCallId, clinic, args) {
const done = await db.toolRuns.get(toolCallId);
if (done) return done.result;
const result = await createBooking(clinic, args);
await db.toolRuns.put(toolCallId, { result });
return result;
}Tools that need confirmation#
Tools with confirm: true are used after the caller agrees to a confirmation message, and the result is told in the message you set. Always set it on tools that create, change, cancel or register something. Read-only tools (checking slots, finding a customer) do not need it.
When the caller agrees, voicast says "Certainly. One moment, please." before the tool runs (in Japanese
Without done_message it is "That's been completed."; on failure it is "I'm sorry, your request has not been confirmed yet. A staff member will get back to you."
With an empty done_message ("done_message": ""), voicast says no completion message. Use it when only the message of end_call in the response should be said (for example, the tool notifies a staff member and closes with "A staff member is on the way, please wait a moment."). Without end_call, the AI tells the caller the result. The failure message does not change.
The confirmation message (confirm_message) and the completion message (done_message) can insert values with {argument name}.
{
"name": "create_booking",
"description": "Books an appointment after the caller picks a time",
"url": "https://saas.example.com/voicast/tools",
"confirm": true,
"confirm_message": "Shall I book {menu} for {name} on {start}?",
"done_message": "You're booked for {start}. We look forward to seeing you.",
"parameters": {
"properties": {
"start": { "type": "string", "description": "Start time (YYYY-MM-DDTHH:MM)" },
"menu": { "type": "string", "enum": ["checkup", "treatment", "cleaning"] },
"name": { "type": "string" }
},
"required": ["start", "name"]
}
}- Date and time values (
YYYY-MM-DDTHH:MMsuch as2026-10-19T14:00, a dateYYYY-MM-DD, or with a time zone offset) are inserted as spoken dates ("Monday, October 19 at 2 p.m."). - Name arguments (
name,…_name) are inserted as the reading when the tool has a reading argument (name_kanaand so on); in Japanese the reading is said in hiragana. - A name that is not an argument is rejected with 422
invalid_configwhen saving. Arguments without a value become empty. - Without
confirm_message, the confirmation is a default message made from the argument values (ID arguments…_id, phone numbers and readings are left out). - voicast speaks these messages in the conversation's language (Japanese, English, Chinese or Korean).
confirm_messageanddone_messageare used only in conversations in the language they are written in; other conversations use the default messages. - When nothing could be changed (for example, the slot was just taken), return 2xx with
{ "ok": false, "message": "That time is no longer available" }or{ "error": "slot_taken", "message": "…" }, or a 4xx. Unless a 2xx body hasok: falseor anerror, voicast tells the caller it is done. Withok: falseor anerror, voicast says only "I'm sorry, your request has not been confirmed yet." and the AI explains why and offers another time.
When trying a tool, confirm tools are called without asking.
Trying tools#
Call a tool once and see what it returns. It runs exactly as when the AI calls it during a call (same signature, API key and 8-second limit).
- Dashboard: under Tools in the agent settings, press Try on a tool; in the Try tool dialog, enter the arguments and call it. It uses what is in the form, even before you save. Results shows success or failure, the status code, the elapsed time and the body. Developers, admins and owners can use it.
- API:
POST /v1/tools/try(see the API reference) - MCP:
try_tool(see MCP) - SDK:
tools.try()(see SDK)
curl https://api.voicast.jp/v1/tools/try \
-H "Authorization: Bearer $VOICAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "agt_…", "tool": "find_free_slots", "arguments": { "date": "2026-10-07" }, "tenant_id": "ten_…" }'{
"tool": "find_free_slots",
"ok": true,
"result": { "slots": ["2026-10-07T10:00:00+09:00"] },
"status": 200,
"body": "{\"slots\":[\"2026-10-07T10:00:00+09:00\"]}",
"truncated": false,
"duration_ms": 182
}toolis the name of a saved tool (requiresagent_id) or an unsaved tool definition (same shape as an entry intools). The stored key is used only when you pass a saved tool by name. With a definition, put the API key inauth.value(a tool withauthand novaluereturns 422missing_api_key).- There is no conversation charge and nothing is recorded as a call.
confirmtools are called without asking. Tools that change data (such as booking) really change it.- Signed requests carry
"test": true,call.channelistestandcall.idistry_…. Withouttenant_id,call.tenantisnull. - Signed tools are sent with the same signature as real calls, even when trying them; the signature alone does not tell a try from a real call. APIs that write data should check
test: truein the body (call.channelistest) and return without writing, or refuse. - Up to 30 tries per minute per environment. Beyond that you get 429
rate_limitedwithRetry-After.
Good practice#
- The AI never answers beyond what a tool returned. Put anything it should say (prices, directions) in the response or in the agent's
faq. - Return only the personal data the AI needs (for example, not a full date of birth).
- On URLs called by signed tools, do nothing until the signature is verified. Reject unsigned requests and stale
webhook-timestampvalues. - Give third-party API keys only the permissions the tool needs (a read-only key for read-only tools).