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

# Tools

> Typed functions that let a skill take action.

Tools are how a skill *does* things. Look up an account, lock a card, place an
order. A tool is a decorated Python function. Drop it in the skill's `tools/`
folder and it's automatically available; the LLM reads its name, description, and
inputs and decides when to call it.

## Defining a tool

```python skills/check_balance/tools.py theme={null}
from rasa.mantle.tools.decorator import ToolContext, tool
from rasa.mantle.tools.result import ToolResult


@tool(description="Look up account balance by account number")
async def check_balance(
    account_number: str,
    context: ToolContext = None,
) -> ToolResult:
    balance = await call_api(account_number)
    return ToolResult(
        llm_response={"balance": balance, "currency": "USD"}
    )
```

The function signature *is* the schema:

* **Name**: the function name (`check_balance`)
* **Description**: the `@tool` decorator argument
* **Inputs**: extracted from the type hints
* **`context`**: injected by the runtime, never visible to the LLM

Tools are **auto-discovered** from the skill's `tools.py` (or a `tools/` folder,
if you'd rather split them across files). No imports, no registration. The LLM
sees the tool and calls it when the instructions call for it.

The tool must be `async`, and the injected parameter must be named exactly
`context`.

## Using a tool in instructions

Reference a tool from the [instructions](https://mantle.rasa.com/concepts/instructions.md) body with
its plain name:

```markdown theme={null}
Ask for their account number, then call check_balance and report
the balance clearly.
```

The tool is already in the model's schema whenever the skill is active: naming
it in prose is guidance about *when* to use it, not a reference the compiler
resolves.

## Sharing state with the skill

Tools read and write [memory](https://mantle.rasa.com/concepts/memory.md) through `context`, so their
results are available to the rest of the skill:

```python theme={null}
context.memory.set("current_plan_id", plan.id)
```

Every key you write must be declared in the skill's `memory.yml` or the
project-root one. `rasa train` rejects an undeclared write.

A tool can also send a message to the user directly, bypassing the LLM. It is a
coroutine, so it must be awaited:

```python theme={null}
await context.send(f"Your balance is ${balance}")
```

## What the user hears while a tool runs

On voice, a slow tool means silence on the line. Before calling a tool, the
model says a short acknowledgement such as "Let me check that for you", so the
caller knows the agent is working. This is on by default for voice and off for
text. Set `fillers.enabled` and `fillers.examples` in
[`agent.yml`](https://mantle.rasa.com/reference/agent-yml#fillers) to change it.

## When a turn is cancelled

On voice, a user can start talking while your tool is still running. The runtime
ends the turn and raises `asyncio.CancelledError` inside your tool at whatever
`await` it is suspended on. Read-only tools can ignore this.

For a tool that changes something, check `context.is_cancelled` before starting
the irreversible step. The check does not undo a request another service has
already accepted, and a cancelled tool can run again on the next turn. Use that
service's idempotency mechanism, and check the outcome of an uncertain request
before retrying. See [Cancellation](https://mantle.rasa.com/reference/tools.md#cancellation).

## Shared tools

Local tools need no declaration. To use a tool defined outside the skill
folder — one in the agent-root `tools/` folder — add `import_tools` to the
frontmatter:

```yaml theme={null}
import_tools:
  - get_customer_info              # shared, from tools/ at the agent root
```

A shared tool that isn't declared is not available to the skill at all.

## Import MCP tools

To call a tool on a remote MCP server, declare the server in
[`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml#mcp_servers), then allowlist
the tool in the skill:

```yaml integrations.yml theme={null}
mcp_servers:
  - name: banking
    url: http://localhost:8000/mcp/
    token: ${MCP_BANKING_TOKEN}
```

```yaml skills/check_balance/skill.md theme={null}
---
name: Check Balance
description: Look up the customer's account balance.
import_tools:
  - mcp/banking:get_balance
---

Ask for the account number if needed, then call @tool.get_balance and report the
result clearly.
```

`import_tools` is an allowlist. A named entry attaches that one tool. The tool
arrives under its bare name (`get_balance`), which is what `tool_constraints`
use. In the body, refer to it as `@tool.get_balance`, the same form as any
other tool.

A pattern attaches every listed tool that matches, so a new tool on the server
is available after a restart or model reload without editing the skill:

```yaml skills/card_replace/skill.md theme={null}
import_tools:
  - mcp/banking:card_*
```

Use a prefix that belongs to one set of tools, and put that pattern on the
skill for that set. `mcp/banking:*` attaches every tool on the server.

A pattern does not name a tool. To write `@tool.card_status` in the body, or to
add a `tool_constraints` entry for it, also import `mcp/banking:card_status`.
The same server keeps the tool once.

If a named import uses a bare name that collides with a local or shared tool in
that skill, train fails. If the server cannot be reached when the agent starts,
startup fails. Which pattern matches are skipped, and which stop startup, is in
the [`skill.md` reference](https://mantle.rasa.com/reference/skill-md#import_tools).

## Adding guarantees

By default the LLM decides when to call a tool, and it can get it wrong. Gate a
tool behind a required value with
[tool constraints](https://mantle.rasa.com/build-guide/tool-constraints.md):

```yaml theme={null}
tool_constraints:
  - check_balance:
      requires: "session.check_balance.account_number"
```

Now `check_balance` is invisible to the LLM until `account_number` is set.

`requires:` is a string expression using the namespaced memory form: see
[Conditions](https://mantle.rasa.com/reference/conditions.md).

When a tool actually runs, Mantle records `tool_executed` with `source` `local`
or `mcp`. For MCP tools, `mcp_server` is the MCP server name (the `mcp_servers:`
key in `integrations.yml`, same id as in `mcp/<server>:<tool>`) so two servers
that expose the same tool name stay distinct. Local tools omit it. See
[Tracker events](https://mantle.rasa.com/reference/execution-loop.md#tracker-events).

## Handing off to another skill from a tool

A tool can end by activating another skill. Return an `ActivateSkill` in
`ToolResult.next`:

```python theme={null}
from rasa.mantle.tools.result import ActivateSkill, ToolResult


@tool(description="Verify the caller's identity")
async def verify_identity(pin: str, context: ToolContext = None) -> ToolResult:
    await check_pin(pin)
    return ToolResult(
        llm_response={"verified": True},
        next=[ActivateSkill(skill_id="account_overview")],
    )
```

The handoff runs after the tool's result is recorded and works like a `call`
step: the current skill waits and continues when the new skill finishes. To
start one ordered block of the skill, pass `ordered_block="<block_id>"`. If
another tool in the same response pauses for `requires_confirmation`, the
handoff waits until the user answers. A decline never runs the paused tool,
so that tool's handoff never applies; a handoff from a tool that already ran
still does. See [`ActivateSkill`](https://mantle.rasa.com/reference/tools#activateskill) for when it
runs and which tools honour it.

To call another tool from a tool, call it as plain Python:
`await other_tool(..., context=context)`.

## Reference

For `ToolContext`, `ToolResult`, invocation modes, tool resolution order, and the
built-in default tools, see the [Tools reference](https://mantle.rasa.com/reference/tools.md).


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