Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →A max_retries=2 setting does not tell you how many times your tool function runs. It names a retry budget owned by some component, and that component may retry an HTTP request, a provider call, or a whole model-driven tool step. Whether the tool executes once depends on which of those layers the setting controls, and on whether the gateway documents any protection against repeated execution. A claim of exactly-once tool execution needs its own evidence. A retry number cannot supply it.
Why the sentence cannot be verified as written
The claim names no product, so there is no documentation to check it against. Three details are missing: which gateway it is, which layer owns max_retries, and what the implementation counts as a retry. Each of those changes the answer. A setting on an HTTP client, a setting on a provider-routing gateway, and a setting on an agent framework’s tool decorator can all be called max_retries and still behave differently.
As an Amazon Associate I earn from qualifying purchases.
Four different things a retry setting can mean
Readers often treat “retry” as one behavior. In practice the word covers at least three separate mechanisms, and exactly-once execution is a fourth property that none of them provides by default.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →| Layer | What gets repeated | Can your tool function run again? | Documented evidence reviewed |
|---|---|---|---|
| Client or SDK retry | An HTTP request handled by the client library | Not by itself. The request is repeated, but a function in your code is not re-invoked unless the request was for the tool itself. | The OpenAI Python SDK documents its own retry control for its HTTP requests, separate from any agent or tool logic. |
| Gateway retry or fallback | A provider request, or a switch to another provider route | Depends on the gateway. Whether a repeated provider request can lead to a second tool execution is not established for any gateway named here. | AcruxCore’s documentation distinguishes constructor-level HTTP retries from gateway-level behavior. This is one vendor’s illustration, not evidence about the unnamed gateway. |
| Framework tool retry | A model turn that is asked to call the tool again | Yes. The model issues a new tool call, so your function can run again. | Pydantic AI documents per-tool, per-toolset, per-run, and agent-wide retry limits. |
| Exactly-once execution | Nothing, if the guarantee holds | No, by definition. The tool runs one time for each logical call. | Not established in the sources reviewed for the gateway in question. |
How a framework retry becomes a second tool call
The framework case is the one most likely to surprise a developer, because the tool is re-invoked as part of normal model behavior. In Pydantic AI’s documentation, under “Requesting a Tool Retry,” raising ModelRetry produces a retry prompt containing the exception message. The documentation states: “Raising ModelRetry generates a RetryPromptPart containing the exception message. That prompt is sent back to the LLM so it can correct the parameters and retry the tool call.”
#1 Best Overall
Validation failures follow the same path. If the arguments the model supplies do not match the tool’s schema, the framework can send a retry prompt and let the model try again. In that flow the tool function may run zero times on the failed attempt and once on the successful one, or it may run more than once if the model is asked to change its approach. None of this is a fault. It is the designed behavior of a retry loop that sits above the tool.
Reading the number itself
The integer in a retry setting does not settle whether it means extra retries or total attempts. Some implementations treat max_retries=2 as two additional attempts after the first, which is three attempts in total. Others count total attempts. The field name alone does not say which. Do not multiply the setting by your tool’s call count to estimate executions. Read the definition in the component’s own documentation or source.
Rank #2
What would establish exactly-once execution
A retry limit cannot prove that a tool runs once, and neither can the absence of retries. An exactly-once claim needs one or more of the following, documented for the specific gateway:
Recommended Free Tools
- An explicit statement that tool invocations are executed at most once per logical call, with the scope of that guarantee named.
- A deduplication mechanism, such as an idempotency key that the gateway checks before running a tool, with the key’s lifetime and scope stated.
- A description of what happens when a response is lost after a tool has already run, including whether the gateway replays the tool or returns a stored result.
- Evidence the claim has been tested or is enforced in code, with the version and conditions named.
If none of these is available, the accurate phrasing is that the gateway retries certain requests up to a configured limit, and whether a tool can run more than once is not documented.
How to check the claim in your own stack
- Identify the component that reads
max_retries. Search your configuration and dependencies for the setting name and note the file and package. - Find the definition of the setting in that component’s documentation or source. Confirm whether the number is additional retries or total attempts, and whether it applies per request, per tool, or per run.
- Determine what is retried: an HTTP request, a provider call, or a model turn that asks for another tool call.
- Add a counter inside the tool function and run a call that you force to fail on the first response, for example by making the tool return a validation error or by interrupting the response. Record how many times the counter increments.
- Look for an idempotency or deduplication setting. If there is none, treat the tool as at-least-once and design its side effects to tolerate repetition.
The counter test in step four shows what happens in your configuration on your model version. It does not generalise to other gateways or to future releases of the same package.
What to do if the tool has side effects
If the tool charges a card, sends a message, or writes a record, a repeated execution is a real defect. Make the tool idempotent where you can, by keying each write to a logical request identifier and rejecting duplicates. Where the gateway offers a deduplication option, enable it and test it with the counter from step four. Where it does not, move the side effect out of the tool and into a step your code controls, so a model retry cannot trigger it.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What the gateway claim should say
A publishable statement needs the gateway’s name, the layer that owns max_retries, the meaning of the number, and the documented execution guarantee, with a link to that documentation. Without those, the defensible version is narrower: the gateway retries specified requests up to a configured limit, and the number of tool executions is not guaranteed.
Sources reviewed for this article are vendor and framework documentation published as of October 2026. Their descriptions may change between releases, so confirm the current behavior in the version you run.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
