new-tool

---
name: new-tool
description: Add a new tool to Waku the right way — schema, safe execution, deterministic eval, honest output. Use when adding or modifying agent tools or when the user asks for a new capability.
---

## Procedure

1. One file per tool in `waku/tools/`, exposing `make_tool(...) -> Tool`.
   Copy the shape of `waku/tools/calendar.py` (the reference implementation).
2. The tool function must be:
   - **Idempotent** where repeat calls could occur (check-before-insert, like
     create_event's title+start guard).
   - **Honest in its return string**: say exactly where the artifact went
     (file path, table) and how the user can see it. Never imply effects the
     tool doesn't have.
   - **Local-first by default**: write to `.waku/` or state.db; real external
     services go behind env-gated adapters.
3. Register it in `waku/tools/__init__.py:build_registry`.
4. Add deterministic eval coverage in `evals/deterministic/`:
   - offline: scripted client fires the tool → assert the artifact (DB row/file)
   - a dataset case in `evals/dataset.jsonl` for the live tier
5. If the tool needs usage guidance, add a rule to DEFAULT_SOUL
   (`waku/runtime/session.py`) or a skill in `skills/`.
6. Check scope first: the repo ships flagship-task tools only. New capabilities
   beyond scheduling/notes/messages should be discussed before building.