Designing Tools an Agent Can Actually Use

When an agent misbehaves, the tool is at fault more often than the model. Good tools make good agents.

Name and describe for a reader who skims

The model picks tools from their names and descriptions. search_orders_by_email beats query. Say what the tool does, what it needs, and when *not* to use it.

Keep each tool small and single-purpose

One tool, one job. A mega-tool with ten optional parameters forces the model to guess. Several focused tools let it choose clearly.

Return useful errors

"Error 500" teaches the agent nothing. "No customer found for that email — check spelling or ask the user" lets it recover on its own. Errors are instructions in disguise.

Scope permissions tightly

Give the agent the narrowest tool that does the job. Read-only when it only needs to read. This is a safety control and a clarity control at once.

Test tools in isolation

Before blaming the agent, call each tool by hand with the arguments the agent used. Half of "the agent is dumb" turns out to be "the tool returned garbage."