Skip to Content

Tool loop

Tool Loop finds repeated calls to the same tool with the same arguments. It records a CF-01 finding with a reason, counts, and the calls that support it. Actionable findings feed the existing Tool Loop alert. You do not need to create a second rule.

Repeated calls can indicate wasted work, but they do not prove that the agent is stuck or that the tool returned the same result. A status check, for example, can legitimately use the same arguments and return a new result later.

What counts as a sequence

With the default minimum of three, this sequence can produce a finding:

search_orders(id=7) -> success search_orders(id=7) -> success search_orders(id=7) -> success

Only finished tool calls count. The tool name and captured, normalized arguments must match. In start order, neighboring identical calls can have at most one other tool call between them. Two or more intervening calls break the sequence.

In the default run scope, a turn span starts a new sequence. A pause longer than five minutes also breaks it; the pause is measured from the latest end of earlier tool calls. Identical calls that overlap in time are excluded on both sides of the overlap, so parallel fan-out is not a sequential loop.

The minimum is inclusive: three means at least three, not more than three. The time window selects recent activity for evaluation. It is not a count of every matching call anywhere in that window: sequence boundaries still apply, and the detector reads earlier calls to reconstruct a sequence.

Retries

Exclude retries is on by default. An errored call does not count and breaks its argument group’s sequence:

success -> error -> success # no three-call sequence success -> success -> error # no three-call sequence success -> error -> success -> success -> success # the last three can qualify

With retry exclusion off, errors count and do not create a retry boundary. The other sequence rules still apply.

Polling

Three or more calls at nearly regular intervals are classified as likely polling. Rius measures the variation in the gaps between call starts. A coefficient of variation below 0.2 qualifies; regular timing is a heuristic, not knowledge of the tool’s purpose.

10:00:00 check_status(job=123) -> running 10:00:10 check_status(job=123) -> running 10:00:20 check_status(job=123) -> completed

With Polling as info on, the finding is informational and does not create an alert. Turn the setting off if you want qualifying regular repetition to be actionable too. Irregular polling can still alert, and a real loop with regular timing can be classified as polling.

Across runs in a session

Session scope is off by default. When enabled, matching calls across runs with the same real session ID can form one sequence:

Session A Run 1: search_orders(id=7), search_orders(id=7) Run 2: search_orders(id=7)

The finding belongs to Run 2, where the third qualifying call occurred. Additional calls extend that finding while the sequence remains available to the detector. Run and turn boundaries do not split a session sequence; the pause, intervening-call, retry, and concurrency rules still apply. Runs without a real session ID are evaluated separately. The detector reads calls from 24 hours before the evaluation window starts through the end of that window, so it cannot reconstruct an unlimited session lifetime.

Tune the rule

Use the Tool Loop rule on the Alerts page or the MCP alert tools. Switches travel as 0 or 1 in rule config.

SettingConfig keyDefaultMeaning
Identical callsmin_identical_calls3Minimum sequence length, from 3 to 100000
Time windowwindow_minutes10Recent-activity window, from 5 to 1440 minutes
Exclude retriesexclude_retries1Exclude errors and split after an errored call
Polling as infopolling_as_info1Keep likely polling informational
Session scopesession_scope0Join qualifying calls across runs of one session

For example, the following MCP arguments enable alerts for qualifying polling and set the minimum to five:

{ "ref": "tool_loop", "config": { "min_identical_calls": 5, "polling_as_info": 0 } }

Pass them to update_alert_rule. This changes the existing rule, not a new copy. A stored legacy minimum of two is interpreted as three. Existing notification-channel and reminder settings still apply.

Findings, alerts, and notifications

A finding records the tool-name subject, severity, reason, call/error counts, and ordered evidence span IDs, capped at 50. It contains no raw arguments or tool results. Different argument groups can produce separate findings.

Finding severityMeaningCreates an alert?
InfoLikely polling, with Polling as info onNo
WarningSequence reaches your minimum and is not classified as infoYes, subject to rule settings
CriticalAt least five qualifying calls and more than your configured minimum, unless classified as infoYes, subject to rule settings

With a minimum of three, five calls are critical. With a minimum of five, the first five-call finding is warning and the sixth is critical.

An info finding stays included in finding_count, but does not set the run’s silent_failure flag. A live warning or critical finding does. Severity on the finding is separate from the alert’s open/resolved state.

Alerts group new actionable findings by rule, agent, and tool. Five repeated calls can produce one finding in one run, not five alert occurrences. Alert occurrences count findings, and the run count and sample traces describe the affected runs. Counts are not the tool-call total.

Notifications use the rule’s configured channels and acknowledgement/reminder policy. A Slack or email notification for a Tool Loop alert names the agent, the tool and the severity, carries the newest finding’s explanation, counts Findings rather than occurrences, and links to the run that holds the evidence. A webhook payload carries the same facts as severity and a finding object with trace_id, finding_key, severity, evidence_span_ids and the run url. Both keys are absent on alerts that are not built from run findings, such as Consistent Error Pattern, so an existing receiver of those sees the shape it always has. The alerts API returns the newest finding’s reason as summary and the same reference as sample.latest_finding.

Reading the same finding on another scan does not create a new alert occurrence. A warning that becomes critical under the same finding identity does not notify again and does not change the alert; the finding itself shows the current severity. A reminder repeats the summary and detects nothing new. An open alert resolves after the quiet period without new findings, two hours by default. Resolution means the detector reported nothing new, not that the agent recovered, and historical findings remain inspectable.

Investigate a finding

Use list_silent_failures in the MCP server with failure_mode: "CF-01", or read GET /v1/workspaces/{workspace_id}/findings. The tool name is the subject, the reason gives the counts, and the findings API’s evidence_span_ids identify the repeated calls in order. Use the returned trace ID to inspect the run; a notification for the alert links to the same run. With session scope, some evidence belongs to earlier runs in the session and will not appear in the owning trace’s span list.

The findings section on the trace detail page is separate console work. Until it is available in your deployment, read the evidence from the findings API; the MCP lists the reason and counts. Alert pages show grouped counts, and a notification carries the newest finding only, not every finding’s evidence.

Before changing thresholds, check whether the repeated call reads changing state, whether errors/retries explain it, and whether the selected scope matches how your application uses sessions. Tool Loop findings do not stop an agent or inject instructions. Agent feedback is a separate capability.

What to send

InputWhy it matters
Finished tool spans, stored with kind TOOLOnly tool calls participate; a generic CHAIN span does not
gen_ai.tool.nameTool identity; Rius falls back to the span name when absent
Captured gen_ai.tool.call.argumentsThe argument identity used to compare calls
Accurate start time, duration, and error statusSequence ordering, concurrency checks, and retry handling
CHAIN spans named turnOptional boundaries in run scope
A real session ID shared by the intended runsRequired for cross-run joining when session scope is enabled

Use the SDK integrations to instrument tool calls and check the attribute guidance when sending telemetry yourself. A captured empty object, {}, has an argument identity. Missing or withheld arguments do not; calls without an identity cannot establish repetition. Check your content-capture policy before enabling argument capture.

GET /v1/workspaces/{workspace_id}/silent-failures/coverage reports unavailable when required tool spans or arguments are absent. Missing optional inputs, such as agent root spans, makes repetition coverage partial. Use the response’s missing list to see which inputs your backend release checks. Coverage is workspace-level evidence that inputs exist, not a guarantee that every run is fully instrumented or that every scan succeeded.

Next steps

Last updated on