Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/goadesign/goa-ai/agentic-tool-designnpx skills add goadesign/goa-ai --skill agentic-tool-designgit clone --depth 1 https://github.com/goadesign/goa-aiWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/goadesign/goa-ai/agentic-tool-design)<a href="https://agentmods.dev/skills/goadesign/goa-ai/agentic-tool-design"><img src="https://agentmods.dev/badge/skills/goadesign/goa-ai/agentic-tool-design.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00071 | $0.01238 |
| Opus 5 | $0.00036 | $0.00619 |
| Sonnet 5 | $0.00014 | $0.00248 |
| Haiku 4.5 | $0.00007 | $0.00124 |
Grade A, and why
agentic-tool-design scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 5d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 101 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Agentic Tool Design
Overview
Tools are contracts between a deterministic system and a non-deterministic caller. The model's only comparative advantage is language: understanding the question and phrasing the answer. Everything between — retrieval, filtering, date resolution, joining, counting, correlation — is mechanical, and every mechanical step left on the model's side of the contract is a place it can silently be wrong.
Design tools question-shaped, not entity-shaped. An entity-shaped
surface mirrors storage: list handles, dereference handles (list →
get(id)). A question-shaped surface mirrors the caller's job: one
self-contained request in, complete answer-ready evidence out.
The recipe
Design the toolset in this order:
- Enumerate the caller's real questions, not the store's entities. Work backwards from twenty concrete questions users will actually ask.
- One tool per capability seam. A seam is a different corpus, a different side effect, or a different trust level — never a different field projection of the same retrieval. A cost tool, a when tool, and a bring tool are column masks over one query; they belong as fields of one result.
- One call per referent; all projections travel together. If two calls each run retrieval for "the camp trip", nothing guarantees they resolve to the same record — the answer fuses camp A's cost with camp B's date. Return the full dossier (logistics, money, lists, source attribution) in the retrieval result. Token thrift via summary-then- detail splits is almost always premature: measure first; twenty full dossiers is typically a few thousand tokens.
- Pre-compute every mechanical fact in-band. Named date windows
(
this_week,friday) resolved server-side in the right timezone and echoed back resolved; truetotalunder any row cap; sums when numeric fields appear. The model reports arithmetic; it never performs it. - State the corpus's own limits in the envelope. An honest absence
claim ("nothing this weekend") requires the tool to say what was
coverable:
coverage: since <date>, <n> sources. Without it the model will confidently overclaim what the corpus never contained. - Semantic values in, semantic values out. Kid/user/project names
as the model speaks them, resolved against the closed roster server-side;
ambiguity returns a correction listing the real candidates. No UUIDs in
results — when the exit needs grounding, number the evidence (
#1, #2) and let the server map ordinals back to IDs from the run journal. - A validated exit tool. The answer is a tool call whose factual claims must cite evidence ordinals, validated against what the run's tools actually returned; a negative answer is grounded by the journal's record of what was checked, which the model cannot author.
- Errors teach. Every rejectable call returns a correction the model can act on ("'vienna' names a tracked kid — pass kid: 'Vienna'"), never a bare failure.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 5d ago First seen · 101 lines · 71 tokens per session scan A 2c4d560bde3f
agentic-tool-design is a skill published in the GitHub repository goadesign/goa-ai (8 stars, last pushed today), licensed MIT. It adds 71 tokens to every session and 1,238 once invoked, about $0.0004 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
golang-gomlx
Machine learning models training and inference using GoMLX for Go. It provides an abstraction to create vectorized computation graphs, that can then be JIT-compiled (Just-In-Time) and executed very fast, with backends using XLA (for CPU/CUDA/TPU), Go and others. Includes a reach set of vector (tensors) operations on…
code-review-codex
Use the external codex CLI as a second-opinion reviewer for pi-go. This skill is for read-only review and findings, not code editing. The only intended output is ./specs/issues/002-code-review-codex/PROMPT.md.
pi-loop-forensics
Diagnose pi-go agent loops and degenerate turns — "agent loop aborted", runaway thinking with no tool calls, repeated phrases. Discriminates genuine model repetition collapse from a race, a tool-parse failure, or a too-low guard, and A/B replays a seed session across providers.
nightly-session-watch
Nightly sweep of the last 24h of pi-go sessions — anomalous runs, loop aborts, tool error rates, token waste, real prompt-token spend, and whether the observation and palace pipelines are still recording. Triages each finding to the specialist skill that diagnoses it. Use for an unattended daily health check, or on…
migration-helper
Analyze GORM model changes, estimate resulting schema (DDL) differences, and propose safe migration steps with verification guidance.
memory-status
Show MemPalace memory system status — drawer counts, wings, rooms, knowledge graph stats, and embedding model state.