Skip to content

Tool Budgets

Cap how many times the model can call each tool, or any tool, in one run, and refuse a call that repeats an earlier one exactly. An over-budget or repeated call is answered with a tool result that tells the model what it hit, and the run continues. Use it to keep an agent from spending a run on one expensive tool, such as web search.

While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.

Usage

Terminal
pip install pydantic-ai-harness
from pydantic_ai import Agent
from pydantic_ai_harness import ToolBudgets

budgets = ToolBudgets(per_tool={'web_search': 3}, total=20, refuse_repeats={'web_search'})
agent = Agent('anthropic:claude-opus-5-5', capabilities=[budgets])
FieldRefuses a call when
per_toolThe named tool already ran this many times in the run.
totalThis many tool calls, across all tools, already ran in the run.
refuse_repeatsThe named tool already ran in the run with the same arguments.

A budget must be at least 1. UsageLimits.tool_calls_limit stays the hard ceiling: it raises UsageLimitExceeded and ends the run. A refused call is still a call the model made, so it counts toward that limit.

What the model sees

A refused call doesn’t run. Its tool result names the budget and how much of it is used:

3 of 3 `web_search` calls used; no more are allowed in this run.
20 of 20 tool calls used; no more are allowed in this run.
`web_search` already ran with these exact arguments in this run (tool call `call_abc`); its result, or a summary of it, is earlier in this conversation. Don't call it again with the same arguments.

The refusal is a ToolReturn whose metadata, which the model doesn’t see, is {'origin': 'pydantic-ai-harness.tool_budgets.refusal.v1', 'reason': reason}, with reason one of 'per_tool', 'total' or 'repeat' (ToolBudgetReason). Find refusals in history by that origin, not by their text.

How calls are counted

  • A call counts once its execution starts, whether the tool then returns, raises ModelRetry, fails, or raises CallDeferred, since a tool that defers may already have started its work. A call that another capability skips or holds for approval, such as a Tool Call Judge block or an approval request, doesn’t count. A refused call doesn’t count either.
  • Repeats are opt-in per tool, because a polling tool repeats its call on purpose. Two calls are the same when the tool name matches and the arguments, as the model sent them before defaults are filled in, are equal as JSON with sorted keys. A call that failed isn’t remembered, so it can be made again.
  • Parallel calls in one response are counted in the order they start, so they can’t overshoot a budget, and an identical parallel call is refused as a repeat. A call is checked against calls that started but haven’t finished, so if another capability then skips one of those or holds it for approval, a parallel call refused because of it still doesn’t run.
  • Every function tool call counts, including MCP tools and tools other capabilities add. Calls the provider runs itself (native tools) and output tools don’t. per_tool and refuse_repeats use the tool’s name as the model sees it, after any prefix.
  • Counts live in the instance for_run creates for each run, not in message history, so compaction that summarizes earlier calls away doesn’t hand a budget back, and a repeat stays refused after its earlier result has been summarized.
  • A run that continues an earlier conversation through message_history starts at zero. So does a run resumed after a tool approval or other deferred call resolved outside the run, rather than by a handler inside it: with approval rounds, per_tool={'web_search': 3} allows three calls per round, not per task.

Durable execution

The checks run in wrap_tool_execute, in workflow code, under durable execution. When Temporal, DBOS, or Prefect replays a run, they run again in the same order over the journaled responses and reach the same refusals, so a replay doesn’t double-count.

Telemetry

Each refusal emits a zero-duration tool call refused span through ctx.tracer, with tool_budgets.reason and tool_budgets.tool_name. It’s a no-op unless the agent is instrumented. Calls that run emit nothing beyond core’s tool span.

Composition

  • Several ToolBudgets on one agent each count the calls they let run, so every budget applies.
  • Detect Loops notices repetition after the fact and nudges or stops the run; ToolBudgets refuses an exact repeat before it runs, for the tools you list.

See the source.

API reference

ToolBudgets

Bases: AbstractCapability[AgentDepsT]

Cap tool calls per tool and per run, and refuse exact repeats, by answering the model instead of raising.

A refused call doesn’t run: the model gets a tool result that says which budget it hit and how much of it was used, and the run continues. UsageLimits.tool_calls_limit stays the hard ceiling that ends the run.

Counts live on the instance for_run creates for each run, not in message history, so compaction can’t hand a budget back. A call counts once its execution starts, whether it then succeeds, fails or defers; a call that another capability skips, or holds for approval, doesn’t count.

from pydantic_ai import Agent
from pydantic_ai_harness import ToolBudgets

budgets = ToolBudgets(per_tool={'web_search': 3}, total=20, refuse_repeats={'web_search'})
agent = Agent('anthropic:claude-opus-5-5', capabilities=[budgets])

Attributes

per_tool

The most calls each named tool may run in one run. Tools not named here have no per-tool budget.

Type: Mapping[str, int] Default: field(default_factory=(dict[str, int]))

total

The most tool calls, across all tools, that may run in one run, or None for no total budget.

Type: int | None Default: None

refuse_repeats

Tools whose call is refused when the same call, with the same arguments, already ran in this run.

Opt in per tool: a lookup repeated with the same arguments returns what it returned before, but a polling tool legitimately repeats its call.

Type: AbstractSet[str] Default: frozenset()

Methods

for_run

@async

def for_run(ctx: RunContext[AgentDepsT]) -> ToolBudgets[AgentDepsT]

Return a fresh instance, so runs don’t share their counts.

Returns

ToolBudgets[AgentDepsT]

wrap_tool_execute

@async

def wrap_tool_execute(
    ctx: RunContext[AgentDepsT],
    *,
    call: ToolCallPart,
    tool_def: ToolDefinition,
    args: dict[str, Any],
    handler: WrapToolExecuteHandler,
) -> Any

Refuse a call that is over budget or repeated, otherwise count it and run it.

The checks and the count happen before the first await, so parallel calls can’t overshoot a budget.

Returns

Any

ToolBudgetReason

Why ToolBudgets refused a call, as recorded under 'reason' in the refusal’s ToolReturn.metadata.

Type: TypeAlias Default: Literal['repeat', 'per_tool', 'total']