# Function Calling in Live Calls: Designing In-Call Tools

> How to design tools a phone AI calls mid-conversation: names and descriptions, reads vs writes, wait time, returning failures, and securing the endpoint.

Published: 2026-11-07
Source: https://voicast.jp/en/blog/voice-ai-function-calling

## Key points

- The model decides when to call a tool from its description, so say plainly when to use it and when not to.
- Callers can't see a spinner, so keep tool responses fast and return only the fields the AI needs to say out loud.
- Read back and get a yes before any write (booking, cancelling), and make writes idempotent so a repeated call does the work once.

To let a voice AI hit your API mid-call, you give it tools (function calling). The model reads each tool's description, decides whether to use it, fills in the arguments, and the platform makes the HTTP request and hands the result back. On a phone call the caller is waiting in silence while this happens, so good tool design covers more than the schema: response time, how failures come back, and confirmation before anything that changes data.

## How a tool call plays out

A tool is an entry in a list of operations the AI is allowed to trigger. One call goes like this:

1. The caller says, "Do you have anything next Tuesday?"
2. The model reads the tool descriptions, picks the availability tool and builds arguments (the date).
3. The platform calls the tool's URL. Meanwhile the AI says something like "Let me check that for you."
4. Your API returns JSON.
5. The model turns it into speech: "Tuesday has 10 a.m. and 2 p.m. open."

The model never makes the HTTP request itself. It only chooses which tool and which arguments. That's why URLs and credentials stay out of the prompt.

## Names and descriptions

Whether the model uses a tool comes down mostly to the description. Describe what it does, when to use it, and when not to.

| Field | Weak | Better |
|---|---|---|
| Name | `api1` | `find_free_slots` |
| Description | Booking API | Finds open appointment times. Use when the caller asks about availability on a day or date. Don't use it to book. |
| Parameter description | date | Day to search (YYYY-MM-DD). Convert phrases like "next Tuesday" to a date. |

Keep parameters few and strictly typed. When the valid values are a short list (morning/afternoon), use an enum so the model can't invent one.

Keep the tool count down, too. Several near-identical tools make the model hesitate or pick the wrong one. One tool per operation: find slots, create booking, cancel booking.

## Separate reads from writes

Split tools into reads (find slots, look up a customer) and writes (create, change, cancel).

- **Reads** are cheap to get wrong. Let the model call them on its own judgment.
- **Writes** need a read-back and an explicit yes first. A misheard date that turns into a real booking costs far more to undo than it does to confirm.

Make writes idempotent: the same request arriving twice should produce one booking. Models sometimes repeat a call after the caller corrects themselves, and a request that timed out on the platform side may still have completed on yours. Derive an idempotency key from the call ID plus the arguments and you won't double-book.

## Handling wait time

A caller can't see a loading indicator. A few seconds of dead air and they start wondering whether the line dropped. Faster is always better, and the easiest wins come from doing less in the request:

- Move slow work (reporting, notifications, syncing other systems) to post-call webhooks.
- Return only the fields the AI needs to speak. A long payload takes the model longer to read, too.
- Trim lists to what works on a phone call, two or three options rather than twenty.

Every platform has a timeout, and a timeout counts as a failure, so design to answer well inside it. For the bigger picture, see [voice AI latency](https://voicast.jp/en/blog/voice-ai-latency).

## Returning failures

Distinguish "no result" from "something broke."

| Situation | Return | What the AI does |
|---|---|---|
| No open slots | 2xx with `{ "slots": [], "message": "No openings that day" }` | Suggests another day |
| Customer not found | 2xx with `{ "found": false }` | Asks again or treats them as new |
| Booking system down | 5xx | Apologizes and offers a callback |

If you return a 5xx for a perfectly valid "nothing found," the model reads it as an error and can't move the conversation forward.

## Securing the endpoint

Your tool URL is reachable from the internet, so:

1. **Verify the signature.** Only accept requests from the platform; see [verifying Standard Webhooks signatures](https://voicast.jp/en/blog/standard-webhooks-signature-verification).
2. **Never take the tenant from the arguments.** Decide whose data you're touching from the signed tenant ID in the request body. If the tenant were a model-generated argument, a caller could talk the AI into querying another customer's data.
3. **Return as little as possible.** Anything you give the model may be spoken aloud. Return "verified: true", not the stored date of birth.

More on this in [securing in-call tools](https://voicast.jp/en/blog/voice-ai-tool-security).

## Doing this with voicast

In voicast you list up to 10 tools under `tools` in the agent settings. When the AI decides to use one, voicast POSTs to its `url` and waits up to 8 seconds, saying "let me check" in the meantime. A 2xx with JSON goes straight to the AI; anything else, or a timeout, is reported as a failure, and the AI apologizes and offers a callback from staff.

```json
{
  "tools": [
    {
      "name": "find_free_slots",
      "description": "Finds open appointment times. Use when the caller asks about availability on a day or date.",
      "url": "https://api.example.com/voicast/find-free-slots",
      "parameters": {
        "properties": {
          "date": { "type": "string", "description": "Day to search (YYYY-MM-DD)" },
          "period": { "type": "string", "enum": ["morning", "afternoon"], "description": "Morning or afternoon" }
        },
        "required": ["date"]
      }
    }
  ]
}
```

Your endpoint receives `{ type: 'tool.call', tool, tool_call_id, arguments, call: { id, channel, provider_call_id, from, tenant: { id, external_id } } }`, signed with Standard Webhooks. Use `call.tenant.external_id` to know which of your customers the call belongs to, and `tool_call_id` (the same as the `idempotency-key` header) for deduplication. Google Calendar, CRMs and similar systems work the same way: your endpoint calls their API. Mark tools that write (creating or cancelling bookings, for example) with `confirm: true` so the agent reads the details back and gets a yes first.

## FAQ

### How many tools can I give the AI?

voicast accepts up to 10 in `tools`. The more you add, the more likely the model is to pick the wrong one, so start with the minimum the call actually needs.

### Are there naming rules?

In voicast, tool names start with a lowercase letter and use lowercase letters, digits and underscores, up to 40 characters. `finish` is reserved, and names must not repeat within one config.

### What if my API can't answer within 8 seconds?

Push anything the caller doesn't need to hear about to after the conversation, and have the tool just acknowledge the request. If the core lookup itself is too slow, have the AI offer a callback and pick it up from the post-call webhook.
