> For the complete documentation index, see [llms.txt](https://docs.voiceb.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voiceb.ai/tools-connect-your-agent-to-external-actions-beta.md).

# Tools — Connect Your Agent to External Actions (Beta)

This guide explains how to use **Tools** to extend your VoiceB agent beyond conversation. Tools let your agent perform **real-time actions during a call** — checking data against your systems, validating a customer record, creating a lead, or triggering any HTTP endpoint — all while the conversation keeps flowing naturally.

The result: agents that don't just talk, but **execute** — querying, validating, and writing data in real time, exactly when the conversation requires it.

{% hint style="info" %}
**VoiceB tip:** Tools are **reusable at the organization level**. Build a tool once (e.g. "Check coverage by ZIP code") and attach it to as many agents as you need. Any changes you make are automatically **published to the agent's provider** — no manual sync required.
{% endhint %}

***

#### What is a Tool?

A Tool is an **HTTP action** your agent can call autonomously during a conversation. The AI decides *when* to use it based on the tool's description and the context of the call.

Typical use cases:

* **Real-time data checks** → verify if a caller is an existing customer before pitching.
* **Coverage / availability lookups** → check service availability by address or ZIP.
* **Lead creation** → push qualified lead data to your CRM mid-call.
* **Appointment booking** → query calendar availability and confirm a slot.
* **Order or ticket status** → retrieve live information from your backend.

***

#### Attaching Tools to an Agent

From the agent view, scroll to the **Tools** section:

<div data-with-frame="true"><figure><img src="/files/sSmODulTYjRnJWEvEhCM" alt=""><figcaption></figcaption></figure></div>

> 📷 **Image** — Tools (Beta) section on the agent

* Click **+** to create a new tool or attach an existing org tool.
* Click **Import from provider** to bring in tools already configured on the agent's provider — no need to rebuild them manually.

**Import from provider**

If your agent already has tools defined on the provider side, use **Import from provider** to pull them into VoiceB in one click. The import brings the full tool definition — name, description, request method, URL, headers, and parameters — and registers it as a reusable org tool.

From that moment, **VoiceB becomes the source of truth**: edit the tool in VoiceB and the changes are published back to the provider automatically.

{% hint style="info" %}
**Tip:** Import is the recommended path when migrating an existing agent into VoiceB — it guarantees the tool definitions in both systems start perfectly in sync.
{% endhint %}

***

#### Creating a New Tool

When you create a tool, you define **what it does**, **how it's called**, and **what data it sends and receives**.

**Name & Description**

<div data-with-frame="true"><figure><img src="/files/bKwknRuSc0PvbQyPHD9o" alt=""><figcaption></figcaption></figure></div>

> 📷 **Image** — New Tool modal: Name and Description fields

The description (up to **1,200 characters**) is the most important field: it's what the AI reads to decide **when to trigger the tool**.

Example: "Checks if the caller is an existing customer. Call this tool immediately after collecting and confirming the caller's phone number, before offering any product or plan. Send the phone number in international format (e.g. +34612345678). Returns `is_customer` (true/false) and `customer_segment`. If `is_customer` is true, redirect to customer service."

{% hint style="info" %}
**Tip:** Write the description as an **instruction to the agent**, not as internal documentation. State *when* to call it, *what inputs it needs*, and *what it returns*. Vague descriptions lead to tools being triggered too early, too late, or never.
{% endhint %}

**Request**

<div data-with-frame="true"><figure><img src="/files/qWzVl9XEuogn2lBOcq6J" alt=""><figcaption></figcaption></figure></div>

> 📷 **Image** — Request (Method + Webhook URL) and Headers

Define the HTTP call:

* **Method:** `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
* **Webhook URL:** the endpoint of your API or middleware (e.g. Make, n8n, or a direct customer endpoint) — for example `https://api.example.com/v1/customers/lookup`.

**Headers**

Click **+ Add header** to add any headers your endpoint requires — typically authentication and content type. Each header has a key, a mode (**Fixed** or **Variable**), and a value. You can inject stored values with `{{ }}` syntax.

Common examples:

* `Authorization` → `Bearer {{API_KEY}}`
* `Content-Type` → `application/json`

**Parameters**

<div data-with-frame="true"><figure><img src="/files/SSSepFZGXIeeUaazlojT" alt=""><figcaption></figcaption></figure></div>

> 📷 **Image** — Parameters: name, location, type, fill mode, description, allowed values, Required

Parameters define the **data the agent sends** with each call. For each parameter you configure:

* **Location:** `Body`, `Query`, or `Path` — where the value is placed in the request.
* **Type:** `string`, `number`, `integer`, `boolean`, `object`, or `array`.
* **Fill mode** — how the value is populated:
  * **AI-filled** → the agent extracts the value from the conversation.
  * **Variable** → the value is injected from a declared variable using `{{variable}}` syntax.
  * **Fixed** → a constant value you set.
* **Description:** what the field means. The AI uses this to extract and format the value correctly.
* **Allowed values (comma-separated):** restrict the values the AI can send. Use it whenever your backend expects an enum (e.g. `Electricity, Gas`) — it prevents free-text values your CRM won't recognize.
* **Required:** mark it if the tool must never be called without this value. Applies to **AI-filled** and **Variable** parameters (a Variable may be empty if it wasn't provided and has no default). Fixed values are always present.

Example → a customer lookup might send `phone_number` (string, Body, AI-filled, required) and `product_interest` (string, Body, AI-filled, optional, allowed values `Electricity, Gas`).

**Object and array parameters**

<div data-with-frame="true"><figure><img src="/files/5l69RaU43YCKrBnFVfZT" alt=""><figcaption></figcaption></figure></div>

> 📷 **Image** — An `object` parameter with Fields, plus the Variables section

* **Object** types expose a **Fields** list (**+ Add field**). Each field is configured just like a parameter — name, type, fill mode, value, and Required. Use objects to group related data, e.g. a `contact` object holding `lead_id`, `name`, and `phone` populated from variables (`{{lead_id}}`, `{{name}}`, `{{phone}}`).
* **Array** types let you set the **item shape** — the type of each element (`string`, `number`, `integer`, `boolean`, or `object`).

{% hint style="info" %}
**Tip:** Give each parameter a clear, self-explanatory name and description. The AI fills parameter values from the conversation — the better it understands what a field means, the more accurately it extracts and formats the data.
{% endhint %}

**Variables**

Variables let you inject **dynamic values** into the tool — such as data passed via Click to Call Variables or values collected earlier in the call. Declare each variable (e.g. `lead_id`, `name`, `phone`), optionally give it a **default value**, and reference it anywhere in the tool — parameter values, object fields, or header values — with `{{variable}}`. Use them to avoid asking the caller for information you already have.

***

{% hint style="danger" %}
**Alert – Test before going live** Always validate a new tool with a **test call** before attaching it to a production agent: - Confirm the endpoint responds within a conversational latency budget (ideally **< 2 seconds**) — slow tools create awkward silences. - Verify required parameters are actually collected in the script **before** the tool can be triggered. - Check how the agent behaves when the endpoint fails or returns empty — define a fallback path in the script.
{% endhint %}

***

#### Best Practices

* **One tool, one job.** Keep each tool focused on a single action. Composite logic belongs in your middleware, not in the tool definition.
* **Align script and tools.** Reference the tool explicitly in the agent's script ("After confirming the phone number, check if the caller is an existing customer") so triggering is deterministic, not left to chance.
* **Mark critical fields as Required.** This prevents the agent from firing the tool with incomplete data.
* **Reuse org tools.** Centralize shared actions (customer lookup, CRM push) at org level instead of duplicating them per agent.
* **Use Variables for known data.** Map `{{lead_id}}`, `{{name}}`, `{{phone}}` from Click to Call instead of asking the caller again.
* **Handle the "no answer" path.** Every tool call can fail — script what the agent says while waiting and what it does if no result comes back.

***

#### Final Checklist

| :x: Don't                                            | :white\_check\_mark: Do                                              |
| ---------------------------------------------------- | -------------------------------------------------------------------- |
| Write vague descriptions like "checks customer data" | Write instruction-style descriptions: when to call, inputs, outputs  |
| Guess the method or endpoint URL                     | Confirm the correct method and endpoint with your API owner          |
| Send requests without authentication                 | Configure auth headers (`Authorization`, `Content-Type`)             |
| Leave parameters untyped or in the wrong location    | Type every parameter and place it correctly (Body / Query / Path)    |
| Let the agent fire the tool with incomplete data     | Mark critical fields as **Required**                                 |
| Ask the caller for data you already have             | Map **Variables** from Click to Call or earlier in the conversation  |
| Accept slow endpoints that create dead air           | Keep endpoint latency **under 2 seconds**                            |
| Assume the tool always responds                      | Define a **fallback path** in the script for errors or empty results |
| Attach a new tool directly to production             | Validate with a **test call** first                                  |

By [Álvaro Iglesias](https://www.linkedin.com/in/aiglesiasreina/). July 13th 2026.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.voiceb.ai/tools-connect-your-agent-to-external-actions-beta.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.