Skip to main content

​
Overview

When you attach tools to a persona, the AI automatically knows they exist. However, your system prompt determines when and how the agent uses them. A well-written prompt tells the agent the conditions under which to invoke each tool. You reference tools by their model-facing name in your persona instructions. These are the names the AI actually sees and calls.

​
Voice Tools

These are available during live calls (voice:in-call).

​
hangUp

Ends the call.
ParameterTypeRequiredDescription
reasonstringNoA brief reason for hanging up
Once you've confirmed the appointment and said goodbye, use hangUp to end the call.
Do not hang up while the customer is still speaking.

​
transferCall

Transfers the call to another party. Used for both warm and cold transfers — the behavior depends on how the tool is configured on the persona. Warm transfer (AI stays on the line during handoff):
ParameterTypeRequiredDescription
targetstringDepends on configThe transfer destination (phone number or SIP URI). Only provided by the AI if configured with dynamic targets.
contextstringNoContext from the conversation to share with the new party
Cold transfer (immediate transfer, AI disconnects):
ParameterTypeRequiredDescription
targetstringDepends on configThe transfer destination. Only provided by the AI if configured with dynamic targets.
When the transfer target is pre-configured (static), the AI does not need to provide target — it’s injected automatically. When configured with dynamic targets, the AI decides where to transfer based on the conversation.
If the caller asks to speak with a manager, use transferCall and provide context
about what the caller needs help with.

If the caller requests the billing department, use transferCall to connect them.
Let them know you're transferring before you do it.

​
leaveVoicemail

Leaves a voicemail and ends the call.
ParameterTypeRequiredDescription
messagestringYesThe voicemail message to leave
If the call goes to voicemail, use leaveVoicemail with a brief message:
introduce yourself, state the reason for calling, and leave a callback number.
Keep it under 30 seconds.

​
playDtmfSounds

Plays touch-tone digits. Useful when your agent needs to navigate phone menus (IVR systems).
ParameterTypeRequiredDescription
digitsstringYesThe digits to play. May include 0-9, *, or #
When you reach the automated menu, use playDtmfSounds to press 2 for sales.
If prompted for an extension, dial 4501.

​
queryCorpus

Searches the attached knowledge base for relevant information.
ParameterTypeRequiredDescription
querystringYesWhat to search for
max_resultsintegerNoHow many results to return (1-20, default 5)
This tool is automatically available when a knowledge base is attached to the persona. You don’t need to manually enable it.
If the caller asks a question about our policies or pricing, use queryCorpus
to look up the answer before responding. Don't guess — always check the knowledge base first.

​
Multi-Agent Tools

​
agent_transfer

Transfers the live call to a different AI persona mid-call. The new persona takes over with its own system prompt, voice, and tools.
ParameterTypeRequiredDescription
target_keystringYesKey of the target persona to transfer to (matches one of the configured targets)
handoff_messagestringNoOne-line context to share with the new agent
If the caller wants to discuss a technical issue, use agent_transfer with
target_key "technical_support" and include a handoff_message summarizing
what the caller needs. Let the caller know you're connecting them with a specialist.

​
create_call

Creates a new outbound call as a separate session. Does not affect the current call.
ParameterTypeRequiredDescription
phone_numberstringNoE.164 phone number to call (provide if no contact_id)
contact_idstringNoExisting contact ID to call
persona_idstringNoPersona to make the call (defaults to configured persona)
contextstringNoReason/context for the call, shared with the receiving persona
external_referencestringNoOptional external reference for tracking
If the customer asks you to call their colleague to confirm availability,
use create_call with the colleague's phone number and provide context about
why you're calling them.

​
Prompting Best Practices

Don’t just say “transfer if needed.” Specify the exact conditions:
Use transferCall if the caller explicitly asks for a human agent,
or if you cannot resolve their issue after two attempts.
The agent should communicate with the caller before taking action:
Before using transferCall, always tell the caller:
"Let me connect you with our billing team now."
Prevent unwanted behavior by being explicit about restrictions:
Never use hangUp while the customer is mid-sentence.
Only hang up after they've confirmed they have no further questions.
You can instruct the agent to use multiple tools in order:
When the caller needs to be transferred:
1. Confirm with the caller that you're transferring them
2. Use transferCall and provide context about what they need help with
Always use the exact model-facing name (e.g., transferCall, not “transfer the call” or “do a warm transfer”). The AI maps your instructions to the tool by its name.