Giving an Agent Tools

An agent without tools is a chatbot. Tools are where reasoning becomes action, and a surprising share of total agent capability lives in how they are designed rather than in the model using them. This book’s authoritative treatment of that idea is the Agent-Computer Interface chapter.

The minimum that works

For coding agents the field has converged on a small stable core: read file, write or edit file, search, list, and a shell. Five tools, and the shell is doing most of the heavy lifting. Everything beyond this baseline should fight its way in, because every added tool costs context tokens and decision quality even when it is never called. Tool flooding is one of the seven early mistakes, and the fix is curation, not cleverness: an agent with twenty well-chosen tools outperforms one with fifty, and past that point selection accuracy visibly decays.

Selection is environment design

When an agent picks the wrong tool, the instinct is to blame the model. Almost always, the environment was ambiguous: two tools with overlapping descriptions, vague names, or no guidance on when not to use something. Tool selection is prompt-driven reasoning over your descriptions; it is exactly as good as the descriptions are.

The craft that measurably helps:

• Examples in the description. JSON schemas define structure, not usage. One to five realistic examples per tool, from minimal to full parameter use, moved complex-call accuracy from 72 to 90 percent in the source’s testing. Use realistic values, not placeholders.
• Negative guidance. State what a tool is not for. “Do not use for multi-file search; use search instead” prevents the most common confusions outright.
• Unambiguous names. Domain-prefixed, specific names (git_commit, not commit) do routing work for free.
• Structural error prevention. Design inputs so common mistakes are impossible rather than discouraged: require absolute paths, exact string matches, validated line numbers. Rejecting approximate input beats accepting and misinterpreting it.

Restrictions are architecture

What an agent cannot do is as much a design decision as what it can. Start from deny-all and allow per role: a reviewer gets read and search, a test runner adds execution, an implementer adds write, and only an orchestrator gets dispatch. Role-scoped toolsets are simultaneously a security boundary, per Security & Prompt Injection, and a forcing function for clean delegation, per Cohort. Treat agent tool grants with the seriousness of production IAM: explicit patterns rather than wildcards for anything destructive, confirmation gates on irreversible operations, and logs on everything, feeding the Execution Ledger.

The cost model

Different capability-packaging mechanisms have very different context costs, and choosing among them is a budgeting decision:

• Plain tools cost roughly a hundred tokens per definition: cheap, always loaded, explicitly invoked.
• Skills cost more up front (metadata for discovery, instructions on activation) but amortise well for workflows you run repeatedly; their progressive disclosure keeps a large library nearly flat in cost.
• MCP servers are the expensive tier: schema sets for a typical multi-server setup can consume tens of thousands of tokens before any work happens. Load them lazily or through search-based discovery when the definitions are large; deferred loading recovered around 85 percent of that cost in Anthropic’s published measurements.

The rule of thumb: one-off action, plain tool; recurring workflow, skill; continuous external system, MCP, loaded as lazily as the harness allows.

Next in the walkthrough: the loop that drives all of this, in The Agent Loop.