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) -> successOnly 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 qualifyWith 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) -> completedWith 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.
| Setting | Config key | Default | Meaning |
|---|---|---|---|
| Identical calls | min_identical_calls | 3 | Minimum sequence length, from 3 to 100000 |
| Time window | window_minutes | 10 | Recent-activity window, from 5 to 1440 minutes |
| Exclude retries | exclude_retries | 1 | Exclude errors and split after an errored call |
| Polling as info | polling_as_info | 1 | Keep likely polling informational |
| Session scope | session_scope | 0 | Join 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 severity | Meaning | Creates an alert? |
|---|---|---|
| Info | Likely polling, with Polling as info on | No |
| Warning | Sequence reaches your minimum and is not classified as info | Yes, subject to rule settings |
| Critical | At least five qualifying calls and more than your configured minimum, unless classified as info | Yes, 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
| Input | Why it matters |
|---|---|
Finished tool spans, stored with kind TOOL | Only tool calls participate; a generic CHAIN span does not |
gen_ai.tool.name | Tool identity; Rius falls back to the span name when absent |
Captured gen_ai.tool.call.arguments | The argument identity used to compare calls |
| Accurate start time, duration, and error status | Sequence ordering, concurrency checks, and retry handling |
CHAIN spans named turn | Optional boundaries in run scope |
| A real session ID shared by the intended runs | Required 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
- Failure modes: how
CF-01relates to alert kinds. - Distribution channels: configure delivery.
- Context rot: a different detector for context pressure and history loss.