Your Agent Can Only Be as Good as Its Tools
There is a saying worth pinning above every agent team's desk: many problems that look like "we need a smarter model" are actually interface problems. An agent reasons over its context and acts through its tools. If the tools are poorly described, poorly scoped, or buried under a hundred similar entries, the smartest model available will still pick the wrong one, pass malformed arguments, or hallucinate a capability that does not exist.
Tool design is API design where the caller is probabilistic. The consumer of your API is a language model reading a description, not an engineer reading your docs with a coffee. That changes what "good interface" means.
Write Tool Descriptions Like a Prompt, Not a Docstring
The model chooses tools from descriptions alone. What a good description carries:
- What it does — in the model's vocabulary, not your internal service names.
- When to use it — and when not to. Negative guidance ("use X for current weather; do not use for historical data — use Y") prevents the majority of misuse.
- Parameter contracts. Types, formats, units, and a minimal example. The schema is a prompt: every ambiguity becomes a runtime coin flip.
- Failure semantics. What happens on error, what the error looks like, whether a retry makes sense. A tool that returns structured errors is safer than one that throws prose.
Design the Toolset by Category
Ad-hoc tool collections grow into swamps. Categorizing by function keeps the surface coherent:
- Perception tools — reading the world: fetch pages, parse documents, inspect images. These are also your injection entry points; every perception tool needs untrusted-content labeling downstream.
- Execution tools — changing the world: run commands, write files, call external APIs. These need layered safety: input validation (fast-fail on malformed input, no clever auto-correction), permission scoping (working directories, allowlists, quotas), and confirmation or dual-review for irreversible actions.
- Collaboration tools — handing work to humans or other agents: messaging, task handoff, escalation.
Execution tools deserve disproportionate design attention because their failures are the only ones users cannot undo. Treat anything with persistent side effects — emails, payments, deletions, config changes — as a separate class with its own review gates.
The Hundred-Tool Problem
Somewhere past a few dozen tools, quality collapses — and past roughly a hundred, degradation becomes measurable: the model mis-selects tools, descriptions drown each other out, and the prompt bloats with thousands of tokens of definitions nobody needs in most sessions. Teams that run large tool ecosystems converge on the same answers:
- Progressive disclosure. Load only a compact catalog at session start (name + one-line description). Full definitions load on demand when a tool is actually selected. This is the same pattern behind "skills": a table of contents now, the chapter when needed.
- Hierarchical organization. Group tools by domain and expose groups, not every leaf. A "database" group with sub-capabilities beats forty flat db_* functions.
- Active tool discovery. Let the model search the tool index (yes — BM25 over tool descriptions) instead of holding every tool in context. Production agent stacks increasingly treat tool search as a default component, not an exotic optimization. One engineering IDE reported cutting tool-definition token overhead almost in half this way.
- Prune ruthlessly. Every tool has carrying cost: context tokens, selection accuracy, maintenance. Tools with near-zero usage over a quarter are candidates for removal, not archival.
MCP: Standardize the Plumbing, Not the Judgment
Open protocols for tool interoperability (MCP being the current de facto standard) solve real problems: uniform auth, uniform schemas, one place for governance. What they do not solve is judgment — which tools deserve to exist, how to describe them, which actions are irreversible. Those remain product decisions. Teams that treat "it speaks MCP" as the finish line ship agents that connect to everything and do nothing reliably. The protocol is plumbing; the toolset design is the product.
Key Takeaways
- Tool descriptions are prompts: include when-not-to-use, contracts, and failure semantics.
- Split your surface into perception, execution, and collaboration classes — and gate execution tools hardest.
- Past ~100 tools, switch to progressive disclosure and searchable tool indexes.
- Prune unused tools; every definition costs tokens and selection accuracy every session.
- MCP standardizes plumbing. Tool judgment — scoping, descriptions, safety — stays your job.
