Tools — Connect Your Agent to External Actions (Beta)

By Álvaro Iglesias. July 13th 2026

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.

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.

---

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:

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

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.

---

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

📷 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. [phone]). Returns is_customer (true/false) and customer_segment. If is_customer is true, redirect to customer service."

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.

Request

📷 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

📷 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

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

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.

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.

---

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.

---

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

❌ Don't	✅ 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. July 13th 2026.