Built-in Tools

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.

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.

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

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

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

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

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 book nothing: they answer from a fixed list of times on the next two weekdays and report a booking without writing one.