Your tools are an API whose consumer is a model — audit names, descriptions, error contracts, and guards on destructive actions.
Free & open · no signup · read-only — it ends by asking · nothing leaves your machine
You are working inside this repo. Mission: review the tools exposed to your agents as what they are — an API whose consumer is a model — and find where the design invites wrong calls, dead ends, or damage.
Read-only pass. Your only write is the report file.
Phase 2 sweeps the codebase through every one of these, citing file and line for each finding.
names and descriptions that make the model pick the wrong tool or wrong moment
ambiguous types, formats described nowhere, optionals that silently default to something surprising
failures returning actionable text the model can adapt to, vs stack traces, nulls, or silence
too atomic (routine jobs need 12-call chains) or too broad (one mega-tool misused)
delete/send/pay/write tools with no confirmation step, dry-run mode, or undo
two tools doing the same job, chosen inconsistently
hacks in traces or prompts where the agent works around a tool that should exist
tool results dumping thousands of tokens into the window when a summary would serve
One structured report at the repo root — or in reports/, if you keep one — the same shape every time, ready for a teammate — or the optional Studio — to act on.
TOOLS.md already exists from a previous run, read it first and lead with what changed since.Every Goal Prompt follows the same four steps, so results are consistent and repeatable — no matter which one you run.
List every tool/function an agent can call.
Misleading surface — names and descriptions that make the model pick the wrong tool or wrong moment.
Every finding names the failure it produces.
Create TOOLS.md at repo root.
Copy it and paste it into your agent inside the repo you want checked.
Install the goal plugin once — two commands — then just type /goal:tool-design-review.
/plugin marketplace add GhostlyGawd/goal-prompts/plugin install goal@goal-promptsOr install only this Goal Prompt as /goal-tool-design-review:
curl -fsSL https://goal-prompts.vercel.app/install | BRIEF=31 shLet an agent fetch it mid-conversation, or pull the raw Goal Prompt by URL.
https://goal-prompts.vercel.app/raw/31.mdNothing hidden — this is the whole Goal Prompt, verbatim. Read it in a minute, edit it, or copy it as-is.
# Goal: Tool Design Review You are working inside this repo. Mission: review the tools exposed to your agents as what they are — an API whose consumer is a model — and find where the design invites wrong calls, dead ends, or damage. Read-only pass. Your only write is the report file. ## Phase 1 — Inventory the toolbox - List every tool/function an agent can call: name, description, parameters, what actually executes. - Which loops or agents can call which tools; which tools touch the outside world. - If traces exist: which tools get called most, and which calls fail most. ## Phase 2 — Audit through 8 lenses 1. **Misleading surface** — names and descriptions that make the model pick the wrong tool or wrong moment 2. **Parameter footguns** — ambiguous types, formats described nowhere, optionals that silently default to something surprising 3. **Error contract** — failures returning actionable text the model can adapt to, vs stack traces, nulls, or silence 4. **Granularity** — too atomic (routine jobs need 12-call chains) or too broad (one mega-tool misused) 5. **Destructive gaps** — delete/send/pay/write tools with no confirmation step, dry-run mode, or undo 6. **Overlap** — two tools doing the same job, chosen inconsistently 7. **Missing tools** — hacks in traces or prompts where the agent works around a tool that should exist 8. **Return bloat** — tool results dumping thousands of tokens into the window when a summary would serve ## Phase 3 — Curate - Every finding names the failure it produces: wrong call, wasted loop, or real damage - Prefer fixing descriptions and errors first — cheapest lever on agent behavior ## Phase 4 — Report Create `TOOLS.md` at repo root: 1. **Tool table** — name · job · calls the outside world? · risk · issues found 2. **Description rewrites** — worst 3, before/after, ready to paste 3. **Error contract standard** — the one shape every tool failure should return 4. **Guard plan** — which tools get confirms, dry-runs, or scoped permissions 5. **Add/merge/kill list** Start the report with today's date. If `TOOLS.md` already exists from a previous run, read it first and lead with what changed since. ## Rules - Judge tools from the model's seat: only what the description says exists - An error a model can't act on is a dead end, not error handling - No agent tool definitions in this repo? Say so in a one-paragraph null report and stop — a null result is a valid finding. - If a `reports/` directory exists at the repo root, write the report there instead of the root. - Before asking, present the top findings as a ranked list in plain words - Report only — end by asking which changes to make
reports/ directory exists at the repo root, write the report there instead of the root.Every system prompt in the repo: contradictions, dead instructions, bloat, and injection surface — with a consolidation plan.
How runs end — iteration caps, stop conditions, stuck-state detection, and the true cost of one pathological run.
Reconstruct what actually enters the model's window each step — stale payloads, token hogs, retrieval junk, and buried instructions.
The test-gap audit for nondeterminism — golden sets, regression evals, judge quality, and the drift between eval and production.
Runs inside these playbooks — curated sequences you can launch with one paste: