Skip to main content

Tools for VoiceAgent

Set up Tools to let your VoiceAgent take real-time actions via API

V
Written by Valeriia Volobrinskaia
Updated yesterday

Tools let your VoiceAgent go beyond scripted answers by interacting directly with other platforms via API during a live call. Think of them as real-time actions your AI agent can take: fetch order status, book appointments, trigger refunds, and more.

This feature helps turn VoiceAgents from helpful assistants into full problem-solvers.


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 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.

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.”

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

  1. Go to the VoiceAgents tab in your CloudTalk Dashboard.

  2. Select the Agents section.

  3. Click on the agent you want to configure.

  4. Scroll to the Tools section of the agent's profile.

  5. Click Manage to see the list of available Tools.

  6. Select the Tools you want to assign to that agent.

  7. 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_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.

  • 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

get_free_slots

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

GET

Request method.

URL

https://api.cal.com/v2/slots?username={{userName}}&eventTypeSlug={{eventType}}&start={{startDate}}&end={{endDate}}

Endpoint URL with parameters.

Headers

cal-api-version

2024-09-04

Required by Cal.com.

Authorization

Bearer cal_live_76***REDACTED***17

Replace with your Cal.com API key.

Path Parameters

username

Constant: elise-marshall

Your Cal.com username. Can be found in your profile.

eventType

Constant: 30min

Slug from the event’s detail page in Cal.com. Use LLM Prompt if multiple types are available.

startDate

Parameter: startDate

Define the start of the search window. Should be passed as a System Prompt variable.

endDate

Parameter: endDate

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

book_meeting

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

POST

Request method.

URL

https://api.cal.com/v2/bookings

Endpoint for booking a meeting.

Headers

cal-api-version

2024-08-13

As required by Cal.com.

Authorization

Bearer cal_live_76***REDACTED***17

Replace with your API key from Cal.com API settings.

Body Parameters

username

Constant: elise-marshall

Your Cal.com username.

eventTypeSlug

Constant: 30min

Type of event being scheduled.

start

LLM Prompt: The start time of the booking in ISO 8601 format in UTC timezone, e.g. 2024-08-13T09:00:00Z.

Extracted from the conversation.

attendee.name

Parameter: name

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."

Did this answer your question?