Skip to main content
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.
To book appointments in Google Calendar, Microsoft Outlook, Calendly or Cal.com, use the built-in Appointment Booking skill instead of a custom tool. Custom tools can reschedule or cancel through your own booking API; with native Calendly or Cal.com booking, the caller reschedules or cancels through the platform’s links in the invite e-mail, or through the booking-confirmed SMS, which carries the reschedule link by default (add {{appointment.cancel_link}} to it for a cancel link).
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 click the ➕ button in the top-right corner and select Create custom tool, or select Create a Tool, to open the configuration panel where you can define how your new tool works. To build a tool on an integration you’ve already connected, see Create a tool from a connected integration. Here’s how to configure each part:

Tool Fields Reference

Create a tool from a connected integration

If the API you want to call belongs to an integration you’ve already connected to CloudTalk (for example Zoho, HubSpot, Pipedrive, Zendesk or Intercom), you can build the tool on top of that integration. CloudTalk then handles the connection for you: there are no API keys or authentication headers to enter.
  1. Go to Dashboard > AI Voice Agents > Tool Management and click the ➕ button.
  2. Under From your integrations, select the integration the tool should use.
    • An integration marked Not connected has lost its connection. Click Connect to reconnect it in your integration settings, then come back.
    • To use an integration you haven’t connected yet, click Connect new integration.
    The + menu in Tool Management with Create custom tool and the From your integrations list
  3. The Integration Tool box shows what’s inherited from the integration: the integration itself and its base URL (locked). Requests go through your integration’s connection, authentication is handled for you, and the tool can only reach that integration.
  4. Fill in the rest of the tool the same way as a custom tool: Tool Name, Description, Awaiting Response Message, Method, and the rest of the Endpoint after the locked base URL, plus any Path Parameters and Query Parameters. For POST, PUT and PATCH requests, you can also add Body Parameters. See Understanding Parameters. The Integration Tool box showing the inherited integration and locked base URL
  5. Click Test tool to send the request once, as the VoiceAgent would. Nothing is saved.
  6. Click Save in the bar at the bottom of the form, then assign the tool to your VoiceAgents (see Assigning Tools to VoiceAgents).
Pick an endpoint that returns a focused result. If the response is too large, it’s rejected rather than shortened, and the VoiceAgent gets nothing.
The tool can only do what your integration’s connection allows. If a request fails because of missing permissions, reconnect the integration in your integration settings.

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

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: Triggering Request Example:
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: Triggering Request:
This request will result in the following body:

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:
  1. Navigate to the Scenarios & Guardrails section of the VoiceAgent configuration.
  2. Create a new Scenario or edit an existing one.
  3. Define the situation in which the Tool should be used.
  4. In the Action field, select Tool Call.
  5. In the Tools dropdown, choose the Tool you want the VoiceAgent to use.
  6. 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.

Can I see whether a tool call succeeded?

CloudTalk doesn’t currently show a log of individual tool requests and responses. To check what happened on a call:
  • Open the call’s transcript on the call details page to see what the VoiceAgent said. Transcripts require Conversation Intelligence.
  • Check your own server logs. Every tool call is an HTTP request from CloudTalk to the endpoint you configured, so your logs show the request, the response and its status code.

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