A Hands-On Course · 15 lessons

Tool Engineering

Tools agents use well — schema design, token efficiency, error output, and result shaping.

Short lessons (~5–8 min each), each with one tangible win and a retrieval-practice quiz. Built for engineers who already use AI coding tools and want the non-obvious mechanics.

Grounded in the agentpatterns.ai corpus (CC BY 4.0). Keep the Glossary open as you go.

Part 1 · Foundations

1 What Makes a Tool Agent-Friendly A tool that works perfectly when you call it can still be unusable by an agent. The difference is not the implementation — it's the surface. 2 Schema & Description Altitude The agent never browses your tool catalog. It selects by reasoning over descriptions — so the description is where you win or lose the call, before any work begins.

Part 2 · Shaping the Surface

3 Token-Efficient Tool Design Every tool call is a deposit into the context window. A tool that returns 10,000 tokens when 200 would do has spent 10% of a 100K window on a single call. 4 Result Shaping Sizing output was the budget. Shaping it is the craft: which fields, in what language, paginated how — and what to do when even the trimmed result overflows. 5 Errors as a Teaching Signal An agent has no intuition to fall back on. It takes your error message literally — so a cryptic failure leaves it stuck, and a well-shaped one tells it exactly what to do next.

Part 3 · Managing the Set

6 Consolidation vs Sprawl More tools feels like more capability. To the agent it's more reasoning tax — and past a point, measurably worse accuracy. The fix is fewer, well-scoped tools.

Part 4 · Reliability Under Failure

7 Idempotent, Safe-to-Retry Tools Agents fail mid-task and get re-run from scratch — with no memory of what the first run already did. A tool that wasn't designed for that turns a retry into a duplicate. 8 Annotations & Safe Concurrency A tool annotation looks like a passive safety badge. The moment a harness reads it to decide whether to run calls in parallel, it stops being advisory and starts governing execution.

Part 5 · Scaling the Set

9 Tool Discoverability at Scale Lesson 6 thinned one toolset. But some agents legitimately need dozens of tools — and past a point the model can't hold them all in view. The fix isn't fewer tools; it's loading them at the right time. 10 MCP Tool Exposure Everything so far applies to a single tool. MCP is where a server exposes a whole set across hosts — and the first decisions, made before naming or schemas, are whether something should even be a tool. 11 Tool-Call Cost & Latency Budgeting Lesson 3 budgeted the tokens of one call's output. This one budgets the whole toolset — the tokens it costs before a single call, and the wall-clock it costs across many — as a line item you track, not a side effect you discover.

Part 6 · Beyond the Tool Catalog

12 Skills as a Tool-Engineering Surface The first eleven lessons engineered the typed tool. But a tool isn't the only thing you hand an agent. A skill is a second surface — packaged knowledge the agent discovers and loads — and it answers questions a schema can't. 13 Hooks & Deterministic Lifecycle Enforcement Lesson 7 made effects safe by designing the tool to be re-runnable. This lesson makes them safe a second way — by intercepting the call before it runs, with code the model cannot reason its way around. 14 The Unix CLI as a Tool Interface The whole course assumed a catalog of typed tools. This lesson considers the opposite extreme: hand the agent one run(command) tool and let Unix supply the rest.

Capstone

15 Capstone — The Tool Engineer's Decision Table Fourteen lessons, one habit: read the symptom, find the surface, apply the move. Here it is as a single routing table — now spanning reliability, scale, cost, and the surfaces beyond the catalog — plus a mixed review of the whole course.