Skip to main content
Ultravox Realtime includes several built-in tools that provide common functionality out of the box. These tools are publicly available and work exactly like custom tools you create yourself.

​
Available Built-in Tools

Tool NameDescription
queryCorpusRetrieves relevant information from an existing corpus (knowledge base). See Query Corpus API for details.
leaveVoicemailLeaves a voicemail and ends the call. Intended to be used with outbound phone calls.
hangUpTerminates the call programmatically. Useful for ending conversations gracefully.
playDtmfSoundsPlays dual-tone multi-frequency (dialpad) tones. See DTMF documentation for sending and receiving tones.
coldTransferTransfers the current call to a human operator. See Call Transfers for more details.
More information about these can be found below in Tool Details →
Built-in tools use the same definition structure as custom tools. You can view their complete specifications using the List Tools API.

​
Using Built-in Tools

Using built-in tools is the same as using any other custom durable tool that you have created except for one difference: you can override built-in tools by using the same name. For example, if you created a durable tool named “hangUp” and then provide that tool by name (i.e. not by the toolId), then your tool would be used instead of the built-in hangUp tool. Add built-in tools when creating agents, calls, or call stages:

​
Using Tool Names

// Add the hangUp tool by name
{
  "systemPrompt": "You are a helpful assistant. When the conversation naturally concludes, use the 'hangUp' tool to end the call.",
  "selectedTools": [
    { "toolName": "hangUp" }
  ]
}

​
Using Tool IDs

If you have multiple tools with the same name, you can use the unique toolId instead. Agents will see the modelToolName. 
// Add the hangUp tool by ID (more explicit)
{
  "systemPrompt": "You are a helpful assistant. When the conversation naturally concludes, use the 'hangUp' tool to end the call.",
  "selectedTools": [
    { "toolId": "56294126-5a7d-4948-b67d-3b7e13d55ea7" }
  ]
}

​
Viewing Available Tools

Use the List Tools API to see all available tools, including built-ins: 
curl -X GET "https://api.ultravox.ai/api/tools" \
  -H "X-API-Key: your-api-key"
The List Tools API returns both built-in tools and any custom tools you’ve created, making it easy to see all tools available in your account.

​
Tool Parameters

Tools can use and pass parameters (i.e. send variables to the underlying API). The parameters for each built-in tool are explained below. See Tool Parameters → for details about the different types of parameters used by tools.
Tool Parameters
Tools can use and pass parameters (i.e. send variables to the underlying API). The parameters for each built-in tool are explained below.See Tool Parameters → to learn about the different types of parameters used by tools.

​
Built-in Tool Details

​
queryCorpus

Searches through a knowledge base (corpus) to find relevant information (AKA RAG). Requires the ID of the corpus (corpus_id) to be used for all queries and a dynamic query parameter is used for each query. Optionally, you can restrict the number of results that are returned to the agent (via max_results) along with a minimum semantic similarity score (minimum_score). Example Usage:
Using queryCorpus Tool

// Basic usage
{
  "selectedTools": [
    {
      "toolName": "queryCorpus",
      "parameterOverrides": {
        "corpus_id": "your-corpus-id-here"
      }
    }
  ]
}

// Require semantic similarity of 0.8 or higher
{
  "selectedTools": [
    {
      "toolName": "queryCorpus",
      "parameterOverrides": {
        "corpus_id": "your-corpus-id-here",
        "minimum_score": 0.8
      }
    }
  ]
}

​
Parameters

Required Parameter Override:
​
corpus_id
string
required
The ID of the corpus to be used for all queries.
Dynamic Parameters:
​
query
string
required
What to search for.
​
max_results
integer
default:"5"
How many chunks to receive back. Can be any value from 1-20.
Static Parameters:
​
minimum_score
number
default:"0"
Can be used to only return content with a minimum semantic similarity score.

​
leaveVoicemail

When making outbound phone calls, used to leave a voicemail and then end the call. A dynamic message parameter is used for the message that will be left. Optionally, you can change the hang up behavior with strict and the return message with result. Example Usage:
Using leaveVoicemail Tool

// Basic usage
{
  "selectedTools": [
    {
      "toolName": "leaveVoicemail"
    }
  ]
}

​
Parameters

Dynamic Parameters:
​
message
string
required
The voicemail message to leave.
Static Parameters:
​
strict
bool
default:"true"
true ends the call regardless of user interaction. If set to false, any user interaction (i.e. speech or interrupting the voicemail) will cause the call to continue.
​
result
string
default:"[Leaving voicemail...]"
The message that is returned from the tool call. Will be added to conversation history.

​
hangUp

Ends the current call programmatically. Optionally accepts a dynamic parameter called reason. A static parameter called strict can be overridden to enable the call to continue if the user speaks and continues the call. Example Usage:
Using hangUp Tool
// Basic usage
{
  "systemPrompt": "Help users with their questions. When they say goodbye or the conversation naturally ends, use the hangUp tool to end the call politely.",
  "selectedTools": [
    { "toolName": "hangUp" }
  ]
}

// Enable soft hangup behavior
{
  "selectedTools": [
    {
      "toolName": "hangUp",
      "parameterOverrides": {
        "strict": false
      }
    }
  ]
}

​
Parameters

Dynamic Parameters:
​
reason
string
A brief reason for hanging up.
Static Parameters:
​
strict
bool
default:"true"
true ends the call regardless of user interaction. If set to false, any user interaction (i.e. speech) will cause the call to continue.

​
playDtmfSounds

Plays telephone keypad tones (dual-tone multi-frequency signals). Requires a dynamic parameter called digits. Static parameters for toneDuration and spaceDuration can be overridden. Automatically sets the sample rate based on current call medium. Example:
Using playDtmfSounds Tool
// Basic usage
{
  "selectedTools": [
    { "toolName": "playDtmfSounds" }
  ]
}

// Increasing length of tones and spaces
{
  "selectedTools": [
    {
      "toolName": "playDtmfSounds",
      "parameterOverrides": {
        "toneDuration": "0.5s",
        "spaceDuration": "0.3s"
      }
    }
  ]
}

​
Parameters

Dynamic Parameters:
​
digits
string
required
The digits for which tones should be produced. May include: 0-9, *, #, or A-D.
Static Parameters:
​
toneDuration
string
default:"0.2s"
The length (in seconds) that tones will be emitted.
​
spaceDuration
string
default:"0.1s"
The length (in seconds) that spaces (AKA silence between DTMF tones) will be emitted.

​
coldTransfer

Transfers the current call to a human operator. Requires the transfer target. You can optionally include additional headers that will be used in the sip REFER. Example Usage:
Using coldTransfer Tool

// Basic usage
{
  "selectedTools": [
    {
      "toolName": "coldTransfer",
      "parameterOverrides": {
        "target": "sip:user@mytrunk.com"
      }
    }
  ]
}

// With headers and name/description overrides
{
  "selectedTools": [
    {
      "toolName": "coldTransfer",
      "nameOverride": "escalateToManager",
      "descriptionOverride": "Transfers the call to your shift manager.",
      "parameterOverrides": {
        "target": "sip:manager@mytrunk.com",
        "extraHeaders": {
          "Referred-By": "sip:agent@mytrunk.com",
          "X-Custom-Header": "customValue"
        }
      }
    }
  ]
}

​
Parameters

Required Parameter Override:
​
target
string
required
The target of the transfer. This is who the user’s client should be REFER’ed to. A SIP URI is always allowed. A phone number in E.164 format may be allowed depending on your medium and telephony configuration.
Optional Parameter:
​
extraHeaders
object
A string-to-string map of headers to include in the REFER request. Custom headers should use the “X-” prefix to avoid conflicts with standard SIP headers.

​
Customizing Built-in Tools

​
Overriding Tool Behavior

You can customize built-in tools by overriding their names or descriptions:
Overriding Tool Name & Description
{
  "selectedTools": [
    {
      "toolName": "hangUp",
      "nameOverride": "endConversation",
      "descriptionOverride": "Politely end the conversation when the user is satisfied with the help provided."
    }
  ]
}

​
Parameter Overrides

Some built-in tools require or allow parameter overrides: 
{
  "selectedTools": [
    {
      "toolName": "queryCorpus",
      "parameterOverrides": {
        "corpus_id": "corp-123",
        "maxResults": 5
      }
    }
  ]
}
See the guide on Parameter Overrides →

​
Replacing Built-in Tools

You can override built-in tools by creating your own tool with the same name: 
// Create a custom "hangUp" tool that logs before ending calls
{
  "name": "hangUp",
  "definition": {
    "modelToolName": "hangUp",
    "description": "Log conversation details and end the call",
    "http": {
      "baseUrlPattern": "https://your-api.com/log-and-hangup",
      "httpMethod": "POST"
    }
  }
}
When you reference a tool by name, your custom tool will be used instead of the built-in version.
Tool ID vs Name PriorityIf you reference a tool by toolId, you’ll always get that specific tool. If you reference by toolName and have a custom tool with the same name, your custom tool takes precedence over the built-in version.

​
Authentication

Built-in tools handle authentication automatically - no additional setup required. However, some tools like queryCorpus require you to specify which corpus to search via parameter overrides.

​
Next Steps