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

# APIs & MCPs: let your agent act during a call

> What tools are, the three kinds (API requests, MCP servers, web tools), how to attach them to an agent, and what happens when the agent calls one on a call.

Tools let your agent do things during a call: look up an order, book a slot, check a balance, or update the page the caller is looking at. You create tools once in **APIs & MCPs**, then attach them to any agent in the project. This page explains the kinds of tools, how agents use them, and what the caller hears while a tool runs.

![The APIs & MCPs page with API requests, an MCP server and a web tool listed, and the Add new tool menu open showing API request, MCP server and Web tool](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/tools/tools-add-menu-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=d3c1fc37504a384d45af96b9a5ddc8be)

## Kinds of tools

| Kind | What it does | Who runs it | Page |
| - | - | - | - |
| **API request** | Calls one HTTP endpoint of your system with values the agent collected. | Hamsa, from its servers | [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md) |
| **MCP server** | Connects an MCP server. Every function the server offers becomes available to the agent. | Hamsa, from its servers | [Connect an MCP server](https://docs.tryhamsa.com/agents/tools/mcp-servers.md) |
| **Web tool** | Asks your web page to do something, and waits for its answer. | Your page, through the Web SDK | [Web tools](https://docs.tryhamsa.com/agents/tools/web-tools.md) |

Agents also get some tools without you creating them, for example the knowledge base search when **Agentic RAG** is on. See [Knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/overview.md).

## Before you start

* To see **APIs & MCPs** in the sidebar you need permission to view tools. To add tools you need permission to create them. By default Owners, Admins and Users can create and edit tools; only Owners and Admins can delete them. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).
* Have the details of the system you want to call: its URL, how it authenticates, and what it expects in the request.

## Create a tool

**1. Open APIs & MCPs**

In the sidebar, under your agents, click **APIs & MCPs**.

**2. Pick the kind of tool**

Click **Add new tool** and choose **API request**, **MCP server** or **Web tool**.

**3. Fill in the form**

Give the tool a **Tool name** and a **Description**. The agent reads both to decide when to use the tool, so describe what it does and when to call it. Then fill in the settings for that kind of tool.

**4. Save**

Click **Create**. Until you do, the tool is a local **Draft** in your browser, listed above your saved tools. **Discard draft** removes it.

Then attach the tool to an agent (below). A tool that no agent uses does nothing on calls.

## Attach a tool to an agent

How you attach a tool depends on the type of agent.

> [tab] Single prompt agent
>
> **1. Open the agent's Tools section**
>
> In the agent's configuration, find **Tools** ("Connect to external services and APIs.") and click **Manage**.
>
> **2. Select the tools**
>
> In **Select tools**, search or filter by **Type** (**API request**, **MCP server**, **Web tool**) and select the tools the agent may use. Click **Done**.
>
> ![A single prompt agent's Select tools panel with lookup\_order and store\_catalog selected](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/tools/single-prompt-select-tools-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=72280ed70b4ec9a2804f6b79e9abfd2b)
>
> **3. Adjust per agent (optional)**
>
> Under **Tool configuration**, open a tool to change its settings for this agent only, for example to set a parameter to a fixed value or a variable instead of asking the caller.
>
> The agent sees every tool you attach, all the time, and decides from the conversation when to call one.

> [tab] Flow agent
>
> * **API requests**: add a **Tool** step to the flow and pick the tool in **Choose a tool**. The step runs when the call reaches it. See [API request step](https://docs.tryhamsa.com/agents/flow/steps/api-request.md).
> * **Web tools**: add a **Web tool** step and pick the tool in **Choose a web tool**. See [Web tool step](https://docs.tryhamsa.com/agents/flow/steps/web-tool.md).
> * **MCP servers**: open **Global settings**, go to **MCP servers** and click **Add MCP servers**. Their functions are available on every step.
>
> **Global settings** > **Tools** lists every tool the flow calls and the steps that call it. **Locate** shows a step on the canvas.

## How it works on a call

What the agent does with a tool's result differs between the two types of agent.

| | Single prompt agent | Flow agent |
| - | - | - |
| When a tool runs | When the model decides to call it, at any point in the call. | API requests and web tools: when the call reaches the step. MCP functions: when the model decides, on any step. |
| What the agent sees | The full response, which it uses to answer the caller. | The step's result decides the next step (**On success** or **On failure**). Values you extract from the response become [variables](https://docs.tryhamsa.com/agents/variables/extracted-variables.md) for later steps. The model doesn't read the response itself. |
| What the caller hears while it runs | There is no processing message. Hold music plays if the tool has **On hold music** on. | The step's **Processing message**, and hold music if the step has **Put on hold** on. |

On both types of agent:

* **Failures stay out of the conversation.** If a tool can't run (a timeout, a network error, an MCP failure), the agent is told the action couldn't be completed and to continue without mentioning technical problems. The original error stays in the [call details](https://docs.tryhamsa.com/agents/monitor/call-details.md).
* **The caller isn't timed out.** While a tool runs, the agent doesn't count the silence as the caller being away.
* **Hold music** is the agent's own on-hold track from its call settings. A tool doesn't have its own track.

## Manage tools

* **Search and filter.** **Search tools...** matches tool names. Filter by kind (**All**, **APIs**, **MCP**, **Web**), and for APIs by **Method**.
* **Collections.** Group tools with **New collection**, and move a tool with **Move to collection**. Tools in no collection show under **Uncategorized**. Deleting a collection moves its tools to Uncategorized.
* **A tool's page.** Click a tool to see its settings: **ID**, **Status** (**Active** when at least one agent uses it), **Authentication**, **Timeout** and **Runs** (**In the background** or **While the agent waits**). API requests have a **Test** button.
* **Versions.** Every time you save a tool, it gets a new version. Agents keep the version they were set up with. When a newer one exists, the agent's tool shows **Update available**; **Sync to latest** updates the tool definition and keeps your per-agent changes.
* **Delete.** Click **Delete**, type DELETE and confirm. You get a few seconds to undo. You can't delete a tool that an agent uses: remove it from those agents first.

## Good to know

* The **ID** on a tool's page belongs to that version, so it changes each time you save.
* You can't change a tool's kind after you create it.
* **Async execution** makes the agent move on without waiting for the result. On single prompt agents the agent never gets the result; on flow agents the result can still fill the step's variables. See [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md#async-execution).
* Store passwords and API keys as [Secrets](https://docs.tryhamsa.com/agents/tools/secrets.md) instead of typing them into tools.

## Related

> [card] [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md)
>
> Call your own endpoints during a call.

> [card] [Connect an MCP server](https://docs.tryhamsa.com/agents/tools/mcp-servers.md)
>
> Give the agent every function of an MCP server.

> [card] [Web tools](https://docs.tryhamsa.com/agents/tools/web-tools.md)
>
> Let your web page answer the agent.

> [card] [Secrets](https://docs.tryhamsa.com/agents/tools/secrets.md)
>
> Keep credentials out of your tool settings.


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