# New Tool

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

- Skill: `shenseanchen/new-tool` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shenseanchen/new-tool`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shenseanchen/new-tool/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ShenSeanChen (https://skillmd.com/u/shenseanchen)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/shenseanchen/new-tool

---


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