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

> The tool interface and the built-in framework tools.

A tool is an `async` Python function decorated with `@tool`. The function
signature is the schema the LLM sees, and there is no separate registration
step.

## 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 the customer's account balance")
async def check_balance(
    account_id: str,
    context: ToolContext = None,
) -> ToolResult:
    balance = await api.get_balance(account_id)
    context.memory.set("current_balance", balance)
    return ToolResult(llm_response={"balance": balance, "currency": "USD"})
```

`tool` and `ToolContext` come from `rasa.mantle.tools.decorator`, and
`ToolResult` from `rasa.mantle.tools.result`.

Requirements:

* The function must be `async`.
* `@tool` takes `description` as a **keyword argument**. `@tool(description="…")`.
  A bare `@tool` without it raises.
* The return type is `ToolResult`.
* Name the injected parameter **`context`**. The runtime passes it as the
  keyword argument `context=`, and leaves it out of the LLM's schema.

Local `@tool` calls are subject to a wall-clock timeout. Configure it with
[`tool_timeout` in `agent.yml`](https://mantle.rasa.com/reference/agent-yml#tool_timeout) (default
`10` seconds). MCP tools use the same agent default unless the server sets its
own `tool_timeout` in [`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml#mcp_servers).

## How the schema is derived

| Schema field | Comes from |
| - | - |
| `name` | The function name |
| `description` | The `description=` argument to `@tool` |
| Property types | Python type annotations |
| `required` | Every annotated parameter with no default |
| *(excluded)* | The `context` parameter never appears in the schema |

Type mapping:

| Annotation | JSON schema |
| - | - |
| `str` | `{"type": "string"}` |
| `int` | `{"type": "integer"}` |
| `float` | `{"type": "number"}` |
| `bool` | `{"type": "boolean"}` |
| `list[str]` | `{"type": "array", "items": {"type": "string"}}` |
| `list` | `{"type": "array"}` |
| `Optional[T]` / `T \| None` | unwrapped to `T` |
| anything else | `{"type": "string"}` |

The generated object sets `additionalProperties: false`.

> [!NOTE]
>
> Each generated property carries its type. Put the meaning of an argument into
> the tool's `description`, or name the parameter so its purpose is obvious.

## Where tools are discovered

For a skill `skills/<id>/`, in resolution order:

1. **Skill-local**: `skills/<id>/tools.py` **and** `skills/<id>/tools/*.py`. Both
   locations are scanned; no declaration needed. A name defined in `tools/*.py`
   shadows the same name in `tools.py` (logged as a duplicate).
2. **Shared**: `tools/*.py` at the agent root. Only tools the skill **declares**
   via `import_tools` are attached to it; an undeclared shared tool is not
   available to that skill at all.
3. **MCP**: `mcp/<server-id>:<tool-name>`, `mcp/<server-id>:*`, or
   `mcp/<server-id>:<prefix>*` in `import_tools`. A named entry attaches that
   tool. A pattern attaches the listed names that match when the agent starts
   or the model reloads. The LLM sees the bare tool name. The server must be
   declared under [`mcp_servers`](https://mantle.rasa.com/reference/integrations-yml#mcp_servers).

First match wins among skill-local and shared names. A concrete MCP import
whose bare name collides with a local or shared tool in the same skill fails
`rasa train`. A pattern that later matches that name fails when the agent
starts. See [`import_tools`](https://mantle.rasa.com/reference/skill-md#import_tools).

When a tool module cannot be imported, `rasa train`
fails. When a referenced MCP server cannot connect, authenticate, or list tools,
agent startup stops with an error naming the failure, so a misconfiguration
surfaces before the first conversation rather than as a missing tool mid-turn.

### Importing shared project code

While tool modules are imported, the project root is on `sys.path`, so a `lib/`
package at the agent root is importable from any tool location:

```python theme={null}
from lib.wallet_data import WALLETS   # works in skills/<id>/tools.py and tools/*.py
```

Do this at **module top level**. The project root is only importable during tool
loading, not later when the tool is dispatched.

## `ToolContext`

The runtime constructs one `ToolContext` per invocation and injects it:

| Member | Type | Description |
| - | - | - |
| `await context.send(text, *, buttons=None, metadata=None)` | coroutine | Send one finished message to the user immediately, bypassing the LLM |
| `async with context.stream(...) as response` | async context manager | Stream a message while the tool is still running. See [Streaming a message](#streaming-a-message) |
| `context.memory` | `MemorySlice` | Scoped read/write access to memory |
| `context.events` | `list[Event]` | A **copy** of the tracker's typed event history |
| `context.is_cancelled` | `bool` | `True` once the turn has been cancelled. See [Cancellation](#cancellation) |
| `context.model` | `ToolModelContext` | The project's LLM settings and knowledge index |
| `context.set_buttons(buttons)` | method | Fill the buttons of a **named response** that called this tool as its button source. See [`context.set_buttons`](#contextset_buttons) |

`context.model` carries two read-only values that are fixed for the loaded
model: `llm_config`, the same provider settings the orchestrator uses from
`integrations.yml`, and `references_index`, the packaged knowledge index (or
`None` when the project ships no reference files). Use it when a tool needs to
run its own model call or query the same knowledge the agent searches.

> [!NOTE]
>
> `send` is a coroutine, so await it: `await context.send("One moment…")`.

`context.events` is a fresh list, so appending to or removing from it does not
touch conversation state. Memory is the only supported write path.

### Sending a message

`await context.send(text)` records one agent message and delivers it at once.

Pass `buttons` to attach choices to that message. Use the same `Button` values
as a [named response's button source](https://mantle.rasa.com/reference/responses-yml.md#dynamic-buttons):
a title, an optional tap value, and an optional memory `ref`. Buttons are
delivered with the text.

Pass `metadata` to add extra fields to the recorded message:

```python theme={null}
await context.send("One moment…", metadata={"campaign": "autumn"})
```

The engine reserves some keys and drops them from this metadata, because it
sets them itself: `agent_message_type`, `utter_action`,
`mantle_response_source`, `llm_time_to_first_token_ms`,
`llm_total_time_ms`, `prompts`, `domain_ground_truth`, `discarded`, `session_id`,
`model_id`, `model_name`, `default_language`, and `assistant_id`. Keys that name parts of the message
are dropped too, because they would replace the text or controls already set: `text`,
`timestamp`, `buttons`, `quick_replies`, `custom`, `image`, `attachment`,
and `elements`. A tool message is still labeled the same way as a plain
`send(text)`.

`context.set_buttons` does **not** decorate `send`. It only fills the buttons
of a named response that invoked this tool as its button source.

If the user has already interrupted the turn (voice barge-in), `send` drops
the whole message. Nothing is recorded and nothing is delivered.

### Streaming a message

Open a stream when the tool should show text as it is generated, for example
from the tool's own model call:

```python theme={null}
from rasa.mantle.tools.buttons import Button

async with context.stream() as response:
    async for token in my_model.tokens():
        await response.write(token)
    response.set_buttons([Button(title="Yes", value="yes")])
```

You can also pass `buttons` and `metadata` to `context.stream(...)`.
`response.set_buttons` and `response.set_metadata` replace those values.
Buttons are sent once, when the block ends, after the text.

On a channel that streams, including voice, each `write` is queued for the
user as soon as the channel accepts it. When a `modify_outgoing_message` hook is
registered, pieces are not sent live. The runtime holds them and sends the
assembled text once, at close, after that hook runs. On a channel that does
not stream, the user receives the full text once, when the block ends. Either
way the conversation stores **one** agent message, not one per piece. An empty
stream records nothing.

Buttons on a finished stream are delivered after the text, without repeating
it. `context.set_buttons` still does not attach buttons to this message.

If the turn is cancelled before any piece is queued, nothing is recorded.
If some text was already queued, further pieces stop, voice playback closes,
and that queued text is recorded **without** the stream's buttons. On voice,
a piece counts once it is queued for playback, which can be before the user
hears it. A tool error after some text was queued does the same, then the
error propagates.

Only one stream may be open. `send` while a stream is open raises. Call
`stream` only inside a turn; outside a turn it raises `LookupError`, same as
`send`.

### `context.set_buttons`

`context.set_buttons` fills the buttons of a named response that called this
tool as its button source. It does not attach buttons to `send` or `stream`.
How to declare that response, and how `Button` fields become a tap payload, is
in [Dynamic buttons](https://mantle.rasa.com/reference/responses-yml.md#dynamic-buttons).

### `context.memory`

```python theme={null}
value = context.memory.get("selected_card_id")   # bare: active skill, then project
cards = context.memory.get("card_list", [])      # unset, None, or unreadable → []
value_from_another_skill = context.memory.get(
    "card_disambiguation.selected_card_id"
)  # fully-qualified: another skill's public field
context.memory.set("selected_card_id", card.id)  # writes memory_set immediately
context.memory.set("project.authenticated", True)  # always project, even if the skill has authenticated
```

For **reads**, use either:

* a **bare** name as declared in `memory.yml` — resolved against the active
  skill's schema first, then the project-root `memory.yml`
* a **fully-qualified** name (`<skill_id>.<entry>` or `project.<entry>`) — same
  visibility as conditions / prompt memory: the active skill's public and
  private fields, every other skill's **public** fields, and project fields.

Do **not** write `session.` prefixes here (that form is for conditions). For
**writes**, use a **bare** name (active skill, then project) or a
**fully-qualified** name for a field this skill may write: `project.<entry>`
always targets project memory (even when the skill declares the same name),
and `<active_skill_id>.<entry>` always targets this skill's field (it does
not fall through to project). Cross-skill writes stay out of scope. Do not
use the internal memory manager or clear memory entries — `rasa data validate`
rejects that. To clear a field this skill owns, use
`context.memory.set(field, None)`. Fields another skill owns must be cleared
from that skill.

* `get` returns `None` when the entry is unset, stored as `None`, or outside
  the readable set (for example another skill's `private` field) — unless you
  pass a second argument, which is returned instead. Stored `None` cannot be
  distinguished from never-written, so it also yields that default. It never
  raises.
* `set` writes through immediately and **raises `MemoryWriteError`** when the
  entry is undeclared, the name is a cross-skill write, the name collides
  with the reserved `system.*` namespace, the writing skill is not listed in
  `writable_by` for that project field, or a `project.*` field is already set
  and not [`mutable`](https://mantle.rasa.com/reference/memory-yml#mutable-and-writable_by)
  (`ProjectMemoryAlreadySetError`). YAML `set_memory:` steps and
  `run_after_setting_*` memory validation tools skip an already-set project
  field **only when it is not** [`mutable`](https://mantle.rasa.com/reference/memory-yml#mutable-and-writable_by);
  mutable fields are overwritten. That skip avoids failing the step so a later
  collect or a `set_memory` revision is not rolled back.

> [!NOTE]
>
> Every key a tool writes must be declared in the skill's `memory.yml` or the
> project-root `memory.yml`. `rasa train` rejects an undeclared write with
> `undeclared_memory_write`. Literal writes to restricted project fields and
> bare names that collide with a project field name are checked at train time; see
> [`mutable` and `writable_by`](https://mantle.rasa.com/reference/memory-yml#mutable-and-writable_by).

## `ToolResult`

```python theme={null}
class ToolResult:
    llm_response: Any = None             # returned to the LLM
    next: list[ActivateSkill] = []       # skills to activate after the tool
```

* **`llm_response`**: any JSON-serialisable value; this is what the LLM reads as
  the tool's result. It is used for LLM-invoked tools; framework-invoked tools
  (ordered-block `execute_tool:` steps, memory validation tools) act through `context`.
* **`next`**: skills to activate once the tool's result is recorded, in list
  order. See [`ActivateSkill`](#activateskill).
* A tool that only sends a message or writes memory returns a bare
  `ToolResult()`.

### `ActivateSkill`

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

return ToolResult(next=[ActivateSkill(skill_id="handoff")])
return ToolResult(next=[ActivateSkill(skill_id="handoff", ordered_block="callback")])
```

* **`skill_id`**: the skill to activate. Without `ordered_block`, Mantle enters
  that skill's entry, the same target `activate` uses for the skill id. A skill
  with prose starts at its instructions. A blocks-only skill starts at its one
  entry block: the ordered block that no other block in the skill `call:`s or
  `link:`s. The block id can be anything. See
  [A skill needs prose or a block](https://mantle.rasa.com/reference/skill-md.md#a-skill-needs-prose-or-a-block).
* **`ordered_block`**: one of that skill's routable ordered blocks. The block
  always starts at its first step.

**When it runs.** After the tool has finished and its result is recorded. If
the LLM called several tools in one response, the tools that are not paused
run first, then the handoff, in list order across those tools.

If one tool in that response pauses for `requires_confirmation`, every
`ActivateSkill` from the response waits until the user answers. Tools that
did not pause still run immediately; only their handoff waits. The paused
tool does not run until the user confirms, so its own `next` exists only then.

* **Confirm.** The paused tool runs, then its `next` applies, then any handoff
  that was waiting from the other tools.
* **Decline.** The paused tool never runs, so its `next` never applies.
  Handoffs from tools that already ran still apply.

When `utter_on_user_denial` is set, that line ends the turn. The new skill is
already on the stack, and its steps run on the next user turn. With no denial
response, the turn continues and those steps run before the turn ends.

**Rules.** An `ActivateSkill` works like a `call` step or an `@skill_id`
reference in prose:

* The current skill waits. When the new skill finishes, the conversation
  returns to where it left off.
* Hidden skills can be targeted, so a skill can be reachable only through a
  tool. Disabled skills and internal blocks (`routable: false`) are refused.
* A skill that is already on the stack is left alone.

**Skipped instructions.** An unknown `skill_id`, an `ordered_block` the skill does not
have, or a refused target is logged as a warning and skipped. At most 10 instructions run per turn;
any beyond that are dropped with an error log. Memory validation tools, `button_source` tools, and tools re-run when the model revises an earlier value with `set_memory` can not set a next skill and will log a warning.

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

## Gating a tool

By default every skill-local tool is visible to the LLM whenever its skill is
active. Add `tool_constraints` in the frontmatter to gate one behind a memory
condition:

```yaml theme={null}
tool_constraints:
  - lock_card:
      requires: "session.card_replace.selected_card_id"
```

The tool stays out of the LLM's schema until the condition holds, and the same
check runs again before the function is called. See
[Conditions](https://mantle.rasa.com/reference/conditions.md).

Visibility rules differ slightly by tier:

* A **skill-local** tool is visible unless it appears in `tool_constraints` with
  an unmet condition.
* A **shared** tool must be listed in `import_tools`; a `tool_constraints` entry
  then gates it as well.

## Built-in framework tools

These names are **reserved**. A builder tool that reuses one raises at model
load.

| Tool | When it is offered | What it does |
| - | - | - |
| `activate` | Whenever at least one skill is startable | Start a skill when none is running, switch to another skill, or resume a paused one. An optional `memory_items` object carries values the user already stated. The allowed ids are skill ids, rebuilt each turn. Ordered blocks are not listed. After a knowledge search the list also includes the running skill |
| `enter` | When the running skill has a same-skill target to move to | Move to a block, a paused block, or the prose of the skill that is already running. A `memory_items` object for that skill is recorded with `set_memory`, even though the schema takes only `target_id`. Not offered after a knowledge search. A call anyway is refused |
| `complete` | While a skill's prose instructions are active | Mark the active skill finished when completion gates allow it |
| `cancel` | While a skill is active | Abandon the active skill |
| `set_memory` | When the active skill has unset entries, or an earlier value can be revised | Record one or more memory values in one call, including one revision of an earlier value. A call with no fields is skipped |
| `resolve_tool_confirmation` | While a tool confirmation is pending | Record the user's approval or denial and resume |
| `search_knowledge` | When a references index was packaged and the tool is still enabled | Retrieve from the knowledge base |
| `cannot_help` | After a search has run, or immediately when search is not available | Decline an unsupported request (`in_domain` boolean) |
| `listen` | Main LLM calls except post-search answer calls and pending tool confirmation. A collect step offers it only on voice, after the question was asked and before the agent speaks this turn | Silent wait: no message, no stack or memory change. Ignored if mixed with text or other tools |

### What each tool is

You do not write these. The orchestrator calls them, and the engine runs them.

#### `activate`

`activate` starts a skill, switches to another one, or resumes a paused one.
The required argument is `target_id`. Its value is a skill id.
Ordered blocks are not listed. A fully guided skill is listed by its skill
id; starting that id opens its entry block. If the model sends
`{skill_id}__{block_id}` for a block of a startable skill, the skill starts
and the block stays closed. A hybrid skill therefore begins in its prose, and
`enter` opens the block once the skill is running. A block id that does not
belong to a startable skill is refused. The allowed ids are rebuilt each turn.

An optional `memory_items` object carries values the user already stated for that
skill. The `memory items:` list under that skill in the routing list shows each
name, type, and description. Text such as `"4"` for an integer or `"Lost"` for `lost` is
converted. A value that does not belong to the skill, or that still fails
the field's type or allowed set, is dropped and does not undo the start. If
the model leaves a value out, the skill asks for it as usual. A memory
validation tool runs when the values are saved. A rejection rolls that value
back and leaves the skill running, and the skill then asks for that value.

A call looks like this:

```json theme={null}
{"target_id": "card_replace", "memory_items": {"reason": "lost", "address": "12 Main Street"}}
```

`reason` and `address` are names from that skill's `memory items:` list. `memory_items` can be omitted when the user has not stated any value yet.

A confirmation or review step is a `collect` step. If `activate` records that field before the step is reached, and the step does not set `ask_before_filling: true`, the engine treats the step as already answered and skips it. A request to proceed, such as "go ahead", is not that answer. Set `ask_before_filling: true` on confirmation and review steps so the question is asked first. `activate` and `set_memory` do not store that field until the question has been asked. The field list `activate` shows for that skill does not include it. A value the block itself wrote, such as an initial value, is still asked about. Until the user answers that question, tool gates that read the field treat it as unset, so a denied confirm cannot open a tool on the offered value. Correcting an earlier answer asks that question again, including when it was still waiting; a value offered with the correction is not treated as the answer.

While `enter` is offered, `activate` refuses a move inside the running skill
and points to `enter`. A `memory_items` object on that refused call is still
recorded with `set_memory`. After a knowledge search, `activate` lists the
running skill by its skill id, so the model can resume it beside its answer.
`set_memory` is withheld on that call, so a `memory_items` object is not recorded
until a later turn.

##### Preconditions

A skill with a `precondition` waits while its `resolve_with` skill runs. The
table shows what happens to the skill and to the values stated on `activate`.

| Situation | What happens |
| - | - |
| No precondition | The skill starts, then the values are saved |
| Precondition already met by saved memory (the skill's own fields are cleared first) | The skill starts, then the values are saved |
| Precondition not met | The skill waits while the `resolve_with` skill runs. The values are kept with it, not saved |
| `activate` is called again while it waits | New values are added to the kept ones |
| The `resolve_with` skill meets the precondition | The skill starts, then the kept values are saved |
| Precondition still not met | The skill and its kept values are dropped, and the model is told |
| The `resolve_with` skill is cancelled | The skill and its kept values are dropped, and the model is told |
| Two skills wait on the same `resolve_with` skill | The skill started last runs first, then the other |
| The next waiting skill needs a different `resolve_with` skill, and that skill cannot start | That waiting skill and its kept values are dropped, and the model is told |
| A field is marked `pii: true` while the skill waits | That value is not kept. The skill asks for it once it is running |

These results are not preconditions. They are the other ways an `activate` call with `memory_items` ends.

| Situation | What happens |
| - | - |
| `activate` names a block of the skill | The skill starts and the block stays closed. `enter` opens it once the skill is running |
| The skill is already running | The values are recorded with `set_memory`, on `activate` or `enter`. After a knowledge search they are not recorded, because `set_memory` is withheld |
| The skill is on the stack under the skill it called | The values are not saved. The model is told to record them once that skill is running again |
| The skill was paused and is resumed | A different value replaces the saved one, as a correction |

This is the skill's precondition. It exists so a value the model just read
from the user cannot open a gate such as authentication. Whether it is met is
decided only from memory that was already saved. Values passed in `memory_items` on
`activate` are not part of that check.
Before the check, the skill's own fields are reset to their defaults, so a
value left by a previous run cannot open the gate, and neither can a value the
user stated. A precondition should not name the skill's own memory fields. If
it does, the check runs on those defaults, so `resolve_with` runs unless the
default already satisfies the check. A `when:` trigger on a kept value runs
when the skill starts, not while it waits.

#### `enter`

`enter` lists a block only when a currently visible instruction names it with
`@block`. An `if:` paragraph whose condition is false does not list that
block. Blocks that are only reachable through `call:` or `link:` are not
listed unless prose also names them. `activate` does not list blocks.

`enter` moves to a block, a paused block, or the prose of the skill that is
already running. Together with `set_memory`, it is how the model changes
the running skill's own state. The argument is `target_id`. A `memory_items`
object for the running skill is recorded with `set_memory`, the same rule as
`activate`. It is offered when that skill has a same-skill target, and
withheld after a knowledge search. A builder tool or MCP tool cannot reuse
the name.

#### `complete`

`complete` marks the active skill finished. It takes no arguments. It is
offered while that skill's prose is active, and withheld while an ordered
block is active, because the block finishes at `END`.

#### `cancel`

`cancel` abandons the active skill. It takes no arguments. Declining an
optional step ("no thanks") is not a cancel.

#### `set_memory`

`set_memory` records memory values the user has already given, in one call.
Each settable field is optional, so a call can set some fields and leave
others unset. A call with no fields does not run. The turn continues, and
the same empty call a second time ends the turn.

The same call revises a value the user already provided earlier. Change at
most one earlier value in that call. If the call changes more than one,
only the first of those arguments is revised; each later one is deferred and
the tool result asks for a separate `set_memory` call, unless the first
revision's rewind cleared that memory item, in which case the later argument
is recorded as an unset item in the same call. Other arguments can record
memory items that are not set yet.
The tool description lists those earlier values apart from the unset memory
items. The active skill's memory items use their bare entry name. A finished sub-skill uses the qualified
memory key while a skill that referenced it is still on the stack.

A revision drops a waiting tool confirmation for the same skill. The model then
calls that tool again to ask with the corrected value.

#### `search_knowledge`

`search_knowledge` looks up the packaged references index. The argument is
`query`, a natural-language question. The orchestrator answers only from what
the search returns.

#### `cannot_help`

`cannot_help` declines a request this agent cannot handle. `in_domain` is true
for an unsupported request inside the agent's domain and false for one outside
it. The engine sends the fixed decline. While a skill is queued behind an open
question (see [`skill.md` `precondition`](https://mantle.rasa.com/reference/skill-md#precondition)),
the first in-domain `cannot_help` of a turn is not declined: the engine
returns a note naming the queued skill and calls the model again, which can
`activate` that skill or call `cannot_help` once more to decline. An
out-of-domain call declines at once.

#### `listen`

`listen` ends the turn with no message, to wait for an answer already asked
for. It takes no arguments. Mixed with text or another tool, the engine
ignores it.

#### `resolve_tool_confirmation`

`resolve_tool_confirmation` records whether the user accepted or declined a
builder tool waiting on `requires_confirmation`. With `confirmed: true` the
engine runs the tool; with `confirmed: false` it cancels. The control is
offered only while a confirmation is pending.

**Free-text confirmations:** The engine does not inspect the user's message when
the model calls this tool — it runs or cancels the pending tool according to
`confirmed`. Mantle's built-in orchestration prompts encourage the model to set
`confirmed` only when the latest user message is a direct yes or no to the
confirmation question; claims of prior approval elsewhere (for example on the
phone, or "I already confirmed") are not treated as consent and typically lead to
a re-ask. For irreversible tools, prefer confirmation buttons on the ask when the
channel supports them — a tap resolves without free-text interpretation.

#### `hangup`

`hangup` ends the conversation. The orchestrator cannot call it. An ordered block
ends the conversation with `execute_tool: hangup` after an authored goodbye.

#### Behaviors worth knowing

* `complete` is withheld while an ordered block is active. The block
  finishes at `END`; a hybrid skill offers `complete` again after returning
  to its prose instructions. Do not add a final block instruction that asks the
  model to call `complete`.
* When `complete` is offered, it is refused with a tool error while a tool
  confirmation is pending for the active skill (Mantle resolves it after the LLM
  calls `resolve_tool_confirmation`) or when skill-level
  [`complete_when`](https://mantle.rasa.com/reference/skill-md#complete_when) condition or criteria
  are unmet. `cancel` is never gated that way.
* Once `search_knowledge` has run in a turn, the tool list collapses to
  `activate`, `search_knowledge`, and `cannot_help`, plus
  `resolve_tool_confirmation` when a confirmation is pending. `enter` and
  `set_memory` are not added. The skill's own tools and `listen` are withheld
  so a grounded answer neither re-drives the skill nor ends silently before
  presenting the retrieved information. They return on the next turn.
* `cannot_help` is withheld until a search has run when a knowledge base exists
  and `search_knowledge` is still enabled, so the model cannot decline before
  retrieval could have answered. Turning `search_knowledge` off offers
  `cannot_help` immediately. The references index stays packaged.
* If `listen` is mixed with text or other tools, the engine ignores `listen`
  and follows the text and sibling tools.
* On a voice collect step, `listen` is offered only after the question was
  asked and before the agent says anything else that turn, so the agent can
  wait for an unfinished answer (for example, the user said the first 4 digits
  of their 16-digit card number and paused). A text collect step never offers
  `listen`. On text, outside a collect step, `listen` is offered only after
  the agent has sent a non-filler message this turn, so it can end the turn
  instead of repeating itself. Post-search answer calls and pending tool
  confirmation never offer `listen`.
* `listen` alone ends the turn with no message. It is the LLM wait tool.
  Ordered-block `execute_tool: listen` is a separate wait step.
* `hangup` is unavailable to the model. To end a conversation, explicitly use
  `execute_tool: hangup` in a skill ordered block after an authored goodbye response.

### Tuning built-in tools

[`orchestrator.tool_constraints`](https://mantle.rasa.com/reference/agent-yml#tool_constraints) in
`agent.yml` sits on top of the offer rules above. Omitting the section keeps
those rules. `enabled: true` does not force a tool onto a turn where the rules
would withhold it. The section is packaged with the model, so a change takes
effect on the next train.

| Tool | Can be turned off | `description` override |
| - | - | - |
| `cancel` | Yes | Replaces the whole offered tool description |
| `complete` | Yes | Replaces the whole offered tool description |
| `search_knowledge` | Yes | Replaces the whole offered tool description |
| `cannot_help` | Yes | Replaces the whole offered tool description |
| `listen` | Yes | Replaces the whole offered tool description (same string on voice and text) |
| `activate` | No | Replaces the whole offered tool description |
| `enter` | No | Replaces the whole offered tool description |
| `set_memory` | No | Replaces the whole offered tool description |

`enabled: false` on `activate`, `enter`, and `set_memory` fails validation.

When to call a built-in tool belongs in that tool's **description** — what the
model sees in the tool list. Optional `tool_constraints.<tool>.description`
fully replaces the engine default for that tool on turns where it is offered.
The **system prompt** still includes fixed instructions the engine adds; they
are not removed when you set `description`, and your override does not appear
there. The model may see both the tool list and the system prompt — keep them
aligned. Details are in [`tool_constraints`](https://mantle.rasa.com/reference/agent-yml#tool_constraints).

Turn `complete` off only when every skill that would have used it finishes
without the orchestrator: a [`complete_when`](https://mantle.rasa.com/reference/skill-md#complete_when)
`condition` with no `criteria`, or an ordered block that reaches `END`.
Otherwise leave the tool on and use `description` if you need different
when-to-call wording. A prose skill that finishes only when the orchestrator
calls `complete` stays open if the tool is off.

`requires_confirmation` is accepted on `cancel` only and rejected on
every other built-in tool. See
[`cancel.requires_confirmation`](https://mantle.rasa.com/reference/agent-yml#cancel-requires_confirmation).

Turning off `search_knowledge` still offers `cannot_help` immediately, even
when a references index was packaged. The index stays. Turning off only
`cannot_help` leaves search and its guidance.

Turning off both `cancel` and `complete` leaves the prompt line
that says a declined optional step ("no thanks", "skip that") is recorded with
`set_memory` and the skill continues.

A call that names a turned-off tool does not run. Turning `listen` off
withholds it from the model. A call that still names `listen` does not end
the turn as a silent wait. Ordered-block `execute_tool: listen` is a
separate wait step and stays available. `hangup` and
`resolve_tool_confirmation` cannot be named in `tool_constraints`.

### Default built-in tool descriptions

When `description` is omitted, the engine uses the defaults below on turns where
the tool is offered. Setting `tool_constraints.<tool>.description` replaces the
**entire** offered string on those turns, including turn-specific suffixes the
engine appends when the key is omitted (noted under each tool). Copy the
published default and merge your text when you customize.

**`activate`**

When `enter` is also offered, the engine appends:

```
 To move inside the running skill, use `enter`.
```

> Start a skill, switch to another (pausing the current one), or resume a paused
> one. Put values the user already stated for that skill in `memory_items`; do
> not invent memory item names.

**`enter`**

> Move within the skill that is already running: open a block its instructions
> name, resume one of its paused blocks, or go back to its main instructions.
> Pass a `target_id` from the list. Do not invent one. Takes only `target_id`.
> To record values, use `set_memory`.

**`search_knowledge`**

> Search the configured knowledge base for information needed to answer the
> user's question. Call this for informational questions before answering; you
> may call it again with a refined query.

**`cannot_help`**

> Decline only when neither the active skill nor any available routable skill
> can fulfil the request.
>
> Requests remain supported when they can be handled from skill instructions,
> conversation context, prior tool results, or currently available tools,
> including contextual follow-ups, comparisons, revised choices or corrections,
> and re-running dependent work.
>
> An active skill does not block a decline when neither that skill nor any
> available routable skill can answer or act.
>
> If the knowledge base lacks an answer to an informational question, say you
> are not certain instead of declining.
>
> Set `in_domain=true` for an unsupported request within the agent's domain and
> `in_domain=false` for one outside it.

**`cancel`**

> Abandon the active skill only when the user clearly cancels the whole task.
> Declining an optional step or follow-up, or asking to return to the task, does
> not cancel it. If the scope is unclear, ask before cancelling.

**`complete`**

> Call it with your closing reply once the skill's work is done and the user has
> the result, including when they say they are done or move on to another topic.
> If the task still needs an answer from the user, do not call it. A reply that
> does not give that answer does not end the task.

**`listen` (text)**

> End the turn without another message when your messages this turn already say
> everything. Call it with no text and no other tool.

**`listen` (voice)**

> Wait without another message: the user's answer is cut off ("and", "uh", part
> of a number, too short), they asked for a moment ("one sec"), or your messages
> this turn already say everything. Do not record a partial answer. Not for a
> complete message, "thanks" included, nor when the user is waiting on you. Call
> it with no text at all, not even an acknowledgement, and no other tool.

A single `tool_constraints.listen.description` applies on **both** REST and
voice turns. When the key is omitted, the engine uses the text or voice default
above.

**`set_memory`**

> Record any of the listed memory items the user has already provided, including
> a decline, in one call. This is not limited to the value being asked for at
> the current step.
>
> Include every listed memory item the user has stated anywhere in the
> conversation so it is not asked for again. Include only values you can
> confidently fill from the conversation so far; omit the rest.
>
> Call it only with at least one value the user stated, and skip the call when
> nothing can be filled.

When the key is omitted, the engine appends one property per settable or
correctable memory item and the correction rule below.

> Change at most one earlier value in this call. A property whose description
> says it is already set holds an earlier value, and that description states the
> current value. If this call changes more than one earlier value, only the
> first of those arguments is revised; send each later one in a later call. Other
> arguments can still record memory items that are not set yet.

## Execute-only tools

`record_handoff` records that a conversation was handed to a human. Studio
analytics use that call for containment and escalation. The tool is a no-op: it does
not speak, write memory, or transfer the user.

Run it from an ordered block. The model is never offered the name, and it is
not one of the built-in framework tools above.

```yaml theme={null}
- id: record_the_handoff
  execute_tool: record_handoff
```

Place the step when the handoff is decided, including when the transfer later
fails. The remaining steps of the skill perform the transfer. See
[Recording a human handoff](https://mantle.rasa.com/reference/ordered-block-steps.md#recording-a-human-handoff).

`tool_constraints` cannot name it. Prose `@tool.record_handoff` and a `tools:`
gate stay unresolved. A skill-local function, shared tool, or MCP import named
`record_handoff` fails training, because the name is reserved for this bundled
tool. A `parameters:` map on the `execute_tool` step fails training too,
including a `session.*` value, because the tool accepts no arguments.

## Memory validation tools

A tool named `run_after_setting_<entry>` validates or derives state after a
memory write. It is not an LLM tool, and it is not a [Mantle hook](https://mantle.rasa.com/reference/hooks.md).
Define it with `@tool` in the skill's `tools.py` (one tool per entry). The
runtime calls it; it is never offered to the model. It runs after a top-level
`set_memory` (including a revision of an earlier value), a static [`set:` button](https://mantle.rasa.com/reference/responses-yml#set-memory-payloads),
or [DTMF collect](https://mantle.rasa.com/reference/ordered-block-steps.md#dtmf) write to that entry.

```python skills/card_disambiguation/tools.py theme={null}
@tool(description="Resolve the chosen card label to an id")
async def run_after_setting_selected_card_label(
    context: ToolContext = None,
) -> ToolResult:
    label = context.memory.get("selected_card_label")
    card = _card_by_label(label, context.memory.get("card_list") or [])
    if card is None:
        return ToolResult(llm_response={"error": "No card matches that label."})
    context.memory.set("selected_card_id", card["id"])
    return ToolResult()
```

* Returning `llm_response` with a **non-null** `error` key rolls the triggering
  write back and surfaces the message to the LLM. `{"error": None}` is success.
* Writes made inside a memory validation tool do not run another one.
* A skill-local `run_after_setting_<field>` tool can write **project** memory
  after a skill field is recorded. Shared or skill tools **named after** a
  project field are invalid at train — the LLM never sets project memory, and
  button taps that write `project.*` do not run a project-named tool.
* `rasa train` only accepts the tool when `<entry>` is `llm_settable` or
  collect-owned. A successful `set:` button write still runs that tool even
  when the field is not `llm_settable`.

## Cancellation

A turn can end while a tool is still running, whether from a session timeout,
a hangup, or a dropped connection. The runtime raises `asyncio.CancelledError`
inside the tool at whatever `await` it is suspended on. There is nothing to
wire up.

A voice barge-in does not cancel a tool. The tool finishes and its result is
recorded, then the agent answers what the caller said. See
[`interruptions`](https://mantle.rasa.com/reference/integrations-yml#interruptions).

Only `await` points are interruptible; synchronous code between them runs to
completion.

### What happens to your tool

When your tool **returns normally**, the runtime records the call and advances
the skill to its next step.

When your tool is **cancelled mid-`await`**, it does neither. The step stays
pending, so the same tool can run again on the next turn. Memory it already
wrote with `context.memory.set(...)` is kept. Text a stream had already queued
is also kept, as one message, without that stream's buttons. On voice, that
can include audio the user has not heard yet. See
[Streaming a message](#streaming-a-message).

That gap matters for a side-effecting tool: your backend may have been called
successfully while the conversation holds no record of it.

### Check before irreversible work

`context.is_cancelled` is `True` once the turn has been cancelled. Check it
immediately before anything you cannot safely repeat, and between consecutive
side effects:

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


@tool(description="Execute a money transfer between accounts")
async def process_transfer(
    amount: float,
    context: ToolContext = None,
) -> ToolResult:
    if context.is_cancelled:
        return ToolResult(llm_response={"ok": False, "reason": "cancelled"})

    await bank.transfer(amount)
    return ToolResult(llm_response={"ok": True})
```

Returning early is clean: the call is recorded and the step advances, with no
further `await` for a cancellation to slip into.

### Release resources on cancellation

If your tool holds a resource, catch `asyncio.CancelledError`, release it, and
**re-raise**. The turn has already ended, so the runtime discards anything you
return from the handler.

```python theme={null}
import asyncio


@tool(description="Stream a statement to the customer")
async def stream_statement(
    account_id: str,
    context: ToolContext = None,
) -> ToolResult:
    client = await bank.open_stream(account_id)
    try:
        data = await client.read_all()
    except asyncio.CancelledError:
        await client.close()
        raise
    return ToolResult(llm_response={"rows": data})
```

## See also

* [Tools concept](https://mantle.rasa.com/concepts/tools.md): when to reach for a tool, including
  [MCP imports](https://mantle.rasa.com/concepts/tools.md#mcp-tools)
* [Conditions](https://mantle.rasa.com/reference/conditions.md): the `requires:` expression grammar
* [`memory.yml` reference](https://mantle.rasa.com/reference/memory-yml): declaring what tools may write
* [`skill.md` reference](https://mantle.rasa.com/reference/skill-md): `import_tools` and `tool_constraints`
* [`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml#mcp_servers): MCP server config
* [`agent.yml` `tool_constraints`](https://mantle.rasa.com/reference/agent-yml#tool_constraints): when a built-in tool is used, and which ones can be turned off
* [`agent.yml`](https://mantle.rasa.com/reference/agent-yml#tool_timeout): default tool-call timeout


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