My AI agent keeps calling the same tool. How do I find the cause?

Rius detects an agent stuck on one tool with its pre-defined Tool Loop alert, and you find the cause in the trace: the repeated tool spans, their arguments, and the prompt before each call. Start from the Tool Loop alert or from your agent’s page, open an affected trace, and read what the model saw before each repeat. Rius shows the loop as one collapsed row, so you can tell a retry loop from a model that never gets the result it wants.

How it works

Tool Loop is one of the pre-defined alerts. It fires when the same tool is called with identical parameters at least 3 times in a row inside a single trace. Calls count as identical when the tool name and normalized arguments match. The calls must form a run: in start order, at most one other tool call sits between neighboring repeats. A tool the agent returns to after other work is routine and does not fire. There is one firing per trace and tool.

Three settings shape it:

• Identical calls: at least 3, which is also the minimum.
• Time window: 10 minutes by default.
• Renotify: off by default, so the notification is sent once.

The alert’s details page shows its description, settings, attached channels and firing history. Tool Loop cannot be narrowed to one service. If the alert never fires, check whether content capture is off: calls whose arguments were not captured are never counted as identical.

The cause sits in the trace. In the Exploring traces views, back-to-back calls of the same tool collapse into one row such as fetch_article · 3 attempts · recovered. Expand it to read each attempt. The usual causes are:

• The same search repeated because no result meets the agent’s stop condition.
• A broken tool schema, so the model retries the identical call and never gets a different outcome.
• A planner and executor cycling on the same lookup.

These are the three loop shapes the alert is built to catch, so the spans below tell you which one you have. For the wider picture of watching agents, see Monitor AI agents in production.

Set it up

1. Open the alert. Go to the Tool Loop alert and read its firing history to see when loops happened.
2. Find the traces. Open the Traces page and set the time range. Use Add filter to narrow to the agent that loops, or open the agent from the Agents page and use Recent traces and Errored traces. A trace with an unusually high token total or cost is a good candidate. On the agent page, the Drift chart for cost per trace shows when loops started to push cost up.
3. Isolate the tool spans. On the Spans tab, use the All kinds menu to pick Tool. Sort by Tokens, Cost or Duration, or search a trace ID, to see the repeated calls.
4. Read the repeated calls. Open the trace and find the collapsed retry row. Expand it and compare the attempts. In Raw or Input / Output, check the arguments. Identical arguments each time mean the model gets nothing new from the result. If the tool span has an error, read the exception and traceback in the detail panel.
5. Read what the model saw. Select the LLM span just before a repeated call. On Input / Output, switch to Since previous llm call to see what each step added to the prompt. If the tool result is empty, truncated or an error, that is the likely cause. If the prompt never changes between calls, the model has no reason to act differently.
6. Check context growth. For a trace with several LLM calls, look at the strip above the tree that plots input tokens per call. A steadily climbing strip points to history growing on every loop.
7. Check whether a release caused it. Tag your runs with versions, then compare versions on the agent page:

RIUS_MAIN_AGENT_VERSION=prompt-v12      # the agent definition: prompt, tools, policy
RIUS_SERVICE_VERSION=2026.09.29-a41f3c  # the build or deploy

If cost per trace rose after a new prompt or tool change, that change is your suspect. You can also use Compare runs on a trace to put it next to a healthy run of the same agent and see which steps were added.

What you get

• An alert on the loop itself, so you do not wait for a bill to notice it.
• One collapsed row per retry chain, with the number of attempts, instead of a wall of identical spans.
• The arguments and results of each repeated call, plus the exact change in the prompt between LLM calls, so you can see why the model asked again.
• A cost and token view per trace and per agent, so you see how much the loop cost.
• A version comparison that ties the start of the loop to a prompt, tool or build change.

When something else fits

• The alert will not fire on loops where the tool alternates with several other tools, or where arguments change slightly each time. Use the trace views and the context growth strip to spot those.
• If a run hangs instead of repeating calls, heartbeats show only that the process is alive. With partial spans turned on, look for traces stuck on running… instead.
• For a loop on a cost or token threshold rather than identical calls, a custom alert on those measures fits better.

Related