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
skills/check_balance/tools.py
tool and ToolContext come from rasa.mantle.tools.decorator, and
ToolResult from rasa.mantle.tools.result.
Requirements:
- The function must be
async. @tooltakesdescriptionas a keyword argument.@tool(description="…"). A bare@toolwithout it raises.- The return type is
ToolResult. - Name the injected parameter
context. The runtime passes it as the keyword argumentcontext=, and leaves it out of the LLM’s schema.
@tool calls are subject to a wall-clock timeout. Configure it with
tool_timeout in agent.yml (default
10 seconds). MCP tools use the same agent default unless the server sets its
own tool_timeout in integrations.yml.
How the schema is derived
Type mapping:
The generated object sets
additionalProperties: false.
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 skillskills/<id>/, in resolution order:
- Skill-local:
skills/<id>/tools.pyandskills/<id>/tools/*.py. Both locations are scanned; no declaration needed. A name defined intools/*.pyshadows the same name intools.py(logged as a duplicate). - Shared:
tools/*.pyat the agent root. Only tools the skill declares viaimport_toolsare attached to it; an undeclared shared tool is not available to that skill at all. - MCP:
mcp/<server-id>:<tool-name>,mcp/<server-id>:*, ormcp/<server-id>:<prefix>*inimport_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 undermcp_servers.
rasa train. A pattern that later matches that name fails when the agent
starts. See 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 onsys.path, so a lib/
package at the agent root is importable from any tool location:
ToolContext
The runtime constructs one ToolContext per invocation and injects it:
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.
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:
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:
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: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.
context.memory
- a bare name as declared in
memory.yml— resolved against the active skill’s schema first, then the project-rootmemory.yml - a fully-qualified name (
<skill_id>.<entry>orproject.<entry>) — same visibility as conditions / prompt memory: the active skill’s public and private fields, every other skill’s public fields, and project fields.
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.
getreturnsNonewhen the entry is unset, stored asNone, or outside the readable set (for example another skill’sprivatefield) — unless you pass a second argument, which is returned instead. StoredNonecannot be distinguished from never-written, so it also yields that default. It never raises.setwrites through immediately and raisesMemoryWriteErrorwhen the entry is undeclared, the name is a cross-skill write, the name collides with the reservedsystem.*namespace, the writing skill is not listed inwritable_byfor that project field, or aproject.*field is already set and notmutable(ProjectMemoryAlreadySetError). YAMLset_memory:steps andrun_after_setting_*memory validation tools skip an already-set project field only when it is notmutable; mutable fields are overwritten. That skip avoids failing the step so a later collect or aset_memoryrevision is not rolled back.
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.ToolResult
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-blockexecute_tool:steps, memory validation tools) act throughcontext.next: skills to activate once the tool’s result is recorded, in list order. SeeActivateSkill.- A tool that only sends a message or writes memory returns a bare
ToolResult().
ActivateSkill
skill_id: the skill to activate. Withoutordered_block, Mantle enters that skill’s entry, the same targetactivateuses 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 skillcall:s orlink:s. The block id can be anything. See 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.
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
nextapplies, then any handoff that was waiting from the other tools. - Decline. The paused tool never runs, so its
nextnever applies. Handoffs from tools that already ran still apply.
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.
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. Addtool_constraints in the frontmatter to gate one behind a memory
condition:
- A skill-local tool is visible unless it appears in
tool_constraintswith an unmet condition. - A shared tool must be listed in
import_tools; atool_constraintsentry then gates it as well.
Built-in framework tools
These names are reserved. A builder tool that reuses one raises at model load.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:
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.
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.
These results are not preconditions. They are the other ways an
activate call with memory_items ends.
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),
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
completeis withheld while an ordered block is active. The block finishes atEND; a hybrid skill offerscompleteagain after returning to its prose instructions. Do not add a final block instruction that asks the model to callcomplete.- When
completeis offered, it is refused with a tool error while a tool confirmation is pending for the active skill (Mantle resolves it after the LLM callsresolve_tool_confirmation) or when skill-levelcomplete_whencondition or criteria are unmet.cancelis never gated that way. - Once
search_knowledgehas run in a turn, the tool list collapses toactivate,search_knowledge, andcannot_help, plusresolve_tool_confirmationwhen a confirmation is pending.enterandset_memoryare not added. The skill’s own tools andlistenare 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_helpis withheld until a search has run when a knowledge base exists andsearch_knowledgeis still enabled, so the model cannot decline before retrieval could have answered. Turningsearch_knowledgeoff offerscannot_helpimmediately. The references index stays packaged.- If
listenis mixed with text or other tools, the engine ignoreslistenand follows the text and sibling tools. - On a voice collect step,
listenis 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 offerslisten. On text, outside a collect step,listenis 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 offerlisten. listenalone ends the turn with no message. It is the LLM wait tool. Ordered-blockexecute_tool: listenis a separate wait step.hangupis unavailable to the model. To end a conversation, explicitly useexecute_tool: hangupin a skill ordered block after an authored goodbye response.
Tuning built-in tools
orchestrator.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.
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.
Turn complete off only when every skill that would have used it finishes
without the orchestrator: a 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.
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
Whendescription 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:
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 atarget_idfrom the list. Do not invent one. Takes onlytarget_id. To record values, useset_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. Setin_domain=truefor an unsupported request within the agent’s domain andin_domain=falsefor 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.
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 namedrun_after_setting_<entry> validates or derives state after a
memory write. It is not an LLM tool, and it is not a Mantle hook.
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,
or DTMF collect write to that entry.
skills/card_disambiguation/tools.py
- Returning
llm_responsewith a non-nullerrorkey 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 writeproject.*do not run a project-named tool. rasa trainonly accepts the tool when<entry>isllm_settableor collect-owned. A successfulset:button write still runs that tool even when the field is notllm_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 raisesasyncio.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.
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.
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:
await for a cancellation to slip into.
Release resources on cancellation
If your tool holds a resource, catchasyncio.CancelledError, release it, and
re-raise. The turn has already ended, so the runtime discards anything you
return from the handler.
See also
- Tools concept: when to reach for a tool, including MCP imports
- Conditions: the
requires:expression grammar memory.ymlreference: declaring what tools may writeskill.mdreference:import_toolsandtool_constraintsintegrations.yml: MCP server configagent.ymltool_constraints: when a built-in tool is used, and which ones can be turned offagent.yml: default tool-call timeout