Designing tools agents can actually use

Most agent failures we see in traces don’t start with the model. They start with a tool that was easy for a human to understand and confusing for an agent.

1. One job per tool

A tool called manage_ticket that creates, updates and closes is three tools pretending to be one. Split it, and the agent stops guessing which mode it is in.

2. Name arguments for meaning

Prefer customer_email over id. The model reads names as instructions.

3. Return what the next step needs

Return the fields the agent will use next, not the whole record. Smaller results mean fewer tokens and fewer distractions.

4. Fail loudly and specifically

“Invalid input” teaches nothing. “customer_email must be a valid address, got ‘n/a’” fixes itself on the next step.

5. Make side effects explicit

• Mark tools that write, send or pay.

• Require approval for anything irreversible.

• Declare whether calling twice is safe.

If a new teammate would need to ask how a tool works, the agent will get it wrong.

The payoff

Teams that applied these rules cut failed steps by 41% in a month, without touching a prompt.