Skip to main content
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

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.
  • @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 (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 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.
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. 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:
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: 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:
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:
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.

context.memory

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 (ProjectMemoryAlreadySetError). YAML set_memory: steps and run_after_setting_* memory validation tools skip an already-set project field only when it is not mutable; mutable fields are overwritten. That skip avoids failing the step so a later collect or a set_memory revision 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-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.
  • A tool that only sends a message or writes memory returns a bare ToolResult().

ActivateSkill

  • 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.
  • 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:
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. 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.

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

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

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:
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.
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. 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. 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_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. 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:
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.

See also