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

# Tool step: call an API from your flow

> Call one of your API tools from a flow with a Tool step: pick the tool, set its parameters, save values from the response and route on success or failure.

A Tool step calls one of your API tools at a fixed point in the flow: look up an order, check availability, create a booking. It sends the request, saves the values you need from the response, and moves on through **On Success** or **On Failure**.

## Before you start

Create the API tool first, in **APIs & MCPs**. The Tool step runs a saved tool, which you can adjust for this step. See [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md).

## Add a Tool step

**1. Add the step**

On the canvas, click **Add node** and choose **Tool** ("Execute pre-configured tools").

**2. Pick the tool**

On the step's card, click **Select a tool**. In **Choose a tool** ("The API this step calls."), pick one of your API tools. Until you do, saving shows "Please select a tool for this node to use".

![The Choose a tool dialog listing lookup\_order and five more API tools, each with its method, and filters for Any, GET, POST, PUT, PATCH and DELETE](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/tool-picker-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=32f5956b558dbda15c5acfc64c23320b)

**3. Set its parameters**

In the panel, open **Tool configuration** and decide where each parameter's value comes from.

**4. Save values from the response**

Open **Variables**, click **Add variable**, choose **Tool response variable** and give its **JSON path**.

**5. Connect both outcomes**

Connect **On Success** and **On Failure** to their next steps.

If you have no API tools yet, the picker shows "No tools yet" with **Open Tools**, which takes you to **APIs & MCPs**.

### Find a tool in the picker

* **Search by name or description** narrows the list as you type.
* When your project has tool [collections](https://docs.tryhamsa.com/agents/tools/overview.md#manage-tools), a menu next to the search box shows one collection at a time: **All tools**, a collection, or **Uncategorized**.
* The method filter (**Any**, **GET**, **POST**, **PUT**, **PATCH**, **DELETE**) shows only tools that use that method. A method none of your tools use is greyed out.
* The tool the step uses now is marked **On this step**. **Remove from step** takes it off the step. Tools set to run asynchronously have an **Async** badge.
* The footer counts the tools, for example "6 tools".

![The Choose a tool dialog with the collection menu on All tools, the POST method filter on, and two POST tools listed: create\_return and send\_tracking\_sms](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/tool-picker-filters-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=c542e319c191c7ba0af432c28087df4e)

## Fields

| Field | What it does | Default |
| - | - | - |
| **Processing message** | What the agent says while the request runs, such as "One moment while I check that." **Static** speaks your text; **Prompt** lets the agent write it ("AI will generate an appropriate processing message"). Leave it empty to say nothing. | **Static**, empty |
| **Put on hold** | "Put the user on hold while the tool is executing": the caller hears the agent's [on-hold music](https://docs.tryhamsa.com/agents/settings/call-behavior.md#pick-or-upload-a-track). | The tool's own **On hold music** setting |

![The Look up order Tool step panel: Processing message, Put on hold, and the Transitions, Test tool, Tool configuration, Variables and Global sections](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/tool-step-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=8373593e2b855c4e855ff3f8ac7e80d6)

## Tool configuration

**Tool configuration** changes how the tool behaves on this step only. The tool itself stays as it is in **APIs & MCPs**. Each changed field has **Restore** to go back to the tool's value.

| Group | What you can change |
| - | - |
| **Tool display** | **Tool name** and **Tool description** for this step. |
| **URL & method configuration** | The **URL** and **HTTP method**. |
| **Async execution** | **Execute tool asynchronously**: the flow moves on without waiting for the response. See [Async tools](#async-tools). |
| **Auth type** and **Auth token** | **No authentication**, **Bearer token** or **Token**, with the token for this step. **Insert secret** adds a stored [secret](https://docs.tryhamsa.com/agents/tools/secrets.md). **Basic authentication** can only be set on the tool itself. |
| **Array body** | The JSON array sent as the request body, for tools that send one. |
| **Parameters** | Where each parameter's value comes from (below), plus **Custom parameters** for this step only. |
| **HTTP headers** | Add or change headers for this call, or **Disable** a header to leave it out of the call. |

Under **Available parameters**, each parameter shows where its value comes from:

* **AI extraction** ("Value will be automatically extracted from conversation"): the agent fills it from the conversation. This is the default.
* **Override**: click it and a **Value** field opens. Type a fixed value, such as `en`, or insert a variable with `{{variable_name}}`, such as one the caller gave earlier or a value passed when the call started. You can mix the two. Click **Remove** to go back to AI extraction.
* **Disable**: leaves the parameter out of the call completely. The agent isn't asked for it, and it isn't sent in the request. Click **Enable** to bring it back. **Test tool** leaves it out too.

![The order\_id parameter under Available parameters, overridden: its Value field holds \{\{order\_id}}, with the Remove button and a tip on inserting variables](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/tool-parameter-override-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=0f8e1a19c6a53c915e40ce141ced1601)

![The Parameters part of Tool configuration, with the order\_id parameter set to AI extraction and its Override button](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/tool-configuration-parameters-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=30b5294407cc0a9f382ddc9f7d02f94a)

**AI extraction** works only when the call reaches the Tool step through a **Prompt** transition: the agent fills the values as it decides to move on. When the step is reached from a Router, another Tool or Web tool step, a **DTMF input** or **Auto** transition, or an **On Failure** path, there's no conversation turn to fill them from. The panel shows a **Value** field for those parameters, marked **Manual value required** on required ones, and saving shows "This tool node requires parameter overrides because it is connected from a Router, Tool, or DTMF transition. Please configure at least one parameter override."

## Test the tool

Open **Test tool** ("Execute this tool with sample parameters to validate response and extraction paths") and click **Open test tool**. Fill in sample values, click **Execute test**, and review the response. The result is saved with the flow and used to check your JSON paths.

## Save values from the response

In **Variables**, add a **Tool response variable** for each value you need. Its **JSON path** says where the value is in the response body: `$` stands for the whole body, and `result` means the same thing.

| Response body | JSON path | Value saved |
| - | - | - |
| `{"order": {"status": "shipped"}}` | `$.order.status` or `result.order.status` | `shipped` |
| `[{"name": "Lina"}]` | `$[0].name` | `Lina` |

![A Tool response variable named days\_late with the JSON path \$.order.days\_late](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/tool-response-variable-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=9a743e68104bc97d7955cd167aae288d)

Leaving the path empty shows "Please specify the JSON path to extract this value". You can also add a **Local variable**. **Variable on node exit** isn't available on a Tool step: "Only available in conversation nodes".

## Transitions

| Transition | Taken when |
| - | - |
| **On Success** | The API answers with a 2xx status. |
| **On Failure** | The API answers with any other status, can't be reached, or doesn't answer within the tool's **Timeout**. |

Both are created with the step and can't be removed.

You can also add **Skip if** to this step: when its conditions already hold as the call arrives, the call goes straight to its target and the step doesn't run. See [Skip if](https://docs.tryhamsa.com/agents/flow/transitions.md#skip-if).

## Async tools

With **Execute tool asynchronously** on, the step has a single **Move to** transition instead of **On Success** and **On Failure**. Turning it on or off opens **Change async execution mode**, which replaces the transitions and clears their connections.

On a call, the request is sent and the flow moves on right away. The response isn't used: no response variables are saved and no path depends on it. Use async for requests whose answer you don't need, such as logging a call or sending a notification.

## How it works on a call

**1. Local variables are set**

Any **Local variable** on the step gets its value first.

**2. The processing message starts**

Without **Put on hold**, the request is sent while it plays. It's skipped if another processing message is playing or ended less than 5 seconds ago, so back to back tools don't repeat "one moment".

**3. Hold music starts, if Put on hold is on**

It starts after the processing message ends, and then the request is sent. The agent keeps listening, and keeps what the caller says for the next step that speaks.

**4. The request is sent**

The flow waits up to the tool's **Timeout** for the response: the step's own **Timeout (seconds)** in **Tool configuration** if set, otherwise the tool's (5 seconds by default).

**5. The call moves on**

A 2xx response takes **On Success** and saves your response variables. Anything else takes **On Failure**.

The agent doesn't say anything about the result by itself. To tell the caller what happened, connect the step to a [Conversation step](https://docs.tryhamsa.com/agents/flow/steps/conversation.md) that uses the saved variables. Hold music stops when the next step speaks, not when the request ends.

There's no automatic retry. To try again, connect **On Failure** to a step that offers another attempt.

## Related

> [card] [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md)
>
> Create the tool this step calls.

> [card] [Router step](https://docs.tryhamsa.com/agents/flow/steps/router.md)
>
> Branch on the values the API returned.

> [card] [Variables](https://docs.tryhamsa.com/agents/variables/overview.md)
>
> Use response values in later steps.

> [card] [Web tool step](https://docs.tryhamsa.com/agents/flow/steps/web-tool.md)
>
> Run a tool in the caller's browser instead.


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