Tool Timeouts in AI Agents: Report Unknown, Not Failed
When an agent's tool call times out, the outcome is unknown, not failed. Learn the status to record, what to verify next, and how to avoid duplicate work.

When an AI agent calls a tool and no answer arrives before the deadline, the correct status is unknown, not failed. The action may have completed, may still be queued, or may have finished while the response was lost on the way back. The next step is a verification read against the system of record, and a retry happens only after that read shows the action did not occur and is safe to repeat.
Key takeaways
- Record a timed-out tool call as unknown until a verification read confirms what happened.
- Give every tool that changes data a request identifier, so the agent can look up an outcome instead of guessing.
- Verify before any retry, and retry only actions that are safe to run twice.
- Set a limit on verification attempts, then hand the case to a named person with the evidence attached.
- Tell the business owner what was done, what is still unknown, and what is waiting.
Why a timeout is not a failure
A failure is a statement about the world. The tool returned an error, the record was not created, and nothing changed. A timeout is a statement about the connection. The agent stopped waiting, and that is all it knows. Treating the second as the first is one of the most common causes of duplicated invoices, double bookings and repeated messages to customers.
The mistake is easy to make because most agent frameworks surface a timeout in the same place as an error. A log line that says the tool failed looks identical to one that says the tool did not respond in time. Downstream, the agent reads the label and decides what to do next. If the label says failed, the agent tries again. If the original request was in fact processed, the second request now runs on top of a result that already exists.
For reads, the distinction matters less, because repeating a lookup is harmless. For writes, sends, payments and status changes, it matters a great deal. The same timeout can mean no change, one change or a change that has already been reversed by someone else. The agent cannot tell which from the timeout alone.
The three states a timed-out call can be in
When a write-capable tool times out, the underlying system is in one of three states. The request never reached the service, so nothing happened. The request reached the service and was completed, but the confirmation did not come back. Or the request was accepted and is still being processed. A sound agent design assumes any of the three and does not pick one by default.
This is why the status should be a distinct value, separate from success and failure. A practical record for each attempted action includes the action type, the target record, the request identifier, the time the request was sent, the time the timeout occurred, the current status and the verification result. Keeping these fields makes the next step a matter of reading, not guessing.
- Action: what the agent tried to do, in plain terms, such as create an invoice draft for a named client.
- Target: the record or account the action touched, identified by its system key.
- Request identifier: the key sent with the call, so the provider or the internal service can match duplicates.
- Status: unknown, confirmed success, confirmed not applied, or pending review.
- Verification: the read performed, its timestamp and what it returned.
The request identifier does most of the work. Payment providers and some internal APIs accept a client-generated key and return the original result when the same key is sent again. The approach is described in provider documentation such as the [Stripe idempotent requests reference](https://docs.stripe.com/api/idempotent_requests), and the same principle applies to any internal service that can match a repeated request to a prior one. Where no such key exists, the agent must rely on a lookup by a unique business field, such as an external reference it generated and stored before the call.
What to verify before any retry
The verification step is where most agent designs are thin. Teams often add a retry with backoff and stop there, which handles transient network trouble but not an action that succeeded silently. The next step should be a read that answers one narrow question: did this specific action take effect?
The read should query the system of record directly, not a cache, a search index or the agent's own memory. Memory is useful for context, but it is not evidence that an external system changed. If the system of record cannot be read within the same deadline, the status stays unknown and the case moves to review.
A plan that works for most business tools follows a short sequence.
- Mark the action as unknown in the run record, and stop any dependent steps that rely on its result.
- Run one verification read using the request identifier or the stored external reference.
- If the read shows the action applied, record it as confirmed and continue with the next step only.
- If the read shows no trace and the action is idempotent, retry once with the same request identifier.
- If the read shows no trace and the action is not idempotent, do not retry. Route the case to a person with the proposed action and the evidence.
- If the read itself times out, keep the status unknown, wait for the configured interval and try the read again within the attempt limit.
- When the attempt limit is reached, stop and escalate. Do not switch to a different tool to achieve the same result without a review.
The last two steps matter. An agent that keeps retrying a read, or that quietly routes the same write through a second tool, can produce the duplicate it was trying to avoid. A clear stop condition protects both the data and the budget. For the general pattern of bounded retries, the AI agent retry policy guide covers how to choose attempt counts and intervals.
An illustrative scenario: a quote sent twice
The following scenario is illustrative and does not describe a real client. An operations agent prepares a quote and sends it through the company's document service. The call times out after the document service has already queued the email. Under a naive design, the agent marks the send as failed and tries again, so the customer receives two identical quotes with two different reference numbers.
Under the design described here, the agent records the send as unknown and attaches the external reference it generated before the call. It then searches the outbox for that reference. The outbox shows one queued message, so the agent marks the send as confirmed and does not retry. It writes a short note in the case record. If the outbox had shown nothing, and the send were not idempotent, the agent would have placed the quote in a review queue with the draft attached, rather than sending it again.
The difference is not in the tool. It is in the status the agent was allowed to write and the check it was required to run before acting again.
Deciding when a person should take over
Not every unknown needs a human, and not every unknown can be left to the agent. The decision depends on what the action changes, whether it can be reversed and how much time the business has before the uncertainty causes harm. The guide below is a starting point to agree on with the operations owner, not a universal rule.
- Reads and lookups: retry within the limit, then mark as unavailable. No human review is usually needed.
- Idempotent writes with a reliable key: verify, then retry once if the read shows no trace.
- Non-idempotent writes such as payments, sends or deletions: verify, then escalate when the read is inconclusive.
- Actions affecting customers or money where the current state cannot be read at all: pause the workflow and notify the owner.
- Repeated unknowns on the same tool within a short period: treat the tool as degraded, stop new calls to it and open an incident.
When a person takes over, the handoff should contain the decision to be made, not the full transcript. The person needs the intended action, the request identifier, the verification results and the options with their consequences. The human escalation guide for agent failures describes how to keep these handoffs short and actionable.
How Be Human handles tool timeouts in managed operations
Be Human designs the status model, the request identifiers and the verification steps as part of the agent's operating context, before the agent is given authority over a write. In managed operations, the team monitors how often calls end in unknown, reviews the verification reads that confirmed or cleared them, and adjusts retry limits and escalation thresholds through a logged change process. When a tool degrades, the response follows a written incident procedure, and the business owner receives a plain summary of what was applied, what is pending and what needs a decision.
For teams that want to see where timeouts already cause trouble, a useful first step is to list every tool the agent calls, mark which ones change data, and check whether each one accepts a request identifier. The free Be Human AI diagnostic can help identify the first task worth handing to an agent, and the right tool design for that task.
Frequently asked questions
Should an AI agent ever record a timed-out tool call as failed? It should not, unless the tool returned an explicit error that confirms nothing was applied. A timeout only tells the agent that it stopped waiting, so the honest status is unknown until a verification read shows the outcome. Recording it as failed invites a retry that can duplicate the action.
How does an agent verify an action after a timeout? It should query the system of record directly, using a request identifier or an external reference that it stored before making the call. The read should answer one narrow question, whether that specific action took effect. If the read also times out, the status remains unknown and the attempt counts toward the limit.
Can every failed tool call be retried safely? No. Retrying is safe only when the action is idempotent, meaning that running it twice has the same effect as running it once, or when the provider returns the original result for a repeated key. For non-idempotent actions such as payments, sends or deletions, the agent should verify and then escalate rather than retry on its own.
What should a business owner ask for before giving an agent write access to a tool? Ask how each timed-out write is recorded, which identifier is sent with it, how the agent verifies the outcome and when it stops and asks a person. Ask to see a sample run record from a timeout in a test environment. The answers show whether the agent can tell done from not done, which is the decision that matters most.
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.


