Playbook
Design the ACI
Names, schemas, errors, caps, idempotency, the permission gate. This is the real prompt.
When: You are adding or reviewing tools.
- 01
One job per tool
Split god-tools. Prefer apply_patch over write_file for code. Prefer grep over read-whole-repo.
Designing the Agent-Computer Interface - 02
Design the observation
Success is short. Errors say what to try. Bulk goes to a file with a pointer.
Compaction and Errors - 03
Gate it
Classify allow / ask / deny. Irreversible actions are high-friction asks that pause and resume.
Allow, Ask, Deny
Done when
- Each tool has one job, a verb name, a compact error, a size cap, and a gate class (allow/ask/deny).
Refuse
- Mega-tool. One job per tool. Named verbs. Typed args. Capped results. Idempotent or journaled.
- Double side effects. Idempotency keys, journals, unify state so 'already refunded' is visible to the reducer.
- Silent truncation. Pin the goal. Compact observations. File the rest. Never drop the goal first.