Tool & Capability Design

Designing Tools Agents Can Use

Tools are the agent's entire API: design for a model that reads only the description and is confidently wrong, not for an engineer who read the source.

Tool Granularity & Composition

Coarse tools hide decisions and concentrate blast radius, fine tools multiply round-trips and bloat the list — and tool explosion is now a measured ~24-point selection-accuracy loss.

Schemas, Contracts & Defaults

The schema is the instruction set: make illegal states unrepresentable, make safety-relevant fields required, and let the path of least specification be the path of least harm.

Error Messages as Prompts

A tool error is a just-in-time prompt: name the cause, echo the bad value, prescribe the corrected call, and say retryable-or-terminal — or breed a runaway retry loop.

Tool Docs & Discoverability

Selection is text-only retrieval over names and descriptions: namespace by service, say when-and-when-not, show one example — and remember discoverability is inversely related to inventory.

Tool-Design Anti-Patterns

The four that sink most agents — kitchen-sink tool, stringly-typed args, silent failure, leaky abstraction — each spotted in a minute, each with a trace signature and a mechanical fix.