Tools for VoiceAgent

In this article, you’ll learn how VoiceAgent Tools enable real-time actions during live calls by allowing your VoiceAgent to interact directly with external systems via API.By leveraging Tools, you can turn your VoiceAgent into a fully capable problem-solver, enhancing automation and delivering faster, smarter customer experiences.

User level: Admin

What Are Tools?

Tools allow your VoiceAgent to perform specific actions during a call by making API requests to third-party systems. You can configure exactly what each tool does and when it should be triggered based on the conversation. For example:

A customer asks, “Where’s my order?” → VoiceAgent uses a tool to fetch the latest tracking info.
A patient says, “Can I move my appointment to Friday?” → VoiceAgent calls your booking API to check availability and reschedule.

Other example use cases:

Fetch data:
- Look up support ticket details
- Access live pricing or availability info
Execute actions:
- Update a CRM contact
- Trigger a refund

How to Create a Tool

To get started, go to Dashboard > AI Voice Agents > Tool Management, then either click the ➕ button in the top-right corner or select Create a Tool to open the configuration panel where you can define how your new tool works.

Here’s how to configure each part:

Tool Fields Reference

Field	Description
Tool Name	A clear, descriptive name that helps the VoiceAgent decide when to use this tool. Use names like `book_meeting`, `update_contact`, or `trigger_refund`. Only the following characters are allowed: `a-z`, `A-Z`, `0-9`, `_`, `-`
Tool Description	Describe in natural language what the tool does and when it should be used. This helps the AI understand in which situations to trigger the tool.
Awaiting Response Message	A short message the VoiceAgent plays while waiting for the API response. This helps manage silence during execution. Example: `Let me check that for you. One moment please.`
Method and Endpoint	The HTTP method and API endpoint the tool will call. For example: `GET https://api.example.com/orders`
Headers	Define any headers required by the API. These are usually constants like `Authorization`, `Content-Type`, or versioning headers.
Path Parameters	Used to fill in dynamic values within the endpoint URL (e.g., `#{{customer_id}}` in `https://api.acme.com/#{{customer_id}}/orders`).
Body Parameters	Available for `POST`, `PUT`, and `PATCH` methods only. Define fields to be sent in the request body.

Understanding Parameters

When defining a tool, parameters help the VoiceAgent pass the right values to your API. There are three main types of parameters you can use in both path and body definitions:

Parameter Types

Type	Description
Constant	A fixed value that stays the same for every API call. Useful when you know the exact value you want to send every time.
Parameter	A dynamic value sent from your system prompt. You’ll reference a variable name here that should match the one sent in your triggering API request.
LLM Prompt	A natural language instruction to the AI on how to extract a value from the conversation. Best when the input depends on what the caller says.

Each parameter also has a data type that controls how the value is formatted in the API request. Available types:

String, Integer, Number, Boolean work as simple scalar values.
List sends the value as a JSON array (e.g. "recipients": ["[email protected]", "[email protected]"]). When you select List, you also choose an element type (List of String, List of Integer, etc.). If the agent extracts only a single value, it’s automatically wrapped into a one-element array rather than failing.
Object sends the value as a JSON object. Note that object parameters are description-only: the agent is told the parameter is an object and sees your description, but it doesn’t know the specific field names, so it can’t enforce internal structure. This works well for simple pass-through payloads.

Path Parameters

These are values placed directly in the URL. You define them using curly brackets inside the endpoint URL, like #{{customer_id}}. Here’s how it works in practice: Example Endpoint:
https://api.acme.com/#{{customer_id}}/orders In this case, the customer_id becomes a path parameter. If defined as a Parameter:

Parameter	Value Source
`customer_id`	`customer_identifier` variable from the system prompt

Triggering Request Example:

{
    "call_number": "++44123123123",
    "voice_agent_id": "6819f0e147851f618cd6aed6",
    "call_properties": {
        "system_prompt": {
            "variables": {
                "customer_identifier": "abc123",
            }
        }
    }
}

This results in a call to:
https://api.acme.com/abc123/orders To extract via LLM Prompt:
Use a clear instruction like:
“Extract the customer ID mentioned by the caller if they provide it. If they don’t provide it proactively, ask for it.”

Body Parameters

For POST, PUT, and PATCH methods, you may need to send a request body. These work the same way as path parameters and can also use constants, system prompt variables, or LLM prompts. Nested objects can be defined using dot notation. Example Definition:

Parameter	Type	Value
`customer_id`	Parameter	`customer_identifier`
`attendee.email`	LLM Prompt	“Extract the customer’s email address from the conversation.”
`recipients`	LLM Prompt	”Extract all email addresses the caller mentions.”

Triggering Request:

{
    "call_number": "++44123123123",
    "voice_agent_id": "6819f0e147851f618cd6aed6",
    "call_properties": {
        "system_prompt": {
            "variables": {
                "customer_identifier": "abc123",
            }
        }
    }
}

This request will result in the following body:

{
  "customer_id": "abc123",
  "attendee": {
    "email": "[email protected]"
  },
  "recipients": ["[email protected]", "[email protected]"]
}

Assigning Tools to VoiceAgents

Tools allow VoiceAgents to perform specific actions during a call, such as triggering external workflows, sending data to other systems, or ending the call. A single VoiceAgent can use multiple Tools, and the same Tool can be used across multiple VoiceAgents. Tools are triggered as actions within a VoiceAgent Scenario. This means the VoiceAgent will use a Tool only when the situation defined in the Scenario occurs during the call. To use tool within scenario:

Navigate to the Scenarios & Guardrails section of the VoiceAgent configuration.
Create a new Scenario or edit an existing one.
Define the situation in which the Tool should be used.
In the Action field, select Tool Call.
In the Tools dropdown, choose the Tool you want the VoiceAgent to use.
Save the configuration.

Once configured, the VoiceAgent will automatically use the selected Tool when the scenario conditions are met during a call.

Tips for Using Tools Effectively

Use clear and descriptive tool names
Give each tool a name that clearly reflects what it does. Avoid abbreviations or internal codes.
- Good: trigger_refund, get_order_status, book_appointment
- Not great: rfnd_tool_v1, statusQ, app_sched_new
Write a natural language description
In the Tool Description field, explain when and why the VoiceAgent should use the tool. For complex tools, add a short description for each argument the agent needs to collect.

Need help or have a question? Just reach out through our Support portal — we’re here for you.

Get started

Numbers & porting

AI

AI Sales Dialer

CloudTalk Phone & Go

Messaging

Dashboard

Integrations

Billing & subscription

Tech News & Updates

Legacy dashboard

What Are Tools?

How to Create a Tool

Tool Fields Reference

Understanding Parameters

Parameter Types

Path Parameters

Body Parameters

Assigning Tools to VoiceAgents

Tips for Using Tools Effectively

​What Are Tools?

​How to Create a Tool

​Tool Fields Reference

​Understanding Parameters

​Parameter Types

​Path Parameters

​Body Parameters

​Assigning Tools to VoiceAgents

​Tips for Using Tools Effectively

What Are Tools?

How to Create a Tool

Tool Fields Reference

Understanding Parameters

Parameter Types

Path Parameters

Body Parameters

Assigning Tools to VoiceAgents

Tips for Using Tools Effectively