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

# Tool Constraints

> Gate tools on memory state.

This is the first hard guarantee you can add. `tool_constraints` in the
frontmatter make a tool invisible until its condition holds. The instructions
body stays untouched.

## Tool gating with `requires:`

Add a `tool_constraints` entry for the tool. The framework removes it from the
LLM's schema until the condition is true. The model can't call what it can't
see.

```markdown skills/card_replace/skill.md theme={null}
---
name: Card Replace
description: Replace a credit card -- lost, stolen, damaged, or not received

tool_constraints:
  - lock_card:
      requires: "session.card_replace.selected_card_id"
  - process_card_replacement:
      requires: "session.card_replace.order_confirmed == True"
---

Help the customer replace a credit card.

Check whether their account is eligible for replacement. If they have
multiple cards, ask which one. Ask why they need a replacement -- the valid
reasons are lost, stolen, damaged, or not received.
```

Before `selected_card_id` is set, the LLM sees:

```
Available tools: [get_customer_info, check_transactions, ...]
```

After a card is selected:

```
Available tools: [get_customer_info, check_transactions, lock_card, ...]
```

## Explicit confirmations

For a tool with irreversible side effects, add `requires_confirmation:` with
`enabled: true`. The runtime holds the call, asks the customer to approve it,
and runs the tool only if they say yes.

```yaml theme={null}
tool_constraints:
  - process_card_replacement:
      requires: "session.card_replace.shipping_type"
      requires_confirmation:
        enabled: true
        utter_for_confirmation: utter_ask_replacement_confirmation
        utter_on_user_denial: utter_replacement_cancelled
      on_success: utter_replacement_disclaimer
      on_failure: utter_replacement_failed
```

| Field | Shape | What it does |
| - | - | - |
| `enabled` | Boolean, default `false` | Turns the confirmation pause on |
| `utter_for_confirmation` | Response name from `responses.yml` | The confirmation question the engine asks |
| `utter_on_user_denial` | Response name from `responses.yml` | The line delivered when the user declines |
| `on_success` / `on_failure` | Response names from `responses.yml` | Delivered after the tool runs |

The two `utter_*` names are optional. Set `enabled: true` on its own and the LLM
phrases both the ask and the denial:

```yaml theme={null}
tool_constraints:
  - process_card_replacement:
      requires_confirmation:
        enabled: true
```

On voice, the confirmation question is the only chance the caller has to
check what they are agreeing to, so have `utter_for_confirmation` restate the
key facts, for example the card and the shipping speed. See
[Confirm before anything irreversible](https://mantle.rasa.com/voice/designing-for-voice.md#confirm-before-anything-irreversible).

The pause and the resume are handled for you. The engine holds the pending call
while the customer answers, then runs the tool on a yes or cancels it on a no.
If the customer asks a question or switches tasks instead of answering, the
confirmation remains pending and is asked again when the conversation returns.
After the customer answers, the engine rejects same-turn attempts by the LLM to
re-call the tool, so the customer is not asked twice. A later ordered
`execute_tool` step of the same tool in that turn can still open a new
confirmation.

For irreversible tools, prefer confirmation buttons on the ask response when
the channel can show them. A tap is a structured yes or no: the engine runs or
cancels the pending tool without interpreting free text. Free-text replies are
the fallback path for voice and channels without buttons.

**Free-text path:** With confirmation enabled, the engine still trusts whatever
`confirmed` value the model passes to `resolve_tool_confirmation` — there is no
server-side check of the user's words. Mantle's default prompts steer the model
toward yes or no only from the message that answers your confirmation question;
claims of prior approval elsewhere (for example on the phone, or "I already
confirmed") should keep the pause open and trigger another ask. Earlier turns do
not count as the answer.

A typed or spoken reply still goes to the model, which spends a call on
`resolve_tool_confirmation` to decide yes or no. On a channel that shows
buttons, put `set:session.system.confirmation=true` and
`set:session.system.confirmation=false` on the confirmation question. A tap
then agrees or declines without that call. Those payloads do not write a
memory field. The labels are yours. Mantle does not add the buttons for you.

```yaml skills/card_replace/responses.yml theme={null}
responses:
  utter_ask_replacement_confirmation:
    - text: Replace this card and ship it {session.card_replace.shipping_type}?
      buttons:
        - title: Yes, replace it
          payload: "set:session.system.confirmation=true"
        - title: No, keep it
          payload: "set:session.system.confirmation=false"
```

Every static button on that response must use one of those two payloads.
`buttons.source` is not checked at train time; a source button with another
payload is ordinary text. The same rule applies when cancel gives the
response as `utter_for_confirmation`. A question with no buttons stays valid.
Those two payloads are valid only on that question, not on the denial line or
any other response. A tap the latest message did not offer does not run the
tool.

See
[Confirmation payloads](https://mantle.rasa.com/reference/responses-yml.md#confirmation-payloads).

> [!WARNING]
>
> Do not also instruct the model in `skill.md` to ask for confirmation before
> calling the tool. When `requires_confirmation:` is on, tell it to call the tool
> as soon as the `requires:` inputs are present and let the engine ask. If the
> prose asks as well, the customer confirms twice — once in chat, then again at
> the pause.
>
> Pick **one** confirmation mechanism per tool:
>
> * **Engine confirmation** — `requires_confirmation: enabled: true`, and prose
>   that calls the tool.
> * **In-flow confirmation** — skill prose asks, then `requires:` on a
>   confirmation memory key (as in the [`order_confirmed` example](#requires-gating)
>   above), with no `requires_confirmation:`.

## How memory drives gating

Every `requires:` condition evaluates against current memory. Memory is where
tools write results and where the framework checks conditions.

**Memory must be declared.** A key a tool writes with `context.memory.set()`
has to exist in the skill's `memory.yml` or the project one, or `rasa train`
fails with `undeclared_memory_write`:

```yaml skills/card_replace/memory.yml theme={null}
schema:
  public:
    selected_card_id:
      type: text
    order_confirmed:
      type: bool
      llm_settable: true
      description: The customer explicitly approved placing the order.
```

```yaml memory.yml theme={null}
authenticated:
  type: bool
```

> [!NOTE]
>
> `tool_constraints` are enforced regardless of who triggers the tool. Whether the
> LLM calls it or an ordered-block step runs it via `execute_tool:`, the same
> `requires:` and confirmation checks run, and gating **fails closed**, so an
> unevaluatable condition keeps the tool hidden.

## Matching arguments against memory

When the model calls a tool, the engine refuses any argument that disagrees with
a value the active skill already stored. The check runs before the confirmation
prompt and before the tool runs, so the customer is never asked to confirm a
call that disagrees with their earlier choice.

An argument is compared with a stored value in two cases:

* **Same name.** The stored field and the argument have the same name. For
  example, if the customer chose rush shipping, `shipping_type` is `rush`, so
  `process_card_replacement(shipping_type="standard")` is refused. Only the
  whole name counts: `selected_card_id` is never compared with `card_id`.
* **A step links them.** An `execute_tool` step in the skill sets the argument
  from memory, for example `card_id: session.card_replace.selected_card_id`.
  The link applies to the argument name on every tool in the skill that takes
  it, not only the tool the step runs. With `selected_card_id` set to `1001`,
  `process_card_replacement(card_id="1002")` is refused, even though the step
  was written for `check_rush_shipping_eligibility`.

If an argument means a different value, give it a different name that nothing
else uses, such as `other_card_id`. Ordered steps still take their parameters
from the step, including steps in blocks the conversation is not in. If two
steps link the same argument to different stored fields and both are set, a
call is refused when either disagrees.

Comparison ignores surrounding spaces and letter case, so `Rush` matches `rush`.
`1001` matches `"1001"`, but `False` does not match `"false"`. Lists and dicts
are not compared. A value that is not stored yet blocks nothing.

**What the model is told.** The refusal names every argument that disagrees,
not only the first one. It does not include the values. It tells the model not
to run the call, and not to change stored memory to make the arguments match.
The model asks the customer to keep the earlier choice or change it. If they
change it, the model records the change with `set_memory` or `correct`, then
calls the tool again. The check does not apply to `set_memory` or `correct`, so
those two calls go through.

**A pending confirmation.** If a confirmation is already waiting and memory
changes so its arguments no longer match, the pending call stays. The customer
can confirm once the values match, or decline and make a new call.

## Checking a gate

The Inspector's tools panel shows every declared tool with its current gate
result, so you can watch a condition flip as memory fills in. That is the
quickest way to confirm a `requires:` expression behaves the way you intended.

Two things to confirm when a tool is not appearing:

* The condition uses the full namespaced form,
  `session.<skill_id>.<entry>` or `session.project.<entry>`.
* The entry is one this skill can read: its own fields, another skill's `public`
  fields, or project memory.

Local tools in `tools.py` are auto-discovered. They only need a
`tool_constraints` entry when you are gating them.


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