--- title: "Built-in tools" description: "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. | Tool | Use it for | How to enable it | Supported calls | | --- | --- | --- | --- | | `end_call` | Finish a completed conversation | Always available | Phone, browser Talk, widget, simulation, and Realtime | | `transfer_call` | Route a phone caller | Configure routing in the prompt | Ordinary phone calls; inline Realtime with `call_events` can use cold transfer. Saved-agent Realtime omits it. | | `send_keypad_input` | Press keys in a phone menu | Always available on ordinary phone calls | Phone calls; inline outbound Realtime with `call_events`. Saved-agent Realtime omits it. | | `no_response` | Keep listening while an automated menu speaks | Always available | All call types | | `wait_on_hold` | Wait silently for a person to return | Included on outbound calls | Outbound phone and outbound inline Realtime sessions | | `search_knowledge_base` | Answer from attached sources | Attach knowledge to the agent | Saved-agent calls with attached knowledge | | `play_sound` | Play a configured notification sound | **Advanced → Tool sound** | Saved-agent calls | | `send_email` | Email one fixed recipient | **Advanced → Send email** | Saved-agent calls | ## `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: ```text 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: ```text 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](/guides/call-transfers) 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: ```text 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: ```text 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. ```text 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: ```text 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](/guides/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](/api-reference/agents), stage `play_sound_asset` as `"chime"`, `"ding"`, or `"beep"`, then deploy. Set it to `""` to disable the tool. ```text 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](/api-reference/agents), stage both `send_email_enabled: true` and a non-empty `send_email_recipient`, then deploy. Define the trigger and required contents in the prompt: ```text 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](/guides/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](/guides/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](/tools/overview). Only a completed hangup or transfer changes the call's `end_reason`; other failures are returned to the agent. See [Completion webhooks](/webhooks/call-complete) for the call record.