Adding per tool usage limit #3691

adtyavrdhn · 2025-12-10T10:41:23Z

PR Summary: Per-Tool Usage Limits & Soft Tool Call Limits

This PR adds two related features for controlling tool execution.

1. `max_uses` - Per-Tool Usage Limit

Limit how many times a specific tool can be called during a run:

@agent.tool(max_uses=3)
def my_tool(ctx: RunContext[None]) -> str:
    return 'result'

Once a tool reaches its limit, it's removed from available tools and further calls return 'Tool call limit reached for tool "{name}".'

2. `max_tool_calls` - Soft Total Tool Call Limit

Set a global limit on total tool calls at the agent or run level:

agent = Agent('openai:gpt-4o', max_tool_calls=5)

# Or override per-run:
agent.run_sync('prompt', max_tool_calls=2)

…er_tool_usage_limit

… if it should be somewhere else altogether to cover granular limit exceeded as well?

…ck and enforce

DouweM · 2025-12-16T21:03:20Z

docs/agents.md

+
+If you want to limit tool calls but let the model decide how to proceed instead of raising an error, use the `max_tool_calls` parameter. This is a "soft" limit that returns a message to the model when exceeded, rather than raising a [`UsageLimitExceeded`][pydantic_ai.exceptions.UsageLimitExceeded] exception.
+
+```py {test="skip"}


We shouldn't skip tests unless absolutely necessary

DouweM · 2025-12-16T21:03:43Z

docs/agents.md

+
+1. Set the maximum number of tool calls allowed during runs. This can also be set per-run.
+
+When `max_tool_calls` is exceeded, instead of executing the tool, the agent returns a message to the model: `'Tool call limit reached for tool "{tool_name}".'`. The model then decides how to respond based on this information.


This seems like it can be combined with the sentence before the example

DouweM · 2025-12-16T21:04:04Z

docs/agents.md

    - Usage limits are especially relevant if you've registered many tools. Use `request_limit` to bound the number of model turns, and `tool_calls_limit` to cap the number of successful tool executions within a run.
    - The `tool_calls_limit` is checked before executing tool calls. If the model returns parallel tool calls that would exceed the limit, no tools will be executed.

+##### Soft Tool Call Limits with `max_tool_calls`


I think this belongs on tools-advanced.md, with a link from the usage limits section above.

And no need to mention the name of the field in the title, that'll make it too long for the ToC sidebar

DouweM · 2025-12-16T21:05:39Z

docs/agents.md

+result = agent.run_sync('Calculate something', max_tool_calls=1)
+```
+
+**When to use `max_tool_calls` vs `tool_calls_limit`:**


This sounds like something for the explanation in the previous section where we link to this feature. And for the primary docs of this feature where we mention how it's related to the UsageLimits hard limit.

DouweM · 2025-12-16T21:06:22Z

docs/tools-advanced.md


 !!! note "Limiting tool executions"
-    You can cap tool executions within a run using [`UsageLimits(tool_calls_limit=...)`](agents.md#usage-limits). The counter increments only after a successful tool invocation. Output tools (used for [structured output](output.md)) are not counted in the `tool_calls` metric.
+    You can cap the total number of tool executions within a run using [`UsageLimits(tool_calls_limit=...)`](agents.md#usage-limits). For finer control, you can limit how many times a *specific* tool can be called by setting the `max_uses` parameter when registering the tool (e.g., `@agent.tool(max_uses=3)` or `Tool(func, max_uses=3)`). Once a tool reaches its `max_uses` limit, it is automatically removed from the available tools for subsequent steps in the run. The `tool_calls` counter increments only after a successful tool invocation. Output tools (used for [structured output](output.md)) are not counted in the `tool_calls` metric.


The bit about max_uses should be in the next paragraph that's about soft limits, o that we can leave this one about hard limits.

DouweM · 2025-12-16T21:14:54Z

pydantic_ai_slim/pydantic_ai/_run_context.py

    retries: dict[str, int] = field(default_factory=dict)
    """Number of retries for each tool so far."""
+    tool_usage: dict[str, int] = field(default_factory=dict)
+    """Number of calls for each tool so far."""


We have to be consistent/specific about calls vs uses and how this relates to retries; does this imply successful calls, or any call at all?

DouweM · 2025-12-16T21:15:19Z

pydantic_ai_slim/pydantic_ai/_tool_manager.py

+        for tool in self.tools.values():
+            # Filter out tools that have reached their max_uses limit
+            if tool.max_uses is not None:
+                current_uses = self.ctx.tool_usage.get(tool.tool_def.name, 0)


get_current_use_of_tool

DouweM · 2025-12-16T21:15:41Z

pydantic_ai_slim/pydantic_ai/_tool_manager.py

+                if current_uses >= tool.max_uses:
+                    continue
+            result.append(tool.tool_def)
+        return result


I'd rather have this be a list comprehension

DouweM · 2025-12-16T21:16:57Z

pydantic_ai_slim/pydantic_ai/_tool_manager.py

+                max_uses=tool.max_uses,
            )

+            self.ctx.tool_usage[name] = self.ctx.tool_usage.get(name, 0) + 1


To me, "uses" implied successful uses of a potentially costly thing, so excluding retries. Otherwise I think it should definitely be max_calls. But I think that only tracking successful uses probably makes sense, so we don't punish models unnecessarily for an arg validation error

If we take it to mean "successful calls", then this part from #3352 (comment) will require special care, especially if we do it in ToolManager, because we don't want to run a max_uses=1 tool twice in parallel; the >1 calls should fail:

Another problem is when we are within one run step and the model does parallel function calling to the one-shot tool. How to stop the model technically (not by prompting or returning "do not call me again" - this works, but it is not real [and nice] control) from reusing this tool? Sequential=true appears too harsh since it makes other tool calls withing the same step sequential as well (I think).

DouweM · 2025-12-16T21:17:32Z

pydantic_ai_slim/pydantic_ai/_tool_manager.py

+    def _get_max_tool_calls(self) -> int | None:
+        """Get the maximum number of tool calls allowed during this run, or `None` if unlimited."""
+        if self.ctx is None:
+            raise ValueError('ToolManager has not been prepared for a run step yet')  # pragma: no cover


Let's move this to a private helper method like _assert_ctx() -> RunContext

DouweM · 2025-12-16T21:23:24Z

docs/tools-advanced.md

+async def raise_on_limit(
+    ctx: RunContext[Any], tool_def: ToolDefinition
+) -> ToolDefinition | None:
+    if ctx.max_uses and ctx.tool_usage.get(tool_def.name, 0) >= ctx.max_uses:


Another interesting example would be to check ctx.tool_use and do this from #3352 (comment):

A better approach may be to have the tool when output "This tool can only be called M more times." after its real result, so that it works like a counter that increases during the run of the conversation. But that'd definitely be something for the user to do, I think, not Pydantic AI itself.

adtyavrdhn added 10 commits December 10, 2025 08:38

init

017eac1

docstrings

190e230

docstrings + args

c9d7aed

documentation

909716b

type

3880ab6

fix

1d62583

better test

114d2eb

better test

64f359d

Merge branch 'main' of https://github.com/pydantic/pydantic-ai into p…

903d5d5

…er_tool_usage_limit

passing max_uses

8ba5cc8

adtyavrdhn changed the title ~~Per tool usage limit~~ Adding per tool usage limit Dec 11, 2025

adtyavrdhn added 12 commits December 16, 2025 19:57

Merge branch 'main' of https://github.com/pydantic/pydantic-ai into p…

0a96653

…er_tool_usage_limit

Adding hard / soft limit enforcement on UsageLimit directly, not sure…

ad40e36

… if it should be somewhere else altogether to cover granular limit exceeded as well?

lint

7554e0d

casting to none

3352ab3

default should be hard as per the existing behaviour

89265a4

Adding test to cover soft limit on global tool usage limit exceeded

776e542

renaming test

f981f99

Fixing inconsitency in one of the docstrings

34b830a

Adding doc and max_uses to runContext for use of the users

364295b

Adding max_tool_calls, soft limit to agent. Using tool manager to che…

283a3f3

…ck and enforce

docs update for max_tool_calls

3914322

test skip doc

0f63561

DouweM requested changes Dec 16, 2025

View reviewed changes

DouweM reviewed Dec 16, 2025

View reviewed changes

DouweM self-assigned this Dec 16, 2025

DouweM added the awaiting author revision label Dec 16, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Adding per tool usage limit #3691

Adding per tool usage limit #3691

adtyavrdhn commented Dec 10, 2025 •

edited

Loading

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

DouweM Dec 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		If you want to limit tool calls but let the model decide how to proceed instead of raising an error, use the `max_tool_calls` parameter. This is a "soft" limit that returns a message to the model when exceeded, rather than raising a [`UsageLimitExceeded`][pydantic_ai.exceptions.UsageLimitExceeded] exception.

		```py {test="skip"}


		1. Set the maximum number of tool calls allowed during runs. This can also be set per-run.

		When `max_tool_calls` is exceeded, instead of executing the tool, the agent returns a message to the model: `'Tool call limit reached for tool "{tool_name}".'`. The model then decides how to respond based on this information.

Adding per tool usage limit #3691

Are you sure you want to change the base?

Adding per tool usage limit #3691

Conversation

adtyavrdhn commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary: Per-Tool Usage Limits & Soft Tool Call Limits

1. max_uses - Per-Tool Usage Limit

2. max_tool_calls - Soft Total Tool Call Limit

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adtyavrdhn commented Dec 10, 2025 •

edited

Loading

1. `max_uses` - Per-Tool Usage Limit

2. `max_tool_calls` - Soft Total Tool Call Limit