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 > VoiceAgents > 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 |
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. |
Method and Endpoint | The HTTP method and API endpoint the tool will call. For example: |
Headers | Define any headers required by the API. These are usually constants like |
Path Parameters | Used to fill in dynamic values within the endpoint URL (e.g., |
Body Parameters | Available for |
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. |
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 |
|
|
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 |
| Parameter |
|
| LLM Prompt | “Extract the customer’s email address from the conversation.” |
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]"
}
}
Assigning Tools to VoiceAgents
After you’ve created a Tool, you need to assign it to one or more VoiceAgents so they can actually use it during calls.
Each Tool can be assigned to multiple VoiceAgents, and each VoiceAgent can have multiple Tools assigned, there's no limitation in either direction.
How to assign a Tool
Go to the VoiceAgents tab in your CloudTalk Dashboard.
Select the Agents section.
Click on the agent you want to configure.
Scroll to the Tools section of the agent's profile.
Click Manage to see the list of available Tools.
Select the Tools you want to assign to that agent.
Click Confirm to apply the changes.
Once assigned, the VoiceAgent will be able to use the Tool during live conversations whenever its instructions in the prompt are met.
Need to remove a Tool from an agent? Simply return to the same Tools section under that agent’s profile and deselect it.
Referencing Tools in Agent Prompts
To make sure your VoiceAgent knows when and how to use a Tool, you’ll need to reference it directly in the agent’s system prompt.
This instruction helps the AI decide the right moment to trigger a Tool during a call, based on the caller’s request or intent.
How to reference a Tool in a prompt
In your VoiceAgent’s prompt (under the VoiceAgent Prompt Settings in the agent configuration), describe the situation in which the Tool should be used. Be as specific as possible to ensure accuracy.
Example:
When a customer asks about local weather in Paris, use the get_local_weather tool to fetch current conditions and share them with the caller.
You can include multiple Tool references in one prompt, each with a clear condition that helps guide the agent's behavior.
Need help writing strong prompt instructions? Check out our Prompt Writing Guide for tips on phrasing and structure.
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_appointmentNot 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.Include usage examples in the VoiceAgent prompt
Reinforce correct tool usage by referencing the tool in your VoiceAgent’s system prompt.Example:
Use check_order_status when the caller asks things like "Where is my order?" or "Has my item shipped?"
Choose the right LLM model
For better tool performance, use high-performing models with strong reasoning capabilities:Recommended: GPT-4.1, GPT-4.1 Mini, GPT-4o, GPT-4o Mini, Claude 3.5 Sonnet
Avoid: Gemini 1.5
Example: Scheduling Appointments with Cal.com
This example demonstrates how to set up two tools that work together to handle appointment scheduling through Cal.com. One tool is used to fetch available time slots, and the other is used to book a selected time once the customer confirms.
This is a sample use case to help you understand how to build Tools for similar workflows in your own systems.
Tool 1: Fetching Available Time Slots
Section | Field | Value | Description |
General | Tool Name |
| Describes what the tool does. |
| Description | When the customer asks for available slots, use this tool to get the list. The response will include dates and times in UTC. | Helps LLM decide when to call this tool. |
| Awaiting Response Message | Let me check the availability. One moment please. | Message played while the tool request is being processed. |
Request Definition | Method |
| Request method. |
| URL |
| Endpoint URL with parameters. |
Headers | cal-api-version |
| Required by Cal.com. |
| Authorization |
| Replace with your Cal.com API key. |
Path Parameters | username | Constant: | Your Cal.com username. Can be found in your profile. |
| eventType | Constant: | Slug from the event’s detail page in Cal.com. Use LLM Prompt if multiple types are available. |
| startDate | Parameter: | Define the start of the search window. Should be passed as a System Prompt variable. |
| endDate | Parameter: | Define the end of the search window. Also passed via System Prompt variable. |
Tool 2: Booking the Appointment
Section | Field | Value | Description |
General | Tool Name |
| Descriptive tool name. |
| Description | This tool books a meeting in the calendar after the customer chooses a time. | Helps the LLM understand when to use the tool. |
| Awaiting Response Message | I'm scheduling the meeting now. Please wait. | Message played while booking is in progress. |
Request Definition | Method |
| Request method. |
| URL |
| Endpoint for booking a meeting. |
Headers | cal-api-version |
| As required by Cal.com. |
| Authorization |
| Replace with your API key from Cal.com API settings. |
Body Parameters | username | Constant: | Your Cal.com username. |
| eventTypeSlug | Constant: | Type of event being scheduled. |
| start | LLM Prompt: The start time of the booking in ISO 8601 format in UTC timezone, e.g. | Extracted from the conversation. |
| attendee.name | Parameter: | Passed via System Prompt. |
| attendee.email | LLM Prompt: Email of the customer booking the meeting. | Extracted dynamically. |
| attendee.timezone | Constant or LLM Prompt | Set based on your workflow. |
VoiceAgent Prompt
##Identity
You are an Meeting Scheduler working at CloudTalk, calling customers over the phone. You’re a friendly, supportive, and efficient assistant, booking meetings for Peter - Product Manager at CloudTalk.
##Style Guardrails
Be Concise: Respond succinctly, addressing one topic at most.
Do not repeat yourself, and do not repeat the customer.
If something was already said, assume everyone remembers and do not repeat it.
Embrace Variety: Use diverse language and rephrasing to enhance clarity without repeating content.
Be Conversational: Use everyday language, making the chat feel like talking to a friend.
Avoid multiple questions in a single response.
Get clarity: If the user only partially answers a question or if the answer is unclear, keep asking to get clarity.
Use colloquial date references (e.g., Friday, January 14th, or Tuesday, January 12th, 2024 at 8am).
##Response Guideline
Adapt and Guess: Understand transcripts even if they contain transcription errors.
Avoid mentioning “transcription error” in the response.
Stay in Character: Keep conversations within your role’s scope, guiding customers back creatively without repeating.
Ensure Fluid Dialogue: Respond in a role-appropriate, direct manner to maintain smooth conversation flow.
Use first names only, never the last name.
##Task
Open with: “Hey {{name}}, this is Emma from CloudTalk. Peter would love to book a meeting with you are you interested?
If the customer says yes, use the get_free_slots tool to obtain available slots and then offer the earliest 3 of them to the customer. The response is in UTC timezone but offer them in CET.
Once the customer picks a slot, confirm that their email address is {{email}}. This is an email address so read it like one. For example "joe dot black at gmail dot com".
If they confirm or give you a different address, use that email to schedule the meeting by using the book_meeting function.
If the function returns success, say "Your meeting is scheduled now, you will receive a confirmation email shortly. Have a nice day."
If you need any further assistance please do not hesitate to reach out to our Support team, we are always happy to help!