> ## Documentation Index
> Fetch the complete documentation index at: https://help.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools for VoiceAgent

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

> [!NOTE]
>
> 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.

![](https://mintcdn.com/cloudtalk/g8s2E4Yk8cWS5656/images/help-center/articles/11275049/89b356edddea-screenshot-2025-05-07-at-11-20-17.png?fit=max\&auto=format\&n=g8s2E4Yk8cWS5656\&q=85\&s=484f51baeac2354c6fdf2fa12e8e794d)

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`](https://api.acme.com//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": ["a@b.com", "c@d.com"]`). 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`](https://api.acme.com//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**:

```text theme={"system"}
{
    "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`](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.”*

![](https://mintcdn.com/cloudtalk/g8s2E4Yk8cWS5656/images/help-center/articles/11275049/815cc3074282-image.png?fit=max\&auto=format\&n=g8s2E4Yk8cWS5656\&q=85\&s=a76817755f1e24e31cf664aec8ebcfec)

### 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**:

```text theme={"system"}
{
    "call_number": "++44123123123",
    "voice_agent_id": "6819f0e147851f618cd6aed6",
    "call_properties": {
        "system_prompt": {
            "variables": {
                "customer_identifier": "abc123",
            }
        }
    }
}
```

**This request will result in the following body:**

```json theme={"system"}
{
  "customer_id": "abc123",
  "attendee": {
    "email": "john@acme.com"
  },
  "recipients": ["a@b.com", "c@d.com"]
}
```

![](https://mintcdn.com/cloudtalk/0LuB-WYxwheF-8cl/images/help-center/articles/11275049/5b9ade3e0dcb-image-1.png?fit=max\&auto=format\&n=0LuB-WYxwheF-8cl\&q=85\&s=e35de45d644f8dfa1eb99f165c09c437)

***

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

   ![](https://mintcdn.com/cloudtalk/0LuB-WYxwheF-8cl/images/help-center/articles/11275049/194bac00bc65-image.png?fit=max\&auto=format\&n=0LuB-WYxwheF-8cl\&q=85\&s=b4b12e4f82fb42298f289c4fb49b63d7)

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](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) — we’re here for you.


## Related topics

- [VoiceAgent Tools: Cal.com](https://help.cloudtalk.io/en/articles/14073361-voiceagent-tools-cal-com.md)
- [VoiceAgent Scenarios & Guardrails](https://help.cloudtalk.io/en/articles/14073408-voiceagent-scenarios-guardrails.md)
- [VoiceAgents for Inbound Calls](https://help.cloudtalk.io/en/articles/11399385-voiceagents-for-inbound-calls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.