Skip to content
RasaGet Developer Edition

tutorial

Chapter 3 of 10

Chapter 3 — First tool

by Rod Rivera Published

Add check_itinerary with Mantle @tool functions backed by a demo SQLite database.

Goal

Atlas can list Maya Chen’s bookings by calling tools — not inventing itineraries.

Teach

Tools are async Python functions. Default to skill-local tools: drop them in skills/<name>/tools.py and they are auto-discovered while that skill is active. No registration.

Put a tool in the project-root tools/ folder only when two or more skills need the same function, and list it under import_tools on each skill that uses it.

In this chapter the shared helpers are intentional:

  • load_customer_profile — also used by intro, authenticate, and human_handoff
  • list_bookings — also used by find_booking and report_baggage

Later chapters move skill-owned tools (PIN verify, flight status, cancel, baggage submit) into each skill’s own tools.py.

from rasa.mantle.tools.decorator import ToolContext, tool
from rasa.mantle.tools.result import ToolResult

@tool(description="List the traveler's upcoming bookings and trip summaries.")
async def list_bookings(context: ToolContext = None) -> ToolResult:
    ...
    return ToolResult(llm_response={"ok": True, "bookings": bookings})
  • Function name → tool name
  • Type hints → input schema
  • context is injected by the runtime (not shown to the LLM); the parameter must be named exactly context
  • Structured data returns in ToolResult.llm_response
  • Name the tool in prose by its plain name: “call list_bookings”

Paste

Paste set: tutorial/snippets/step-02-itinerary/

Copy:

  • skills/check_itinerary/skill.md
  • tools/travel.py (shared: load_customer_profile, list_bookings)
  • lib/database.py
  • lib/tool_helpers.py
  • data/source/*.json

Demo traveler: Maya Chen (id 456). Useful booking: HT12345 (Lisbon). The intro skill loads her profile on greet; booking tools also fall back to id 456 from SQLite.

make show-demo-data

Skill instructions

---
name: check_itinerary
description: >
  List the traveler's upcoming trips and booking details.
import_tools:
  - load_customer_profile
  - list_bookings
---

Help the traveler review their itinerary.
If customer details are missing, call load_customer_profile.
Then call list_bookings and summarize each trip in short spoken sentences.
Speak booking references character by character.

Train and try

make train
make inspect

Try: “What trips do I have?”

Verify: Atlas lists Lisbon and Tokyo trips with spoken booking references (for example H T one two three four five).

Talking point

Side effects and lookups belong in tools. Skills orchestrate conversation around tool results. Keep tools local unless sharing is real.

Next

Chapter 4 — Tool constraints