# Built-in Tools (/docs/agents/voice-agents/built-in-tools)

> For the complete documentation index, see [llms.txt](https://docs.tandemcx.ai/llms.txt). Any page on this site can be fetched as Markdown by appending `.md` to its URL.

Built-in tools are call-control actions the agent can take on its own. Unlike the tools on the
**Custom Tools** row, you don't define a name, a description, or parameters: you switch a tool on
and tell it where it's allowed to go.

You configure them on the **Built-in Tools** row, in the **Tools & Skills** group on the
agent editor's **Conversation** step.

## You name the destinations; the agent picks one

Every transfer tool takes exactly one decision from the agent: _which of the destinations you
listed_. The agent never supplies a queue, an agent, or a phone number of its own — it chooses a
name you wrote, and Tandem resolves that name to the real target.

That is a safety property, not a convenience. If the agent could supply a phone number, anything a
caller said could become a number Tandem dials and your organization pays for.

Each destination needs:

- **Name** — the label the agent picks. Up to 64 characters.
- **When to use it** — one or two sentences telling the agent when this is the right destination.
  Up to 280 characters. This is the whole basis on which the agent chooses, so be specific:
  "Billing questions, invoices, and payment plans" beats "billing".
- **The target** — the queue, agent, phone number, or voice agent it resolves to.

<Callout type="warn">
    Both of those fields are sent to the model on every turn of every call. Long lists of long
    descriptions make every turn slower and more expensive. Twenty destinations is the cap.
</Callout>

## The transfers

**Transfer to an outside number** dials a phone number over the ordinary phone network. Numbers are
stored in bare E.164: `+15551234567`, no spaces, dashes, or parentheses.

**Transfer to another agent** hands the conversation to another of your agents. On a call nothing
leaves Tandem, so the caller hears no dial tone and no ringing.

<Callout type="info">
    Each agent has its own voice. After a transfer to another voice agent, **the caller will hear a
    different voice**, because they are, genuinely, talking to a different agent.
</Callout>

<Callout type="info">
    There is no "transfer to a queue" or "transfer to an agent" yet. Those route through SharpenCX,
    which Tandem cannot currently turn into a dialable destination, so they are tracked separately
    rather than shipped as switches that would not work.
</Callout>

**Carry over** controls how much the receiving agent knows:

- **Nothing** — the second agent starts fresh.
- **A summary** (the default) — the first agent writes a short handover note.
- **The whole conversation** — the second agent receives the transcript so far.

A call can hop between agents at most three times, so an agent that keeps sending callers back and
forth eventually gets a plain error and has to help instead.

### Transfers in website chat

<Callout type="info">
    Agent transfers in chat are being rolled out. Until they are on for your organization, the agent
    is offered this tool on calls only and the editor marks it **Voice only**. Contact support to
    turn it on.
</Callout>

In a chat, the visitor stays in the same widget, under its name and avatar. The transcript shows a
line, **Transferred to** followed by the destination's name, and the receiving agent answers the
visitor's last message straight away, so the visitor does not have to repeat it. The receiving
agent's greeting is not shown.

The receiving agent must be published and have **Chat** on under **Channels**. If it isn't
published, or doesn't have Chat on, the transfer fails and the first agent gets an error naming the
destination, so it can tell the visitor and carry on.

**Carry over** means the following in chat, and holds for the rest of the conversation:

- **Nothing** — the receiving agent sees the visitor's last message and what follows it.
- **A summary** — the receiving agent also sees the first agent's handover note.
- **The whole conversation** — the receiving agent sees everything the first agent saw.

The editor's preview chat does not transfer, so test transfers in the live widget.

A chat conversation can also transfer at most three times. In **Call Logs** the chat stays filed
under the widget's own agent.

### What happens when a transfer fails

Tandem dials the target and waits for it to answer **before** it takes the agent away. If the
target is busy, invalid, or never picks up, nothing is torn down: the caller is still talking
to the same agent, which hears an ordinary tool error and can offer something else. The caller
never knows a transfer was attempted.

## Capture keypad digits

Lets the agent ask the caller to type something — an account number, a PIN, a menu choice — and read
the digits back.

The agent writes the wording of the request itself, in the caller's own context ("What are the last
four digits of your account number?"), and the tool speaks it. Collecting only starts once that
request has finished playing, so the caller always hears the whole thing and gets the full
timeout to answer it. Digits typed over the tail of the request still count: an eager caller
does not lose the start of their account number.

While it is collecting, the agent stops talking, which is what keeps it from speaking over the
caller's keypresses.

You do not write the wording, and there is no setting for it. A capture can be asked for at
any point in a conversation, and the right sentence depends on what the caller has already
said.

Settings:

- **Maximum digits** (1–32, default 16)
- **Finish key** — `#`, `*`, or none
- **Overall timeout** (default 10 seconds, at most 14 unless you've lowered the tool timeout) and
  **gap between digits** (default 3 seconds, and shorter than the overall timeout)
- **Keypresses interrupt the agent** (default on). This overrides the agent's own barge-in setting
  for keypresses only, so an agent configured to read a disclaimer without interruption still
  honors "press 0 at any time".

The overall timeout has to stay a second inside the budget any single tool call gets — 14 seconds
by default, against the standard 15-second budget. Past that budget the call-control layer cuts
the collection short before your timeout is reached and the caller's digits are lost, so a longer
value is rejected when you save. The gap between digits also has to be shorter than the overall
timeout. If it weren't, the gap timer could never fire before the overall timeout ends the
collection first, so a gap that long would silently do nothing.

**Lowering [**Tool timeout**](/docs/agents/voice-agents/conversation) lowers this ceiling with
it.** Set the tool timeout to 5,000 ms and the overall DTMF timeout can be at most 4,000 ms; the
save is rejected until you bring it down, because otherwise every capture on every call would lose
its digits.

If an agent was saved with a longer timeout before this limit existed, calls use the ceiling
instead — the stored value is capped when the call loads it, not at your next save.

## Pause and resume recording

<Callout type="warn">
    **Not available yet.** These tools are built but switched off, and saving an agent with them
    enabled is rejected. A workflow can pause a recording with a **Stop Recording** node instead;
    see [Call Recording](/docs/overview/call-recording#pausing-a-recording).
</Callout>

One switch will turn on both `pause_recording` and `resume_recording`. They come as a pair
because an agent that could pause a recording but not resume it would leave the rest of the
call unrecorded.

## Tell the caller the current time

Every agent is told the current date, day of the week, and time when a conversation starts, whether
or not this tool is on. You don't switch that on and you don't write it into your prompt. So an
agent answers "what's today's date?" or "is Monday the 3rd?" correctly without this tool.

What the tool adds is a clock the agent can read again mid-conversation. The date it was given at
the start is right for the whole call, but the time drifts as the call runs, so an agent that has to
quote the time to the minute forty minutes in — or work out how long until a 3:00 appointment —
needs to check. Turn it on for scheduling, business hours, and countdowns. Leave it off if the agent
only needs to know what day it is.

Turning the tool on reveals a **Timezone** picker. It defaults to `America/New_York`, which is only
right for an eastern-time operation — set it to the zone your business runs in. The agent answers
every time question in that one zone; it has no way to work out where the caller is, so a caller in
Phoenix hears your hours in your timezone, not theirs.

That picker also sets the zone for the date every agent gets at the start of a conversation. It is
only shown while the tool is on, so an agent with the tool switched off is told the date in
`America/New_York`. If your business runs in another zone and the day-boundary matters — an agent
taking late-evening calls on the west coast would hear tomorrow's date after 9:00 PM — turn the tool
on and set the zone.

## Set a workflow variable

Lets the agent write named values back to the workflow that called it — a captured account number,
a chosen option — so the workflow can route on them after the call.

This only makes sense when the agent was reached _from_ a workflow. On a call that came straight to
the agent (a phone number or SIP trunk pointed at it, or a preview session) the tool isn't offered
at all, rather than offered and failing.

Values are collected during the call and handed to the workflow when the agent finishes.

## Update the contact

`update_contact` isn't switched on from this card. It comes from **Let the agent update the
contact** on the [**Contacts**
card](/docs/agents/voice-agents/contacts#let-the-agent-update-the-contact), and it's documented here
because the agent calls it the same way it calls the tools above, and because the name is reserved:
a custom tool can't be called `update_contact`.

It records what the agent learned about the caller on the contact this call resolved to. It can set
a first and last name, append one line to the notes, add tags, and fill in the attributes your
organization marked **Agent can edit** under **Admin → Contact Attributes**. Names replace what was
there; notes and tags are added to it.

Notes hold 4,000 characters. When a new line doesn't fit, the oldest lines the agent wrote are
dropped to make room. Notes a person typed are never dropped: if they leave no room, the agent's
line isn't saved and the agent is told so.

The contact is fixed when the call starts. The agent never names one, so it can only write to the
person on the phone, and the tool isn't offered at all on a call where no contact resolved.

It cannot add a phone number or an email address. If your organization marked no attribute **Agent
can edit**, the tool is still offered for the name, the notes, and the tags.

Failures come back to the agent as an ordinary sentence rather than an error, so a contact write
that doesn't land never interrupts the call.

## Look up a contact

`lookup_contact` isn't switched on from this card either. It comes from **Let the agent look up
contacts** on the [**Contacts**
card](/docs/agents/voice-agents/contacts#let-the-agent-look-up-contacts). Its name is reserved
too: a custom tool can't be called `lookup_contact`, and a tool by that name on a connected MCP
server isn't offered to the agent.

The agent gives it a phone number or email address. It answers with the contact that holds it, in
the same form the agent is told about its own caller, or says that no contact matches. It never
creates or changes a contact, and the call stays attached to the caller's own contact whatever the
agent looks up. It answers three lookups per agent session and refuses the fourth; a transfer to
another agent, or a dropped call that resumes, starts a new count.

It's offered only on a voice call, never in chat, and only with **Recognize callers** on. Because
it puts another person's record in front of the agent, pair it with the
[`verify-identity`](/docs/agents/voice-agents/skills#platform-skills) skill and tell the agent in
your system prompt to verify the caller first.

Failures come back to the agent as an ordinary sentence, as with `update_contact`.

## Switch language

`switch_language` isn't switched on from this card. An agent with two or more
[languages](/docs/agents/voice-agents/voice-and-speech#multiple-languages) has it automatically,
and an agent with one language doesn't. Its name is reserved: a custom tool can't be called
`switch_language`.

The agent calls it with the name of one of the agent's languages, before it says anything, when
the caller asks to speak another language or answers a language menu by naming one, such as
"español". The call's voice changes to that language's voice, the caller is transcribed in that
language from then on, and the agent is told to reply in it. The agent can also switch by
replying in another of its languages. See [How the agent
switches](/docs/agents/voice-agents/voice-and-speech#how-the-agent-switches).

A name that isn't one of the agent's languages comes back to the agent as an error listing the
valid names, and the call stays in its current language. It's offered on voice calls only.

## Schedule callbacks

Lets the agent offer open callback times from one of your [scheduling
calendars](/docs/agents/scheduling) and book one for the caller. It adds two tools,
`check_callback_availability` and `book_callback`. Their names are reserved: a custom tool can't
use either.

Turn on **Schedule callbacks** on the **Built-in Tools** row and pick a **Calendar**. Saving with
the tool on and no calendar is refused with `Pick the calendar the agent books callbacks on.` A
paused calendar is listed as `(paused)`; while it is paused the agent tells the caller it isn't
taking callbacks. Turning the tool off keeps the calendar you picked. The setting is shown only
while **Scheduling** is enabled for your organization.

`check_callback_availability` lists the calendar's next open times, up to 3 days at a time. The
agent can pass the caller's time zone and a start date to look at later days. Times come back in
the zone the agent asked for, or the calendar's zone when it names none or one that isn't a valid
zone.
`book_callback` books one of those times for the caller's name and phone number. The agent can
also pass an email, a reason, and notes of up to 500 characters. The calendar's **Booking Page**
settings decide whether email is required and which reasons are offered.

Rules that hold on every booking:

- **Open times only.** The agent can't book **As soon as possible**. The caller picks a listed
  time.
- **15-minute floor.** A time less than 15 minutes away is never offered, on top of the
  calendar's own **Lead time**.
- **Your calendar's rules apply.** Slot capacity and **Max upcoming callbacks per phone** limit an
  agent as they limit the booking page. The caller can't book a calendar from another
  organization.
- **One booking per conversation.** A call or a chat books at most one callback; in chat that
  holds across every message. A repeat of the booked time returns the same booking instead of
  making a second one.
- **Check and attempt limits.** 10 availability checks and 5 `book_callback` attempts per agent
  session on a call, failures included. In chat they apply to each message the visitor sends.

On a voice call the agent asks whether to call back on the number the caller is calling from, and
leaves the number out if they say yes. When the caller's number is withheld or isn't a full
international number (such as `+15551234567`), it asks for one. In website chat there is no
caller number, so the agent always asks. A number the caller gives is read the same way the
booking page reads it: an extension is dropped, and the callback goes to the main number. The
tools work in chat as well as on calls, and the agent gives the visitor a link to
change or cancel the callback in the chat. On a call it doesn't.

The agent tells the caller the number the callback goes to, as the booking stored it. If the
agent books the same time again with a different number, the booking keeps its first number and
the agent says so.

The caller gets the confirmation the calendar's **Notifications** tab sends: a text, an email, or
both, and none when neither can be sent. The agent tells the caller which. See [Booking
messages](/docs/agents/scheduling/messages). The callback shows **Booked By** **Agent** in its
sidebar on **Scheduling → Bookings**.

Failures come back to the agent as an ordinary sentence, as with `update_contact`, so a booking
that doesn't land doesn't end the call.

## Preview

A [preview call](/docs/agents/voice-agents/preview-calls) has no phone call behind it, so the
telephony tools **simulate success**: **Transfer to an outside number** reports that it connected
without dialing, **Pause and resume recording** reports success, and keypad capture returns the
sample digits `1234`. **Transfer to another agent** is not simulated; see [Transfers during a test
call](/docs/agents/voice-agents/preview-calls#transfers-during-a-test-call).

Contact recognition is switched off for the whole preview session, whatever the agent is saved
with: a preview's caller ID is a placeholder that addresses nobody. No contact resolves, so the
agent is told nothing about the caller, and neither `update_contact` nor `lookup_contact` is
offered.

The parts you most need to test are the prompts that lead _up to_ a transfer, and preview covers
those. It can't tell you a queue id is wrong or a number is unreachable; verify those on a real
call.

Callback tools are live in a preview call and in the editor's test chat. They read the calendar
and **book for real**, and the confirmation is sent to the number you give, so use a number you
can receive messages on and cancel the callback on **Scheduling → Bookings** afterward. A preview
call has no caller number, so the agent always asks for one. A test chat books at most one
callback, as a website chat does. [Agent
tests](/docs/agents/voice-agents/tests) book nothing: they answer from a fixed list of times on
the next two weekdays and report a booking without writing one.