Skip to content
be-human.ai
← Back to the journal

Testing & reliability

Superintelligence Tool Errors: Map Each Failure to a Next Step

Map each AI agent tool failure to one next step: retry, ask a person, or stop. Replace improvised recovery with written rules your team can review.

Be Human typographic cover with the title: Superintelligence Tool Errors: Map Each Failure to a Next Step
Conceptual illustration created with AI · Be Human

A tool error is any failed, empty or unclear response from a system an agent calls, such as a CRM, a billing API, a calendar or a document store. The reliable way to handle it is to classify the failure, then assign each class one predefined next step: retry within limits, hand the decision to a named person, or stop the run and keep its state. Agents that improvise recovery tend to guess, repeat side effects or hide the problem behind a confident answer.

Key takeaways

  • Classify tool failures by what they mean for the business, not only by the error code.
  • Give every failure class one default next step: retry, ask a human, or stop.
  • Retry only when repeating the action is safe, and cap the attempts for each tool.
  • Treat a timeout on a write as an unknown outcome, because the action may already have happened.
  • Log the failure, the rule applied, and the person who can override the decision.

Why improvised recovery is the wrong default

When an agent meets an error that no rule covers, it chooses a path from its prompt and the last few messages in context. That path may be sensible on one run and harmful on the next. A search tool returns nothing, and the agent writes a plausible answer anyway. A payment call times out, and the agent calls it again, creating a second charge. The model is not careless in these cases. It has no stated boundary for the situation, so the boundary becomes whatever it infers at that moment.

Business leaders do not need an agent that is cleverer about errors. They need the error path decided ahead of time, reviewed by the people who own the process, and visible afterward. The NIST AI Risk Management Framework treats risk as something to map, measure and manage across the system's lifecycle, and a tool failure is a concrete place where that mapping pays off.

Classify each tool failure before you design a response

Start with the tools the agent actually uses. For each one, list the ways it can fail and what the agent needs to know in each case. Most failures fall into a small set of classes, and that set is a good starting point for your own map:

  • Transient error: the tool signals that it is busy or unavailable, and the request was not processed.
  • Rejected request: the tool refuses the input because a field is missing, a permission is absent or a business rule was broken.
  • Empty or ambiguous result: the tool answered, but the answer does not fit the task, such as no matching customer or two possible matches.
  • Unknown outcome: the request timed out or the connection dropped after the action may have been performed.
  • Conflicting data: the result contradicts another source the agent holds.
  • Out-of-bounds request: completing the task would require an action outside the agent's approval boundary.

The unknown outcome class deserves the most attention. For a read, the agent can simply ask again. For a write, the agent cannot tell whether to repeat the action or report it as done, and guessing is how duplicate bookings and double refunds happen. The out-of-bounds class is not a fault in the tool, but it should follow the same map, so the agent never works around a permission it was not given.

Map each class to retry, ask a human, or stop

Each class gets one default next step. Keep the map short enough that a manager can read it in a few minutes:

  • Transient error: retry with a fixed attempt cap and growing pauses. If the cap is reached, hand the case to a person.
  • Rejected request: do not resend the same input. Ask a person only if the missing information exists outside the agent, otherwise stop and record the reason.
  • Empty or ambiguous result: do not choose silently. Present the candidates and the open question to a person.
  • Unknown outcome on a read: retry, because repeating a read is safe.
  • Unknown outcome on a write: stop further writes, check the system of record with a read-only lookup if one exists, and ask a person before any repeat.
  • Conflicting data: stop the affected step and ask a person which source is current.
  • Out-of-bounds request: stop, record the request, and route it to the approver named in the permission model.

The pattern is consistent. Retries belong where repeating the same request is harmless and likely to succeed. Human handoff belongs where the right decision depends on context the agent does not have. Stopping belongs where continuing would create side effects nobody has approved.

Retry what is safe to repeat, ask about what depends on context, and stop what would change the business without approval.

Write the plan for each tool as steps someone can audit

A general policy such as "handle errors carefully" cannot be tested. A plan for each tool can. Write one short plan per tool the agent uses, and include these elements:

  • The tool name, the owner of the system behind it, and the actions the agent may take.
  • The failure classes that apply to that tool and the default next step for each.
  • The limits: maximum attempts, maximum elapsed time and the point at which the run stops.
  • The person or queue that receives handoffs, and the response time that person is expected to meet.
  • What the agent reports: the request, the error class, the attempts made and the last known state.
  • How a person resumes or closes the run, and whether the agent may continue from a saved checkpoint.
  • When the plan is reviewed, including after every incident and every change to the tool.

Keep these plans next to the agent's operating notes, so the person on duty can act without asking the builder what the agent was designed to do.

Illustrative scenario: an agent that prepares refund decisions for a support team calls the payments service to check a charge, and the first call times out. Under the plan, the agent classifies the result as an unknown outcome on a write path. It runs a read-only lookup on the charge, finds no refund recorded, and does not issue one. It places the case in the human queue with the charge identifier, the time of the timeout and the lookup result. The support lead decides whether to issue the refund, and the run stops there. None of this depends on the agent guessing.

Limit retries so they never repeat a side effect

Retry logic usually fails in one specific way: it treats every failure as the same kind of problem. A retry on a read is harmless. A retry on a booking, a payment or an outgoing message can duplicate a business action that a customer or a supplier will notice. The safe pattern is to give each write a unique identifier so the receiving system can recognize a repeat and return the original result. Stripe documents this approach for its API as idempotency keys, where a repeated request returns the result of the first one rather than creating a new record. If you build your own tools, the same principle applies: if the tool cannot recognize a repeat, the agent should not repeat a write.

Set attempt caps and time caps per tool rather than one global number, because a slow internal search and a payment gateway have different tolerances. For the full retry pattern, read An AI agent retry policy that avoids repeated mistakes. For the specific problem of a timeout that leaves the result unknown, read Tool Timeouts in AI Agents: Report Unknown, Not Failed.

What to record so every failure can be reviewed

An error path is only useful if someone can see it operate. Record enough to reconstruct each decision: the tool, a summary of the input with personal data removed, the error class, the rule applied, the number of attempts, the final state and the handoff target. Traces that follow one request across several steps make this easier to read. The OpenTelemetry documentation on observability concepts describes this model of spans and traces, which is useful even if your logging tools are different.

When the agent hands a case to a person, the handoff should carry the decision that is needed, not the full transcript. A reviewer who has to read forty messages to find one question will eventually stop reading. For the handoff format, read Human escalation for AI agents: send the decision, not the mess.

How Be Human runs this in managed operations

Be Human designs the error map as part of a first engagement, starting from the one role the agent will perform and the tools that role needs. We define the failure classes for each tool, the default next step for each class, and the approval boundaries that decide when an agent may write, when it must ask and when it must stop. In managed operations, monitoring watches failure logs for classes that appear more often than expected, permission reviews remove access that is no longer needed, and incident response updates the plan when a failure exposes a gap. Changes to retry limits or handoff rules are made in a controlled way and recorded in a form the business owner can read.

If you are not sure which tool failure in your operation would do the most damage, the free Be Human AI diagnostic can help you find the first task worth handing to an agent.

Frequently asked questions

Should an AI agent retry every failed tool call? No. Retries are safe for reads and for transient errors, where a repeat is likely to succeed without side effects. For writes with an unknown outcome, the agent should check the system of record and ask a person before repeating anything. A global retry rule that ignores this difference is one of the most common causes of duplicate actions.

When should an agent stop instead of asking a person? Stop when continuing would create a business effect that no one has approved, such as a write outside the agent's permissions or a write after conflicting data appears. Asking a person is the right choice when the decision depends on context the agent lacks, such as which of two customer records is current. Stopping also keeps the run's state intact so a person can resume it later.

How should a timeout on a write action be handled? Treat it as an unknown outcome, not as a failure, because the action may have been completed before the connection dropped. The agent should look up the result through a read-only check if the system offers one, and it should not resend the write until a person or a verified rule allows it. Where the tool supports idempotency keys, the repeat is safe because the receiving system returns the original result.

Who should own the error map for an agent? The business owner of the process should own it, with the technical builder maintaining the implementation. The owner decides what a handoff means, who receives it and how quickly it must be answered. Reviewing the map after each incident keeps it accurate as tools and permissions change.

Your next step

See where an AI agent fits in your company first.

Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.

Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.

Less busywork. More room for you.

Bring us the work you wish you had time for.

Book a call to try a personalized AI agent free for 7 days ↗Or take the free AI diagnostic →