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

skills/check_balance/tools.py

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

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.

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:

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).
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.
MCP: mcp/<server-id>:<tool-name> entries in import_tools. The skill receives only those allowlisted tools; the LLM sees the bare tool name. The server must be declared under mcp_servers.

First match wins among skill-local and shared names. An MCP bare name that collides with a local or shared tool in the same skill fails rasa train — 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:

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)`	coroutine	Send a message to the user immediately, bypassing the LLM
`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
`context.model`	`ToolModelContext`	The project’s LLM settings and knowledge index

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. If the user has already interrupted the turn (voice barge-in), send drops the message.

`context.memory`

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, or a project.* field is already set (ProjectMemoryAlreadySetError). YAML set_memory: steps and run_after_setting_* memory validation tools skip an already-set project field instead of failing the step, so a later collect or correct 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. This is the most common authoring failure. See the memory.yml reference.

`ToolResult`

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.
A tool that only sends a message or writes memory returns a bare ToolResult().

`ActivateSkill`

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 the skill the same way the LLM would: its instructions, or its main block (the first block when there is no main) for a skill made only of blocks.
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, they all run first, then the handoff. If one of those tools paused for requires_confirmation, the handoff waits until the user has answered. A paused tool’s own next runs when the user confirms; a declined tool never runs, so its next never applies. 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 to correct a value 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:

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. 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 flow is startable	Start or switch to a flow (`flow_id` enum, rebuilt each turn)
`complete_skill`	While a skill’s prose instructions are active	Mark the active skill finished when completion gates allow it
`cancel_skill`	While a skill is active	Abandon the active skill
`set_fields`	When the active skill has settable entries	Record one or more memory values in a single batch call
`correct`	When ≥1 earlier value is correctable this turn	Revise a value the user already provided
`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	Retrieve from the knowledge base
`cannot_help`	After a search has run, or immediately when no knowledge base exists	Decline an unsupported request (`in_domain` boolean)
`listen`	Main LLM calls except guided collect, post-search answer calls, and pending tool confirmation	Silent wait: no message, no stack or memory change. Ignored if mixed with text or other tools

Behaviors worth knowing:

complete_skill is withheld while an ordered block is active. The block finishes at END; a hybrid skill offers complete_skill again after returning to its prose instructions. Do not add a final block instruction that asks the model to call complete_skill.
When complete_skill 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_skill 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. 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, so the model cannot decline before retrieval could have answered.
If listen is mixed with text or other tools, the engine ignores listen and follows the text and sibling tools.
Guided collect steps, post-search answer calls, and pending tool confirmation do not offer listen.
listen alone ends the turn with no message. It is the LLM wait tool. Ordered-block action: action_listen is a separate wait step.
hangup is unavailable to the model. To end a conversation, explicitly use action: hangup in a skill ordered block after an authored goodbye response.

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_fields, correct, or static set: button write to that entry.

skills/card_disambiguation/tools.py

@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 voice barge-in, a session timeout, 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. 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. 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:

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.

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})

File Reference

Language

Customizations

Runtime

Observability

Prompts

Schemas

Tools

Defining a tool

How the schema is derived

Where tools are discovered

Importing shared project code

`ToolContext`

`context.memory`

`ToolResult`

`ActivateSkill`

Gating a tool

Built-in framework tools

Memory validation tools

Cancellation

What happens to your tool

Check before irreversible work

Release resources on cancellation

See also

​Defining a tool

​How the schema is derived

​Where tools are discovered

​Importing shared project code

​ToolContext

​context.memory

​ToolResult

​ActivateSkill

​Gating a tool

​Built-in framework tools

​Memory validation tools

​Cancellation

​What happens to your tool

​Check before irreversible work

​Release resources on cancellation

​See also

Defining a tool

How the schema is derived

Where tools are discovered

Importing shared project code

`ToolContext`

`context.memory`

`ToolResult`

`ActivateSkill`

Gating a tool

Built-in framework tools

Memory validation tools

Cancellation

What happens to your tool

Check before irreversible work

Release resources on cancellation

See also