Built-in tools

Prompt ThunderPhone agents to end calls, transfer callers, navigate keypads, wait on hold, search knowledge, play sounds, and send email.

Built-in tools let an agent perform common call actions without connecting your own API. Most are available automatically; email, sounds, and knowledge search appear only after you configure the related setting or source. Tell the agent when to use each action in its prompt.

end_call#

Ends the current call when the prompt tells the model to do so. It is available by default and has no agent setting.

Write the condition and any required farewell into the prompt:

When the caller confirms they need nothing else, say goodbye and end the call.

An ordinary model-ended call has end_reason: "ai_hangup". A duration or balance shutdown can use a more specific end reason instead.

transfer_call#

Transfers a phone caller to a fixed number supplied by the model. Cold transfer is immediate. A screened warm transfer privately calls the destination before connecting the parties. Warm transfer requires a verified imported VoIP number that can place outbound calls.

Put the destination number and exact routing condition in the prompt:

If the caller asks for billing, transfer them to +15551234567.

A successful cold transfer has end_reason: "ai_transfer"; a completed warm handoff has end_reason: "ai_warm_transfer". A failed warm attempt returns control to the agent, so the call's later ending determines its end reason. On non-phone sessions, a transfer request ends the session instead.

See Transfer calls for dashboard and API setup, routing, screening, failure handling, limits, and testing.

send_keypad_input#

Sends DTMF (phone keypad) digits 0–9, *, and # to a phone line. The model uses it to navigate an IVR, the automated menu that asks callers to press keys. It is available by default and has no agent setting.

Tell the model which menus it may navigate and where requested values come from. Do not ask it to guess menu options:

Follow the phone menu for account status. Press a key only after the menu
states what that key does. Enter the account number supplied by the caller.

The platform removes unsupported characters and sends valid digits in order. If no valid digits remain or the call cannot send keypad input, the failure is returned to the agent so it can recover.

no_response#

Keeps the agent silent while an automated system is still speaking or asks it to keep listening. It is not for a live person's greeting, a question, or a true hold queue. It is available by default and has no agent setting.

Usually the built-in description is enough. For IVR-heavy calls, reinforce the boundary in the prompt:

Stay silent while a phone menu is still speaking. Answer a live person as soon
as they address you.

This action does not end the call.

wait_on_hold#

Places an outbound agent into a silent hold state until a live person returns. The model uses it only after the other party explicitly says the agent is being put on hold. It is automatically available on outbound calls and has no dashboard setting.

If a person explicitly puts you on hold, wait silently. When they return,
continue from the question you were discussing.

Do not prompt the agent to use it for an IVR's "please wait" message. Hold lasts up to 15 minutes by default. For ordinary outbound calls, POST /v1/call accepts a positive-integer max_hold_seconds; inline Realtime restricts max_hold_seconds to 10–900 seconds. If the person returns, the agent resumes without changing the call's end reason. If the limit expires, the platform ends the call with end_reason: "ai_hangup".

search_knowledge_base#

Searches documents attached to the agent and returns relevant passages. Attach a knowledge base or individual knowledge documents to enable it, then tell the model which answers must come from those sources:

Search the knowledge base before answering policy questions. If the first
search is inconclusive, try once more with different key terms.

If a search fails, the result is returned to the agent. See Knowledge base for dashboard and API setup.

play_sound#

Plays the agent's configured notification sound after any speech in the same turn. In the dashboard, set Advanced → Tool sound to Chime, Ding, or Beep, then deploy the agent. None removes the tool.

With the Agents API, stage play_sound_asset as "chime", "ding", or "beep", then deploy. Set it to "" to disable the tool.

After confirming that an appointment was saved, say "You're all set" and play
the notification sound.

A playback failure is returned to the agent and does not end the call.

send_email#

Sends a plain-text email to the one recipient configured by the agent owner. The model supplies the subject and body. It never sees a recipient parameter and cannot choose or change the address.

In the dashboard, enable Advanced → Send email, save a recipient address, then deploy the agent. With the Agents API, stage both send_email_enabled: true and a non-empty send_email_recipient, then deploy. Define the trigger and required contents in the prompt:

When the caller asks to leave a message, collect their name, callback number,
and message. Read the details back for confirmation, then email them.

A call can attempt at most three emails. Each subject is limited to 300 characters and each body to 20,000 characters. Missing configuration, invalid content, the per-call limit, and delivery failures are returned to the agent. A failed delivery still uses one of the three attempts.

Test with a controlled recipient before deploying broadly. Browser Talk and simulations send real email; there is no dry-run mode.

Compatibility note#

The Advanced → Uninterruptible disclosures setting and the legacy speak_uninterruptible_enabled field remain for compatibility, but enabling them has no effect. Leave the setting off; no prompt can activate this tool.

For a required call-opening disclosure, use Consent announcement. It plays verbatim before ordinary conversation and cannot be interrupted. See Call recording consent laws.

Test and monitor built-in tools#

Use browser Talk or a simulation to check prompting, knowledge search, sounds, and email. Those environments cannot reproduce phone-network behavior. Test keypad navigation and hold on an outbound phone call, and test a complete warm handoff on a real call using an eligible imported VoIP number. Realtime support is limited as shown in the table above.

Calls, pricing, and webhooks#

Built-in actions have no per-use tool fee. Normal call and provider charges still apply; see Pricing. Their calls and results can appear in the completed transcript, but they do not emit telephony.tool or web.tool. Those events are for user-defined functions. Only a completed hangup or transfer changes the call's end_reason; other failures are returned to the agent. See Completion webhooks for the call record.