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.calm_v2.tools.decorator import ToolContext, tool
from rasa.calm_v2.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.calm_v2.tools.decorator, and ToolResult from rasa.calm_v2.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.

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.

First match wins; skill-local beats shared. __init__.py is skipped. When a tool module cannot be imported, the model load stops with a ToolLoadingError naming that file, so an import mistake surfaces at load rather than as a missing tool mid-conversation.

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
value_from_another_skill = context.memory.get(
    "card_disambiguate.selected_card_id"
)  # fully-qualified: another skill's public field
context.memory.set("selected_card_id", card.id)  # writes a SlotSet immediately

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, minus the active skill’s access.deny_read

Do not write session. prefixes here (that form is for conditions). Cross-skill writes stay out of scope: set only accepts bare names for the active skill or project.

get returns None when the entry is unset, outside the readable set (for example another skill’s private field), or when the skill’s access.deny_read blocks it. It never raises.
set writes through immediately and raises MemoryWriteError when the entry is undeclared, deny_write blocks it, the field is immutable, or the name collides with the reserved system.* namespace.

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

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, post-write hooks) act through context.
A tool that only sends a message or writes memory returns a bare ToolResult().

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.project.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 is active	Mark the active skill finished
`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)

Two behaviors worth knowing:

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 are withheld so a grounded answer does not re-drive the skill, and 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.

Post-write hooks

A tool named run_after_setting_<entry> is an internal hook, not an LLM tool. It is never offered to the model. The runtime calls it after a top-level set_fields or correct write to that entry, so you can validate the value or derive state from it.

tools/card_hooks.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 hook do not re-trigger hooks.
A hook in the agent-root tools/ folder is available to every skill without import_tools, because an llm_settable project field can be written from any skill.

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.calm_v2.tools.decorator import ToolContext, tool
from rasa.calm_v2.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

Runtime

Prompts

Tools

Defining a tool

How the schema is derived

Where tools are discovered

Importing shared project code

`ToolContext`

`context.memory`

`ToolResult`

Gating a tool

Built-in framework tools

Post-write hooks

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

​Gating a tool

​Built-in framework tools

​Post-write hooks

​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`

Gating a tool

Built-in framework tools

Post-write hooks

Cancellation

What happens to your tool

Check before irreversible work

Release resources on cancellation

See also