Most agent failures we've seen trace back to how a tool was described, not to the model behind it. A model that plans well can still be led into a corner by a tool interface that's ambiguous, too broad, or silent about what went wrong. These are the five rules we now apply by default when we hand an agent a set of tools.
Keep each tool doing one thing
A tool called manage_order that can create, update, cancel and refund depending on which arguments you pass is harder for a model to reason about than four small tools that each do one of those things. Narrow tools are easier to name well, easier to validate, and easier to reason about when something goes wrong. If a tool's description needs an "and" in it, it's usually two tools.
Return structured errors, not exceptions
When a tool call fails, the agent needs enough information to decide what to do next: retry, ask the user, or give up. A stack trace doesn't help with that. We return a small, consistent error shape (a reason code plus a plain-language message) so the model can actually act on the failure instead of just repeating the same call.
Make tools idempotent wherever you can
Agents retry. A network blip, a timeout, or the model simply deciding to try again shouldn't be able to charge a card twice or send the same email twice. Where a tool has a side effect, we look for a way to make calling it twice with the same input safe, usually with an idempotency key the caller supplies.
Log every call, even the boring ones
When something goes wrong three steps into a plan, the only way to understand why is a full record of what was called, with what arguments, and what came back. We log every tool call by default, not just the ones that fail. It's cheap to store and it's the first thing we open when a customer says an agent did something unexpected.
Put a human in the loop for anything irreversible
Sending a message, refunding a payment, deleting a record: these get a confirmation step before they execute, even when the agent is otherwise fully autonomous. It's a small amount of friction in exchange for never having to explain why an agent did something that can't be undone.
Want to talk about something like this?
We take on new projects across agentic systems, web, mobile and custom software.