> ## Documentation Index
> Fetch the complete documentation index at: https://maestro.rasa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> The tool interface and the built-in framework 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

```python skills/check_balance/tools.py theme={null}
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`.

<Note>
  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.
</Note>

## 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.

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:

```python theme={null}
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](#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.

<Note>
  `send` is a coroutine, so await it: `await context.send("One moment…")`.
</Note>

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

```python theme={null}
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.

<Note>
  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](/reference/memory-yml).
</Note>

## `ToolResult`

```python theme={null}
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:

```yaml theme={null}
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](/reference/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.

```python tools/card_hooks.py theme={null}
@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:

```python theme={null}
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.

```python theme={null}
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})
```

## See also

* [Tools concept](/concepts/tools): when to reach for a tool
* [Conditions](/reference/conditions): the `requires:` expression grammar
* [`memory.yml` reference](/reference/memory-yml): declaring what tools may write
* [`skill.md` reference](/reference/skill-md): `import_tools` and `tool_constraints`