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