---
title: "The agent's tools"
description: "What an agent can do in your systems, where its tools come from, how you choose which ones it uses, what it does before a change and how to ask Arbol for an integration or a private tool."
---

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

# The agent's tools

A **tool** is something the agent can do in another system during a conversation: look up a professional's open slots, book or cancel an appointment, check whether a patient is covered by their insurer, or register a new patient. Without tools, the agent talks and searches your [knowledge base](/en/raiz/knowledge/); with them, it actually gets things done. Read this page when you want to give an agent tools, understand what it did in a conversation, or ask Arbol for a new one.

## How a tool is used in a conversation

"I need a general medicine appointment on Tuesday."

It uses a tool that finds open slots.

It shows the options and waits for the person to choose.

It books with your scheduling system's tool.

It only says it's booked if the system confirmed it.

Every time the agent uses a tool, a card is left in the conversation's transcript, such as "Searched available slots" or "Booked the appointment", with its result (see [Follow conversations](/en/raiz/conversations/)).

## Two kinds of tools

In the Dashboard, each system's tools are split into two groups:

| Group | What they do | Examples |
| --- | --- | --- |
| **Look up information** | Read data without changing anything. | Find open slots, see a patient's appointments, check their coverage or their authorizations. |
| **Make changes** | Create, change or cancel something in your system. | Book, reschedule or cancel an appointment, register a patient, update their details. |

> **Tools act for real**
>
> A tool that **Makes changes** really changes your system, in tests too: if the agent books an appointment in the [test chat](/en/raiz/test-an-agent/), the appointment is created. Give each agent only the tools it needs for its job.

## Where tools come from

An agent can only use tools from the systems your organization has connected. You see them in Account, under **Integrations** (see [See the integrations](/en/account/integrations/)). There are two sources:

### Arbol's integrations

These are systems Arbol already knows how to work with. Arbol's team connects them for your organization and keeps them running. Each **connection** (your organization's account in that system, for example one per site) brings its own tools. Some examples:

| In Account | System | What an agent uses it for |
| --- | --- | --- |
| **From Arbol** | **Agenda** | Your organization's agenda in Arbol: find slots, book, reschedule or cancel appointments, and add people to the waiting list. Included if your organization has Agenda. |
| **From Arbol** | **Contactabilidad** and **Account** | Tools about your own contacts, conversations and agents, and about your organization in Arbol. An agent that serves patients rarely needs them. |
| **Insurers** | **SURA** | Check your patients' coverage, appointments, authorizations and copays, and book or cancel appointments. |
| **Insurers** | **AXA Colpatria** | Check affiliation and authorizations. |
| **Insurers** | **Nueva EPS** | Check affiliation and the assigned primary provider. |
| **Clinical systems** | **Visoft** | Read schedules and availability, register patients, and book or cancel appointments in SIIPS. |
| **Clinical systems** | **gMedic** | Read schedules and availability, and manage patients and appointments. |

EPS is the Colombian health insurer a patient is affiliated with. The exact list of each connection's tools is in Account, behind its tools button, and in Raíz, when you open the integration on an agent.

### Your organization's private tools

If your organization has a system of its own, such as its own scheduling system, health record or CRM, Arbol's team can register it as a **custom server**. Its tools are private: only your organization's agents use them. In Account they show under **Your organization's › Custom servers**, and in Raíz you choose them like any other system's.

- Each of your server's tools is marked as a lookup or a change, and shows in the matching group in the Dashboard.
- Tools that **Make changes** are offered only after Arbol's team confirms the server belongs to your organization. Until then, your agents only see its lookups. In Account, the server's row shows **Writes** with **Offered** or **Not offered**.
- If your server adds or changes tools, Arbol's team updates the list. Then, in Raíz, open the integration on each agent, review the changes and save.
- If one of your server's tools makes changes in another connected system, such as Agenda, tell Arbol's team: the agent treats it with the same care as that system's changes.

## Choose an agent's tools

### Before you start

- You need a role that can **Create and tune agents**, such as **Agent design**, **Administration** or **Owner**.
- The system has to be connected in your organization. If it isn't, ask for it as explained in **Ask for a new integration or tool**, further down.

### Steps

1. In the menu, click **Workers** and open the agent.

2. In the **Work & quality** block, click **Tools and knowledge**. Scroll down to **Integrations**.

3. Click **Add integration**. Under **Your organization's systems**, find the system and click **Add**. You'll see "… added with all its tools".

4. In the **Integrations** list, click the system you added to open its tools. They're split into **Look up information** and **Make changes**.

5. Turn off the tools this agent doesn't need, especially under **Make changes**. You can search with **Search tools** or use **Turn all on** and **Turn all off**. At the bottom you see how many are on, for example "5 of 8 on".

6. Click **Save changes**. You'll see "Tools saved".

> **Adding gives every tool at once**
>
> When you click **Add**, the agent gets all of the system's tools, including the ones that make changes, and can use them from its next reply. If it doesn't need them all, open the integration right away and turn off the extra ones.

### What you see when you're done

Each system shows in **Integrations** with how many tools it has and how many can make changes, for example "8 tools · 2 can make changes". On a voice agent, changes take a few moments to reach calls.

### Remove a system

On the system's row, click the **X** (**Remove …**) and confirm with **Remove**. The agent stops using its tools; you can add it again whenever you want.

### Tell the agent when to use each tool

Giving it a tool isn't enough: write in its [instructions](/en/raiz/write-instructions/), or in a skill (see [Agent settings](/en/raiz/agent-settings/)), when to use it and what to confirm before a change. If you hover over a tool's name in the panel, you see the exact name the agent knows it by; use it if you mention the tool in the instructions.

Use the tools when you need them.

To book: ask for the full name and ID number, look up the service's open slots, offer up to three options and book only the one the person picks. When you're done, repeat the date, the time and the site.

If you give the agent the same tool from several connections, for example **Sede Norte** and **Sede Sur**, the agent picks the connection by its name. Write in its instructions which site fits each case.

> **Contactabilidad and Account tools**
>
> You can only give an agent the **Contactabilidad** or **Account** tools your own role allows. For example, to give it a tool that edits contacts, you have to be able to edit contacts. Otherwise, saving shows "You do not have permission to do this."

## What the agent does before a change

Raíz gives the agent these rules on every channel, on top of the ones you write in its instructions:

- **It acts only on what the person asked for and accepted.** On WhatsApp, if the person writes again before receiving an offer from the agent (for example, some slots), the agent doesn't make the change based on what they wrote: it first shows them the offer and waits for their answer.
- **On calls, it announces the change before making it.** Lookups happen right away. A change is made only after the agent says what it's about to do, for example "I'm booking you for Tuesday at 9:00", so the person can interrupt and correct it. Once it starts, the change isn't interrupted.
- **One change at a time.** The agent makes a change, reads the system's answer and only then decides on the next one.
- **It never says something is done unless the system confirmed it.** If a tool fails, it says so plainly and offers what it can do instead, such as handing the case to your team.
- **If the system rejects a change,** it may correct it once, and only if the system confirmed nothing changed. It never cancels or changes another record to fix it: a different action needs the person's new authorization.
- **If a change couldn't be confirmed,** for example because the system didn't answer in time, the agent doesn't repeat it. It tells the person it couldn't confirm it and makes no other change in that conversation until someone on your team checks in your system whether it went through.
- **If a tool is slow,** on WhatsApp the person gets a single message like "One moment, please, while I check" and the agent keeps waiting for the answer.
- **It never asks for passwords, card numbers or verification codes,** nor for your systems' internal codes: it finds those with its tools.

Instructions and skills don't give the agent tools it hasn't been assigned.

> **Tools in your website's public chat**
>
> In your website's chat, the agent's tools are off until you turn on **Allow agent tools**, because any anonymous visitor could use them. See [Put the chat on your website](/en/raiz/web-chat/).

## Ask for a new integration or tool

Arbol's team connects integrations and registers custom servers. Ask when you need a system that isn't in **Add integration**, or a tool your system doesn't offer yet.

1. Decide who in your organization approves the agent working in that system, usually the **Owner** or whoever runs the area.

2. Write to your Arbol team or to <support@getarbol.com> with:
   - **The system**: its name (an EPS, an insurer, a clinical system or a system of your own) and, if you have several sites or accounts, which ones.
   - **What the agent should do**, in concrete words: what it looks up, what it changes and what it must never do.
   - **Which agents and channels** will use it.
   - **Who approves it**: the name and position of the person who authorizes it.
   - **If it's your own system**: who runs it in your organization or at your vendor, to coordinate the technical side, and whether the system needs to receive files patients send, such as a photo of a doctor's order.

3. Wait for Arbol's team to answer: they tell you what comes next and let you know when the system shows in Account, under **Integrations › Connected**.

4. Add it to the agent, choose its tools and [test it](/en/raiz/test-an-agent/) with made-up data before it serves patients.

Example request:

```text
Subject: New tool for the scheduling agent · Clínica Ejemplo

System: Clínica Ejemplo's own scheduling system. Our vendor runs it;
technical contact: Luis Gómez (example), sistemas@clinicaejemplo.com.

What the agent should do: look up open physiotherapy slots and book
the appointment when the patient picks a slot. It must not cancel or
move appointments.

Agents and channels: "Sofía, recepción", on WhatsApp.

Approved by: Ana Pérez (example), administrative director.
```

> **No passwords or patient data**
>
> Don't put passwords, usernames, codes or patient data in your request. Arbol's team tells you how to proceed.

## What your team sees when a tool fails

**In the conversation.** Each tool card says how it ended. Click the card to see the **Input** (what the agent sent) and the **Output** (what the system answered). They may include patient data.

| On the card | What it means |
| --- | --- |
| Green check (**Succeeded**) | The system answered and the action was completed. |
| **In progress** | The system hasn't answered yet. |
| **Failed** | The system rejected the action or didn't answer. If it was an unconfirmed change, check in your system whether it went through. |
| **Interrupted** | The answer was cut off before it finished. Check in your system whether it went through. |
| **Denied** | Raíz didn't allow the action at that moment, for example because an earlier change was unconfirmed or the person hadn't seen the offer yet. |

**On the agent.** Under **Tools and knowledge › Integrations**, a system with a problem shows a notice: "It's disabled: the agent can't use it.", "It isn't responding. Check the connection in Account.", "It no longer exists. Remove it from this agent." or "Its tools changed. Open it to review them.". While a system isn't working, the agent keeps serving people without its tools.

**In Account.** Under **Integrations**, the connection shows as **Needs attention** (see [See the integrations](/en/account/integrations/)).

**In the reports.** **Reports › Tools** shows how many times each tool was used, how many failed and how long they took on average (see [Reports](/en/raiz/reports/)).

**By email.** If you turned on the **The AI could not answer** notice, your team gets an email when a call or one of its functions fails, or when a WhatsApp reply ends in the fallback message (see [Notices and the daily report](/en/raiz/notifications/)).

## Common problems

Only systems that are connected and active in your organization and have tools show up. If the window says "Your organization hasn't connected any systems yet.", there aren't any yet.

**What to do:** use **Connect in Account** to see in Account what's connected and what's available, and ask Arbol's team for the system as explained in **Ask for a new integration or tool**, on this page.

The tool failed, was denied, or the system didn't have what the person asked for, such as open slots.

**What to do:**

- Open the conversation and click the tool's card to read the **Output**.
- If it says **Failed** in several conversations, check **Reports › Tools** and the connection's status in Account.
- If there were no slots, that isn't a failure: check what the agent offers in that case in its instructions.

The system didn't answer in time and nobody knows whether the change went through. The agent doesn't repeat it so it won't be duplicated.

**What to do:**

1. Look in your system for whether the appointment or the change was recorded.
2. Write to or call the person to confirm how things stand.
3. If the conversation is still open on WhatsApp, handle it yourself (see [Handle a WhatsApp conversation](/en/raiz/take-over-a-conversation/)).

The connection with that system isn't working or is turned off, and the agent can't use it.

**What to do:** write to your Arbol team with the connection's name and your organization's ID, which is under **Settings › Organization** (see [Organization settings](/en/raiz/organization-settings/)).

**Changed**: the tool changed since you saved the agent, which keeps using the previous version. **No longer exists**: the system doesn't offer it anymore, and it will be removed from the agent when you save.

**What to do:** open the integration, review the tools and click **Save changes**. If saving shows "One of the tools no longer exists in your organization's integrations.", review the selection and save again.

Your role can't tune agents, or you're giving it a **Contactabilidad** or **Account** tool your role isn't allowed to use.

**What to do:** ask someone whose role allows it, such as the **Owner**, to make the change.

A custom server's change tools are offered only once Arbol's team confirms the server is your organization's. In Account, its row shows **Writes** with **Not offered**.

**What to do:** ask Arbol's team. Once they're offered, open the integration on the agent, turn on the ones you need and save.

Tools that make changes act for real in your system.

**What to do:**

1. Fix the change in your system and let the person know.
2. If the agent shouldn't make that kind of change, turn that tool off under **Make changes** and save.
3. If it should, but more carefully, write in its instructions what it must confirm first, and test it again.

In the public chat, tools are off until you turn on **Allow agent tools**.

**What to do:** turn it on only if it's appropriate for any visitor to take those actions (see [Put the chat on your website](/en/raiz/web-chat/)).

## For developers

Through the API, an agent's tools are assigned from your organization's integrations and connections. See [Agents](/en/developers/raiz/agents/) and [Integrations](/en/developers/integrations/).

Source: https://docs.getarbol.com/en/raiz/tools/index.mdx