Skip to main content
Glama

Root cause

root_cause
Read-onlyIdempotent

Identify the first failing service by comparing errors, traffic and latency to a baseline, detecting deploys/restarts, and returning a ranked incident verdict with timeline and evidence.

Instructions

Find which service broke first and why. Compares every service's errors, traffic and latency with a baseline, pins the first error of each to the millisecond, detects deploys/restarts/host rollouts from the logs, infers the call graph from traces, and returns a ranked verdict with a timeline and evidence. Start here for 'what is causing this incident?'. view='changes': only the deploys and restarts found in the logs (new version-field values, host rollouts, start/stop lines). view='service_map': only which service calls which, from sampled traces, with traffic, error rate and p50/p95 latency per edge.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "root_cause"
  }
}

Input Schema

NameRequiredDescriptionDefault
viewNoWhat to return; 'verdict' by defaultverdict
queryNoOptional Lucene filter for scope, e.g. 'env:prod'
rangeNoWindow to analyse (the incident): '30m', '1h'; 6h for changes, else 1h
sampleNoservice_map: number of traces to sample (200)
streamsNoStream titles or ids; default the repository's focus, else all. ['*'] for everything
to_timeNoAbsolute end; default now
baselineNoverdict: length of the normal period right before the window; same as the window
instanceNoInstance from describe, e.g. 'payment/prod'; the default when omitted
from_timeNoAbsolute start, overrides range: ISO 8601 or 'YYYY-MM-DD HH:MM'

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.3.1
    • changedInput schema / properties / baseline / description
      Previous value: -"Length of the normal period right before the window; same as the window by default"New value: +"verdict: length of the normal period right before the window; same as the window"
    • changedInput schema / properties / instance / description
      Previous value: -"Instance from list_instances, e.g. 'payment/prod'; the default when omitted"New value: +"Instance from describe, e.g. 'payment/prod'; the default when omitted"
    • changedInput schema / properties / range / default
      Previous value: -"1h"New value: +null
    • changedInput schema / properties / range / description
      Previous value: -"Window to analyse (the incident), e.g. '1h', '30m'"New value: +"Window to analyse (the incident): '30m', '1h'; 6h for changes, else 1h"
    • addedInput schema / properties / sample
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 1000,
      +      "minimum": 10,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "service_map: number of traces to sample (200)",
      +  "title": "Sample"
      +}
    • addedInput schema / properties / view
      Added value: +{
      +  "default": "verdict",
      +  "description": "What to return; 'verdict' by default",
      +  "enum": [
      +    "verdict",
      +    "changes",
      +    "service_map"
      +  ],
      +  "title": "View",
      +  "type": "string"
      +}
  2. Changed4 schema fields changedv0.2.0
    • changedInput schema / properties / from_time / description
      Previous value: -"Absolute start: ISO 8601 or 'YYYY-MM-DD HH:MM' in the instance timezone; overrides range"New value: +"Absolute start, overrides range: ISO 8601 or 'YYYY-MM-DD HH:MM'"
    • changedInput schema / properties / instance / description
      Previous value: -"Graylog instance (environment) from list_instances, e.g. 'staging' or 'prod'; the default instance when omitted"New value: +"Instance from list_instances, e.g. 'payment/prod'; the default when omitted"
    • changedInput schema / properties / streams / description
      Previous value: -"Stream titles or ids to search in; all streams when omitted"New value: +"Stream titles or ids; default the repository's focus, else all. ['*'] for everything"
    • changedInput schema / properties / to_time / description
      Previous value: -"Absolute end, same formats as from_time; default now"New value: +"Absolute end; default now"
  3. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is added context, and it delivers: the baseline comparison method, millisecond-resolution first-error detection, log-derived deploy/restart/host-rollout inference, trace-derived call graph, and a ranked verdict with timeline and evidence. An agent knows what analysis it gets and what output shape to expect without an output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the one-line purpose, then mechanics, then view semantics — no filler. It is dense and long-ish for a description, but each clause carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, zero-required, no-output-schema tool that returns a verdict plus timeline, the description conveys both method and output form well. It leaves minor gaps: no guidance on cost/latency of the analysis, behavior when no anomaly is found, or when to prefer compare_periods over the built-in baseline comparison.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so a baseline of 3 applies, but the description adds real meaning for the most consequential parameter by spelling out what 'changes' and 'service_map' return, which the schema enum only names. It does not clarify baseline, instance, or streams semantics beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and outcome: 'Find which service broke first and why,' then enumerates the concrete mechanics (baseline comparison of errors/traffic/latency, first-error pinning, deploy detection, trace-derived call graph, ranked verdict). It is clearly distinguishable from siblings like aggregate, compare_periods and scan, which do not produce a ranked root-cause verdict.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Start here for "what is causing this incident?"' gives an explicit entry-point rule, and each view value is scoped ('view=changes' only deploys/restarts, 'view=service_map' only edges from sampled traces). It never states when NOT to use it or names a sibling to fall back to, so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.