---
title: "Treat tools as named transitions"
lesson_id: "03"
---

# Treat tools as named transitions

- **Lesson ID:** 03
- **Goal:** Let tools propose mode changes and reject illegal ones in app code.
- **Human lesson:** [03-tools-as-transitions.html](03-tools-as-transitions.html)

## Prerequisites

- Lesson 02 Profile switch.

## Inputs, outputs, and artifacts

- **Inputs:** Current mode and a requested next mode.
- **Outputs:** Accept or a blocked reason.

## Agent build steps

1. Write a legal transition table.
2. Implement a switch-mode tool that checks the table.
3. Keep work tools scoped to act.
4. Provide an exit if tool calling is required.

## Constraints

No prompt-only gates. No LangChain. No em dashes.

## Key concepts

- A mode-change tool proposes a next `Mode`. The orchestrator checks the legal table.
- Reject illegal transitions in code, not in the prompt.
- Attach the mode-change tool only in states that may change mode.
- A finish tool that moves to `done` stops required tool loops.

## Takeaways

- Act state exposes the real work tool, not a free-form toolbox.
- Search stays in gather via retrieval or `SpotlightSearchTool`.
- The table is the contract. The model only proposes.

## Acceptance checks

- Table is shown.
- Illegal moves return a blocked string.
- Agent brief link is present.