Skip to main content
Agents get work done by calling tools. A single message from a user can trigger a handful of tool calls, or a hundred, depending on what’s being asked. Mindset AI agents manage how many tool calls happen inside one turn so conversations stay responsive and predictable, while still letting an agent work through genuine bulk jobs. This page explains how the per-turn budget works, what your users see when an agent checks in, what happens when a tool keeps failing, and how to stop a turn programmatically.

​
What a turn is

A turn is everything the agent does in response to a single user message. The agent might reason, call several tools, read the results, call more tools, and then reply. All of that is one turn. The tool budget is measured per turn and resets every time the user sends a new message. Nothing carries over from one turn to the next, so a fresh message always starts the agent with a full budget.

​
How the per-turn tool budget works

An agent calls tools freely at the start of a turn. Once a turn passes 20 tool calls, Mindset AI looks at the user’s original request and decides whether the work genuinely calls for that volume.
  • If the request is clearly bulk work, like “update every open requisition” or “pull all records for this account,” the agent keeps going up to a hard ceiling of 150 tool calls in the turn.
  • If the request doesn’t look like bulk work, the agent pauses, summarizes what it has done so far, and asks the user whether to continue.
The 150 ceiling is an absolute limit for a single turn. An agent that reaches it stops and asks the user to continue, the same way it does at the lower threshold.

​
What counts as a tool call

The budget tracks the tool calls an agent actually runs during a turn. A call counts as soon as it runs, whether it succeeds or returns an error, because either way the agent sent the request and got a response back. A few things don’t count:
  • Calls the agent prepares but doesn’t end up running.
  • Calls still queued in a parallel batch that haven’t run yet.
So the budget measures completed tool calls, not every call the agent considers.

​
When the agent checks in

When an agent reaches a point where it should pause, it doesn’t fail or throw an error. It tells the user what it has done so far and asks whether to keep going. Progress is described in terms that matter to the user, like records or items, not in tool calls. A single item can take more than one tool call to handle, such as a lookup followed by an update, so an agent can reach its tool-call limit before it has worked through every item. Where it can count progress it gives the numbers, and where it can’t it describes how far it got:
I’ve updated the first batch of records and reached my tool-call limit for this turn. Would you like me to continue?
The user gets a Yes, continue button. Selecting it starts a new turn, and the agent picks up where it left off with a full budget again. If quick replies are turned off for the agent, the user continues by sending a normal message instead. Each continue is a fresh turn with a full budget, so a large job can run across as many turns as it needs. The check-in is where a person stays in control of long-running work, instead of the agent making a long run of silent calls on its own.

​
When a tool keeps failing

Sometimes a tool errors repeatedly inside a single turn. If the same tool fails three times in one turn, the agent stops calling it for the rest of that turn. Instead of retrying endlessly, it works with what it has already gathered and tells the user the tool is currently unavailable, including a plain-language reason for the failure:
I tried to retrieve the user records, but that tool is currently unavailable. Here’s what I gathered from the other sources I could reach. You may want to try again shortly, or contact your administrator if this keeps happening.
This protects your users and your connected systems. Without it, an agent can sit in a retry loop against a failing tool, which adds latency, burns through the turn, and for tools that write data can create duplicate or partial records. The failure count is tracked per tool, so one flaky tool failing three times won’t stop the agent from using every other tool. Like the budget, it resets at the start of the next turn. If a tool you’ve connected fails often, this behavior will surface it. A connected service that returns frequent errors, even transient ones that succeed on a retry, is more likely to reach the three-failure point and be set aside for the turn. Returning clear error detail from your tools also helps, because the agent can tell the difference between a request it should fix and one it should simply retry later.

​
Calling many tools at once

When a turn needs a lot of tool calls, an agent often fires several at the same time rather than strictly one after another. Mindset AI paces this: a small number run concurrently (currently up to five), and the rest queue and start as slots free up. A burst of activity never hits a connected service all at once, which matters when a tool talks to a rate-limited or load-sensitive system. The pacing also lets the safeguards act sooner. The per-turn budget and the failure breaker are re-checked as the batch works through, so a tool that starts failing partway through a large batch is set aside before the rest of the batch piles on, rather than only after every call has run. You can rely on this pacing, but for a tool that writes data or is sensitive to repeated calls, designing it to be idempotent and to tolerate retries is still the most robust approach.

​
Stopping a running turn

A user can stop a turn while it’s in progress. In an agent chat interface, the Send button becomes a Stop button while the agent is working. Selecting it halts the current turn. The user keeps everything that was already shown, the turn is marked as interrupted, and the conversation stays open so they can send the next message straight away. For programmatic and headless integrations, the <mindset-agent> element exposes a stop() method. In headless mode there’s no chat interface, so stop() is the only way to cancel a turn. 
const agent = document.querySelector('mindset-agent');

// Stop the turn that's currently running.
// Calling stop() when no turn is running does nothing.
agent.stop();
When a turn is stopped, the element dispatches a mindset:turn-aborted event so you can react in your own UI. 
const agent = document.querySelector('mindset-agent');

agent.addEventListener('mindset:turn-aborted', () => {
  // The user stopped the turn. Re-enable your input,
  // update state, or log it as needed.
  console.log('The current turn was stopped.');
});
After a turn is stopped, the agent is idle and the thread is ready for the next message. Mindset AI keeps only what the user saw and never replays the unfinished remainder of the stopped turn.

​
Designing agents for larger jobs

A few things help your agents work smoothly within these limits:
  • For agents that do bulk work, write instructions that have them work in sensible batches and confirm progress with the user. The agent will check in on its own when it reaches the budget, but explicit pacing reads as deliberate and keeps users informed.
  • Make sure connected tools return useful error messages. An agent recovers far better from “office code not found” than from a generic failure with no detail.
  • Expect long jobs to span more than one turn. Continuing is a single tap for the user, and each turn resets the budget, so there’s no ceiling on the total amount of work an agent can do across a conversation.
The 20 and 150 thresholds are current platform defaults. They apply per turn and reset with every new user message.