Designing Agent Tools

An agent without tools can produce language but cannot change the world. Tools turn reasoning into action, and their design strongly influences what the agent can accomplish. The Agent-Computer Interface develops this principle in full.

The minimum that works

Coding agents can do substantial work with a small core: read, edit, search, list, and shell access. Every additional tool consumes context and adds another routing decision even when the agent never calls it.

Tool flooding is one of the common failure patterns. The remedy is curation. Add a tool when it provides a necessary capability, a safer interface, or materially better feedback than the existing surface.

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.

Tool design defines what an agent can attempt. The next chapter defines what it is allowed to attempt.