# Agentic Tool Design

> Use when designing or reviewing the tools an LLM agent will call — choosing tool boundaries, argument and result shapes, retrieval/search/get decompositions, MCP or goa-ai toolset surfaces — or when an agent misuses existing tools (wrong tool picked, IDs carried between calls, wrong dates computed, confident answers about absent data).

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

---


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

1. **Enumerate the caller's real questions**, not the store's entities.
   Work backwards from twenty concrete questions users will actually ask.
2. **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.
3. **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.
4. **Pre-compute every mechanical fact in-band.** Named date windows
   (`this_week`, `friday`) resolved server-side in the right timezone and
   echoed back resolved; true `total` under any row cap; sums when numeric
   fields appear. The model reports arithmetic; it never performs it.
5. **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.
6. **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.
7. **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.
8. **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.

## The placement principle

**Put model intelligence where its mistakes are loud.** Wrong arguments
fail loudly and corrections teach mid-run. Wrong *tool selection* among
overlapping tools succeeds silently — the when-tool returns *a* date and
nobody errors. So: few tools with rich arguments over many tools with thin
ones, and overlap between tool descriptions is a defect, not a convenience.

## Boundary test

If the model must remember anything between two tool calls — an ID, a
filter it already passed, which record it meant — the boundary is drawn
wrong. Each call self-contained; each result answer-ready.

## Quick reference

| Symptom in a design | Defect | Fix |
|---|---|---|
| `get_x(id)` after `list_x`/`search_x` | ID plumbing | Retrieval returns full dossiers |
| Two retrieval tools accepting the same filters | Overlap → silent mispick | One tool per corpus; split only on capability seams |
| Model computes dates, counts, or sums | Mechanical work on the model | Named windows, `total`, `sums` in the envelope |
| Empty result ⇒ model says "there is none" | Unbounded absence claim | `coverage` bounds + journal-grounded negatives |
| UUIDs in results or citations | Correlation on the model | Ordinal references; server owns the mapping |
| "cost_of", "when_is", "who_sent" tools | Projections dressed as tools | Fields of one dossier |
| Retrieval matches titles only | Recall gap for prose questions | Match bodies too; return the matched quote as evidence |

## When many tools ARE right

Splitting is correct across genuine capability seams: read vs. mutate
(side effects are the strongest seam), different corpora (structured
records vs. raw source text), different cost/latency tiers, different
permission levels. Selection between *disjoint* capabilities is a decision
models make well; selection between overlapping projections is not.

## Evals arbitrate

Every rule above is testable: score answer-correctness per question class
against the toolset. If a design choice can't move that score, it is
taste, not design. Keep a held-out set; tool descriptions are prompt
surface and overfit like any prompt.