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.
skills/card_replace/skill.md
selected_card_id is set, the LLM sees:
Explicit confirmations
For a tool with irreversible side effects, addrequires_confirmation: with
enabled: true. The runtime holds the call, asks the customer to approve it,
and runs the tool only if they say yes.
The two
utter_* names are optional. Set enabled: true on its own and the LLM
phrases both the ask and the denial:
utter_for_confirmation restate the
key facts, for example the card and the shipping speed. See
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.
skills/card_replace/responses.yml
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.
How memory drives gating
Everyrequires: 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:
skills/card_replace/memory.yml
memory.yml
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_typeisrush, soprocess_card_replacement(shipping_type="standard")is refused. Only the whole name counts:selected_card_idis never compared withcard_id. - A step links them. An
execute_toolstep in the skill sets the argument from memory, for examplecard_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. Withselected_card_idset to1001,process_card_replacement(card_id="1002")is refused, even though the step was written forcheck_rush_shipping_eligibility.
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 arequires: 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>orsession.project.<entry>. - The entry is one this skill can read: its own fields, another skill’s
publicfields, or project memory.
tools.py are auto-discovered. They only need a
tool_constraints entry when you are gating them.