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 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/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<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="Reviewed on agentmods" width="80" 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.01225 |
| Opus 5.5 | $0.00028 | $0.00490 |
| Sonnet 5.5 | $0.00014 | $0.00245 |
| Haiku 4.5 | $0.00007 | $0.00122 |
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 13d 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 — 102 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 interprets user intent, relevance, ambiguity, and tradeoffs. Code owns facts derivable from authenticated context, typed contracts, and execution state: identity, authorization, correlation, pagination, exact calculations, and valid transitions. Keep semantic choices model-driven while enforcing their legal shape through the design.
Design tools around the caller's goal. Combine retrieval steps that only
move implementation-owned values between calls. Keep separate operations when
the model genuinely selects a resource or chooses a different capability. A
search followed by get(id) is valid when the search enables that choice.
The recipe
Design the toolset in this order:
- Enumerate the caller's real questions, not the store's entities. Work backwards from representative 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 independently resolve the same project name, they may select different projects. Return related evidence together when the caller needs it. Measure result size and use Goa-AI's bounds and pagination contracts when complete evidence needs more than one page.
- 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. User or project names as the model speaks them, resolved against the closed roster server-side; ambiguity returns a correction listing real candidates. Stable resource identifiers stay visible when the model selects among those candidates. Keep cursors, continuation state, credentials and execution correlation outside model arguments; reuse generated metadata and runtime ownership.
- Validate required answer evidence. When an application requires citations or a typed final answer, define that contract and check it against accepted evidence. Do not assume the framework supplies an evidence-ordinal journal or requires every agent to finish through an exit tool.
- Errors teach. Every rejectable call returns a correction the model can act on, such as the missing field and a valid authored example. Keep authorization failures and unknown tool outcomes distinct from correctable model arguments.
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.
- 13d ago Changed · +1 lines 2855a58cf7f1
- 1mo 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 (9 stars, last pushed today), licensed MIT. It adds 71 tokens to every session and 1,225 once invoked, about $0.0003 per session on Opus 5.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
llm-runtime
Integrate, stream, and orchestrate frontier LLM APIs with robust structured outputs, tool call schemas, prompt caching, and resilient backoff handling. Use when implementing AI agent runtimes, tool-calling loops, streaming SSE endpoints, or optimizing token usage and model latency.
go
Use when writing, reviewing, testing, or shipping Go code and HTTP services: idioms, %w error wrapping, goroutine/context/errgroup concurrency, net/http 1.22 routing, log/slog, project layout, table-driven tests, Go hardening. NOT language-agnostic threat modeling (that is secure-coding), NOT Dockerfile/CI shipping…
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…
memory-status
Show MemPalace memory system status — drawer counts, wings, rooms, knowledge graph stats, and embedding model state.
migration-helper
Analyze GORM model changes, estimate resulting schema (DDL) differences, and propose safe migration steps with verification guidance.