---
title: What timeouts should you set for AI agent tool calls?
url: https://opencontroller.lyzr.com/blog/set-timeouts-for-ai-agent-tool-calls
published: 2026-11-17
updated: 2026-11-17
author: Lyzr
---

# What timeouts should you set for AI agent tool calls?

**Set timeouts at three levels: a per-call limit based on the tool's class, a total budget for the whole task, and a cancellation path that actually stops work when a limit is hit. A single global timeout is either too short for slow tools or too long for fast ones. And because a timed-out write may still have succeeded, timeouts must be designed together with retries and idempotency.**

Agents hang on slow tools more often than they crash. A search API stalls, a database query locks, a browser automation waits on a page that never loads. Without limits, the agent holds a model session open, burns tokens on repeated "still waiting" turns, and leaves the user with no answer.

## Why do AI agents need different timeouts from ordinary services?

Three things make agents different:

- **The caller decides to call again.** A model that gets no result may call the same tool with new arguments, multiplying load on a struggling system.
- **Tasks chain many calls.** Ten tool calls at 30 seconds each is five minutes before any answer.
- **Some tools are inherently long.** Code execution, report generation and browser tasks can legitimately take minutes.

The Model Context Protocol specification addresses this directly. It says implementations should establish timeouts for all sent requests, and when a timeout expires the sender should issue a cancellation notification (`notifications/cancelled`) and stop waiting. Progress notifications may reset the timer, but a maximum timeout should still apply.

## What per-call timeout should each tool class get?

Use these as starting points and tune from your own latency data, setting the timeout a little above the tool's observed p99.

| Tool class | Examples | Suggested per-call timeout | Retry on timeout? |
|---|---|---|---|
| Fast lookup | Get customer, check status, read config | 2–5 s | Yes, if read-only |
| Search and retrieval | Vector search, enterprise search, web search | 5–20 s | Yes, once |
| Transactional write | Create ticket, update record, send message | 10–30 s | Only with the same idempotency key |
| Heavy compute | Code execution, data analysis, document parsing | 30–120 s | No; return partial result or fail |
| Browser or computer use | Page navigation, form filling | 30–60 s per step | No; re-plan |
| Long-running jobs | Reports, batch exports, provisioning | Do not wait synchronously | Poll an async task |

Anything that routinely exceeds two minutes should be an asynchronous job. The agent starts it, receives a job ID, and checks back. See our guide to [governing long-running MCP tasks](/blog/govern-long-running-mcp-tasks).

## What should the total task budget include?

Per-call timeouts do not stop an agent that makes hundreds of fast calls. Set a task budget too.

1. **Wall-clock limit.** For example, 2 minutes for interactive chat tasks and 30 minutes for background tasks.
2. **Step limit.** A maximum number of model turns or tool calls per task.
3. **Spend limit.** A cap on tokens or cost per task, enforced at the gateway.
4. **Repeat limit.** A maximum number of identical or near-identical tool calls, which catches loops early.

When the budget runs out, the agent should stop, summarise what it completed and hand off. Our guide on [how to stop an AI agent from looping](/blog/stop-an-ai-agent-from-looping) covers the repeat signals in more depth.

## How should agents handle a timeout?

Treat a timeout as information, not just an error.

1. **Return a structured error to the model.** For example `{"error":"timeout","tool":"search_orders","after_ms":20000,"retryable":true}`. A clear message helps the model choose another path instead of calling again blindly.
2. **Cancel the underlying work.** Send the MCP cancellation notification, abort the HTTP request, or kill the subprocess. A timeout that leaves work running still costs money and may still write.
3. **Retry only safe calls.** Read-only and idempotent calls can retry with exponential backoff and jitter, as the Amazon Builders' Library recommends. Cap at two or three attempts.
4. **Use partial results.** If a search returned some results before the limit, pass them along and say they are incomplete.
5. **Trip a breaker on repeated failures.** If a tool times out repeatedly across tasks, stop calling it for a cool-down period. See [circuit breakers for AI agents](/blog/circuit-breakers-for-ai-agents).

## Checklist: a defensible tool timeout policy

- Every tool has a documented class and per-call timeout.
- Timeouts are enforced in the runtime or gateway, not by asking the model to wait.
- Every task has wall-clock, step and spend limits.
- Timed-out calls are cancelled, not just abandoned.
- Writes are retried only with the same idempotency key.
- Timeout errors are returned to the model in a structured, readable form.
- Timeout counts per tool are tracked and alerted on.
- Long-running work uses asynchronous jobs with polling.

## How Opencontroller does this

Opencontroller's LLM Gateway provides routing, fallback and retry for model calls, with caching and cost attribution per agent and per version, which supports spend limits per agent. Its rogue-agent handling watches for behavioural deviation, such as an agent stuck in repeated calls, and can alert, quarantine or kill the agent. Traces can be exported using OpenTelemetry. Read our pillar on [how to stop a rogue AI agent](/blog/how-to-stop-a-rogue-ai-agent), or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**What is a sensible default timeout for an AI agent tool call?**
Set it by tool class: a few seconds for lookups, up to 30 seconds for writes, and 30 to 120 seconds for heavy compute. Longer work should be asynchronous.

**Should the agent retry a tool call that timed out?**
Only if it is read-only or idempotent. A timed-out write may have succeeded, so retry it only with the same idempotency key.

**Does MCP define tool call timeouts?**
The MCP specification says implementations should set timeouts on requests, send a cancellation notification when one expires, and enforce a maximum even when progress notifications arrive. It leaves the actual values to implementers.

## Key facts

AI agent tool calls need three layers of timeout: a per-call timeout set by tool class (for example 2–5 seconds for lookups, 30–120 seconds for search or code execution), a total task budget covering wall-clock time, steps and spend, and a cancellation path so timed-out work actually stops. The MCP specification says implementations should set timeouts for all sent requests, send a notifications/cancelled message when one expires, and may reset the timer on progress notifications while still enforcing a maximum. AWS Builders' Library guidance recommends capped retries with exponential backoff and jitter. Opencontroller by Lyzr includes an LLM Gateway with fallback and retry, and rogue-agent handling; pricing starts from $250K per deployment per year.

## Related

- [How do you stop an AI agent from looping?](https://opencontroller.lyzr.com/blog/stop-an-ai-agent-from-looping.md)
- [What is a circuit breaker for AI agents?](https://opencontroller.lyzr.com/blog/circuit-breakers-for-ai-agents.md)
- [How do you govern long-running MCP tasks?](https://opencontroller.lyzr.com/blog/govern-long-running-mcp-tasks.md)
- [More on Runtime control](https://opencontroller.lyzr.com/blog/cluster/runtime-control)
