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

# Tools Overview

> Give a voice agent actions it can take mid-call — built-in system tools and your own custom tools

Tools are actions a voice agent can take during a call: hanging up, transferring to a person, searching your knowledge base, or calling your own API. The agent's AI decides **when** to use a tool based on the conversation and the tool's **description** — so a well-written description matters as much as the tool's settings.

Open an agent and go to the **Tools** tab.

![The Tools tab: the System tools list with switches on the left, and the selected tool's settings on the right](https://mintcdn.com/osviai/KMqnCQy0WnU1ttJE/images/Tools/system-tools-Light.png?fit=max\&auto=format\&n=KMqnCQy0WnU1ttJE\&q=85\&s=926cd5f561d88cc596422f08b937716a)

## System tools and custom tools

The Tools tab has two lists:

| | System tools | Custom tools |
| - | - | - |
| **What they are** | Ready-made actions built into Osvi | Calls to your own HTTP endpoint |
| **Examples** | End call, transfer to a human, search the knowledge base | Check an order status, book an appointment, update your CRM |
| **How you add one** | Turn its switch on | Click **Add custom tool** |
| **How many** | One each — except transfers and knowledge base search, which you can add more than once | As many as you need |
| **What you configure** | A few settings per tool, such as the message spoken | The URL, method, headers, query parameters, payload, and the parameters the agent fills in |

Switch between the two lists with the **System tools** and **Custom tools** tabs above the list. The Custom tools tab shows how many you have.

![The Custom tools tab with Add custom tool and one custom tool selected](https://mintcdn.com/osviai/KMqnCQy0WnU1ttJE/images/Tools/custom-tool-Light.png?fit=max\&auto=format\&n=KMqnCQy0WnU1ttJE\&q=85\&s=5ffd2372c34151f368c5268db0a517a4)

* **[System Tools](https://docs.osvi.ai/platform/tools-system.md)** — every built-in tool, what it does on a call, and its settings.
* **[Custom Tools](https://docs.osvi.ai/platform/tools-custom.md)** — how to connect your own API and how requests are built.

If your workspace has the tools library enabled, the Tools tab has a third list, **Library**, for tools shared across agents — see [Library tools](#library-tools) below.

## Library tools

> [!NOTE]
>
> The tools library isn't publicly released yet. Until it is, contact [support@osvi.ai](mailto:support@osvi.ai) to have it enabled for your workspace.

Where system and custom tools belong to one agent, a **library tool** is built once and attached to any number of voice and chat agents. Editing it updates every agent that uses it. Find the library at **Tools** in the sidebar — *"Reusable tools your voice and chat agents can call. Build once, attach to any agent."*

### What's in the library

The Tools page lists every library tool with its type, who created it, and actions. Search by name, or filter by **Type** (Webhook, Integration, MCP, Interactive UI), **Source** (a specific connected app or MCP server), or **Creator**.

**Add tool** offers:

| Option | What it creates |
| - | - |
| **Webhook** | A tool that calls your own HTTP endpoint — the same shape as a [custom tool](https://docs.osvi.ai/platform/tools-custom.md), but shared. |
| **Integration** | Pick a connected app or MCP server, then one of its live actions, to create a tool backed by that [integration](https://docs.osvi.ai/platform/integrations.md). Its identity and parameters come from the source and can't be edited. |
| **Interactive UI** | *(not yet publicly released)* A chat-only visual tool — buttons, a carousel, or a date picker. |

### Attaching a library tool to an agent

On an agent's **Tools** tab, open **Library**. If nothing is attached yet: *"No library tools attached. Tools created on the Tools page can be shared across agents and edited in one place."* Click **Add from library**, or **New from integration…** to create and attach one without leaving the agent.

**Attach library tools** lists every library tool with the same search and type filters as the Tools page; check the ones you want and click **Attach N tool(s)**. A tool whose name collides with one of the agent's own system or custom tools can't be attached — *"This agent already has its own tool with this name."*

Each attached tool has a switch to enable or disable it for that agent without detaching it, and a **Detach** button to remove the reference. Its settings are read-only from the agent page — *"Shared with every agent that attaches it"* — edit it from the Tools page instead.

### Sharing an existing custom tool

An agent's own custom tool can be promoted into the library with **Move to shared tools**: *"It becomes one tool other agents can attach and everyone edits in one place. This agent keeps working — it points at the shared tool from now on."* If a library tool of the same name and type already exists, you're asked to use it, overwrite it, or keep both as separate tools; a name that collides with a different tool type must be renamed.

### Testing a tool

A library tool's settings panel has a **Test tool** button:

* **Preflight** validates and renders the request — method, URL, headers, and body with your test values filled in — without calling the real endpoint.
* **Run for real**, shown once preflight succeeds, sends the request to the actual target after you confirm the call is real and can't be undone. It runs exactly once.

### Archiving

Removing a library tool **archives** it rather than deleting it: *"Agents still referencing it will skip it until you attach a replacement. The tool is archived, not deleted, and its name becomes reusable."*

## Writing tool descriptions

Every tool has a **Name** and a **Description**. The description is the only guidance the agent gets about the tool, so write it as an instruction:

* **When** to use the tool — "Use this when the caller asks for a real person."
* **What to say first**, if anything — "Tell the caller you're checking before calling this tool."
* **What not to do** — "Don't use this for billing questions."

System tools come with a default description you can edit. Spaces in a tool's name are turned into underscores as you type; give each tool a short, unique name.

## Adding, saving, and removing tools

* **Turn a system tool on** with its switch, or click **Add custom tool**. The tool is added to the agent **immediately** with its default settings.
* **Configure it** in the panel on the right and click **Save**.
* **Add another** instance of a transfer or knowledge base search with the **+** button on its card. Rename each instance so their names stay unique.
* **Turn a system tool off** with its switch. A **Disable tool** dialog asks you to confirm — its settings are lost.
* **Delete a custom tool** (or an extra instance) with the trash icon.

> [!WARNING]
>
> Tools go live the moment you add them, before you click **Save**. If the agent is active, finish configuring each new tool and save it before the agent takes calls.

## Tools on new agents

New voice agents start with **End call** and **Detect voicemail** turned on. [Search knowledge base](https://docs.osvi.ai/platform/tools-system.md#search-knowledge-base) appears and disappears on its own as you attach and remove knowledge base documents.

## Multi-prompt agents

* **The Tools tab** sets **global tools**, available in every state of the conversation.
* **Per-state tools** are set in the **Agent** tab's workflow editor: select a state and use the tools section in its side panel. Save the workflow to keep the changes.

![The multi-prompt workflow editor with a state selected and its side panel showing System tools and Custom tools](https://mintcdn.com/osviai/KMqnCQy0WnU1ttJE/images/Tools/multiprompt-Light.png?fit=max\&auto=format\&n=KMqnCQy0WnU1ttJE\&q=85\&s=4e211b255afbbdd906c1ee4ee922ff15)

Selecting a state opens its side panel, with the same **System tools** and **Custom tools** lists as the Tools tab — above, *Search knowledge base* is on for the Starting State. The panel's **Global Node** switch makes the state callable from every other state, for shared sub-flows such as a transfer.

Static-sentence states can't have tools. Don't give a global tool and a state tool the same name.

## Voice and chat

| Tool | Voice agents | Chat agents |
| - | - | - |
| End call, Detect voicemail, Language switch | Yes | — |
| Transfer call to human agent, Warm transfer to human | Yes | — |
| Search knowledge base | Yes | Yes |
| Custom tools | Yes | Yes |
| [Library tools](#library-tools) | Yes | Yes |
| Request human help, operator commands | — | Yes — see [Chat agents](https://docs.osvi.ai/platform/chat-agents.md) |

Tools are configured in the dashboard (or with [Conductor](https://docs.osvi.ai/platform/conductor)); they can't be set up through the API.


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