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

# Tools

> Attach tools (e.g. API calls) to your agent - it will use them during the call based on your prompts.

Brosbots lets you attach multiple tools (e.g. API calls) directly to the
agent, in the **Tools** tab. This allows the voice agent to call any internal or external system
during a live conversation - the decision is made by the LLM based on your
prompts.

It works like tool calling on any agent platform and is fully
configurable.

## Where you create tools

Tools are created under **Integrations**. The catalogue opens as one
continuous grid, with the agent tool tiles - **transfer**, **end call** and
your own **HTTP API** - at the front.

An HTTP tool is easiest to build in the wizard: **Integrations** → **Custom**
tab. It goes step by step (address, key, fields, a test against the real API,
picking response fields, caller phrases, agents), has templates and accepts a
pasted cURL command. See [Custom integrations](/en/integrations/custom).

Attach tools to an agent in the wizard (the **Agents** step) or in the
**Tools** tab of the agent editor.

### What the wizard adds

A tool built in the wizard has a few settings the plain form does not. The
full editor (**Advanced**) keeps them:

| Setting | Effect |
| - | - |
| Caller phrases | appended to the tool description the model sees |
| Wait message | said before the API answers (instead of the agent's general phrase) |
| Response fields | the agent gets only the chosen fields of the response (`order.status`, `items.0.name`) |
| Error message | what the agent says when the API fails or does not answer |
| Date and Phone types | values travel as text `YYYY-MM-DD` and `+48600100200` |

## What are tools?

A tool is an action the LLM can invoke during a call. Brosbots supports
four categories:

1. **HTTP API (Custom Webhook)** - call any REST endpoint (your backend, a CRM, external APIs)
2. **Transfer** - hand the call over to a human or another number
3. **End Call** - end the conversation politely
4. **Connected Service** - a pre-built integration, no endpoint to write

**Typical use cases:**

* calling your own backend,
* triggering n8n automations,
* syncing data with a CRM,
* fetching data from external APIs (weather, prices, availability),
* escalating urgent matters to a human agent,
* ending the call after a booking is confirmed.

**The LLM decides:** which tool to call, when, and with what parameters -
based on your prompts, the tool's name, its description and parameter
definitions.

## Tool categories

### HTTP API tool

The most flexible. You define a REST endpoint, method, headers,
authentication and parameters - the LLM builds the payload and calls the
endpoint itself.

### Transfer tool

Hands the ongoing call over to another number. Useful for:

* escalating difficult cases to a human,
* routing calls to the right department,
* forwarding after-hours calls to an on-call number.

Configuration fields:

* **Destination number** - where to transfer the call,
* **Transfer message** - an optional utterance before the transfer
  (e.g. "Connecting you with an agent, please hold."),
* **Parameters** - optional data passed along with the transfer.

Calls can be transferred to **Polish landline and mobile numbers only**.
Foreign, short and premium-rate (70x) numbers cannot be saved, and a call is
never transferred to one. The exception is a call that came from your own
contact centre (e.g. Daktela): it goes back there, so it may also go to an
internal extension or a queue.

The agent only dials numbers set on the agent (the tool's destination
number, the number in the agent's tool settings, or a per-node override).
If the model passes a different number in a parameter, for example one the
caller dictated, it is ignored and the call goes to the configured number.
A transferred call lasts at most 2 hours.

How a transfer goes: the person's phone rings for **30 seconds** while the
caller stays with the agent and hears a ringing tone. When the person picks
up, the call is theirs and the agent drops out. When nobody answers, the line
is busy or the number cannot be reached, the call **comes back to the
agent**: it says that nobody from the team can take the call right now, takes
a message (name, a number to call back on, what it is about) and promises
that someone will call back. The message ends up in the call's transcript and
summary like anything else said on the call.

The transfer cannot be switched on without a number: on the agent's
**Integrations** tab you enter the number first and then turn the switch on,
and saving an agent with the transfer on and no number is refused. When the
transfer fails (for example the number is refused), the agent does not go
quiet - it apologises, takes a message and promises that someone will call
back.

<Note>On Telnyx numbers a transfer also rings for 30 seconds, but it is
"blind": when nobody answers, the call does not come back to the agent.
Returning to the agent works on BrosBots (plfon) numbers and on calls from
your own contact centre (e.g. Daktela).</Note>

<Note>The Transfer tool has no "View Code" option, because it's handled internally by the platform.</Note>

### End Call tool

Politely ends the conversation - usually attached to the End Call node.

### Connected Service tool

A pre-built integration - you define no URL and no headers, you pick a
provider:

* **Weather** - current weather for a given city (no API key needed),
* **CRM contact lookup** - finds a contact in HubSpot by phone number or
  email; you provide the CRM type and an API key. The HubSpot token needs the
  `crm.objects.contacts.read` scope - see
  [Connecting HubSpot](/en/integrations/overview#connecting-hubspot).

You fill in the name, the description (which is what the LLM uses to decide
when to call it) and the parameters the model must supply - e.g. `city` for
weather, or `phone` / `email` for the CRM. Tools in this category have no
"View Code" option, because the platform performs the call itself.

## Defining tools

### 1. Tool name

* Clear and action-oriented, e.g. `capture_lead_interest`, `fetch_weather`, `create_crm_contact`.

### 2. Tool description

* **The most important element** - it's what the LLM uses to decide
  **when** to use the tool.
* Write plainly and unambiguously.

**Bad:**
"API for saving data"

**Good:**
"Tool for flagging interest. Use it when the caller clearly expresses
interest in the product or asks to be contacted."

### 3. Endpoint configuration

* Full URL (**must include `http://` or `https://`**)
* Supported **REST** methods

<Note>A common mistake: a missing https\:// in the URL.</Note>

### 4. Authentication and headers

* Custom authentication and headers
* Works with internal services and external APIs

### 5. Parameters

Each parameter has: a name, type, description and a required/optional
flag.

**Parameter descriptions matter more than types.**

Tips:

* start with string parameters,
* describe unambiguously what the value represents,
* mark as required only truly essential fields.

Example:

* interest (string):
  "Set to true if the caller clearly wants to buy or asks to be contacted. Otherwise false."

## Attaching tools to nodes

* You can attach **multiple tools** to a single node.
* All created tools are available for selection in a node.
* A tool can only be invoked in a node it's attached to.
* The LLM chooses which one to use.

Inside a node, steer the LLM with **simple instructions**, e.g.:

"If the caller wants to talk to sales or asks for a callback, immediately
call the capture\_lead\_interest tool with interest = true."

An instruction like this is often **the deciding factor** in correct tool
usage.

## How the LLM decides to call a tool

The LLM takes into account:

* the intent expressed by the caller,
* the instructions in the node prompt,
* the tool's name and description,
* the parameter descriptions.

When everything is consistent, the tool is called automatically. Weak
names and vague descriptions lead to missed calls, wrong parameters and
made-up values.

## Best practices

* Name tools unambiguously.
* Write detailed, action-oriented descriptions.
* Start with simple parameters.
* Always include http/https in URLs.
* Write node instructions in plain language.
* Attach only the tools a node actually needs.

**Well-defined tools + clear prompts = a reliable, production-grade agent.**


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