graylog-mcp

Scan

scan

Read-onlyIdempotent

Run a health check across Graylog logs to detect crashes, resource exhaustion, error spikes, 5xx, timeouts, database and auth failures; only fired rules return with counts and samples.

Instructions

Health scan in one call: runs every scan rule (crashes, resource exhaustion, error spikes, new error types, 5xx, timeouts/connectivity, database, auth failures, plus the rules in the config) concurrently with exact counts against a baseline, and returns only what fired, most severe first, with the query, top groups and a sample. Start here for 'is anything wrong?', 'scan for errors', 'check X'. For a specific need pass rules (names/tags) or checks (ad hoc rules).

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": "scan"
  }
}

Input Schema

Name	Required	Description	Default
`query`	No	Extra Lucene filter applied to every rule, e.g. 'env:prod'
`range`	No	Window to scan, ending now (or at to_time): '15m', '1h', '24h'	1h
`rules`	No	Rule names or tags from list_scan_rules (e.g. ['errors'], ['connectivity', 'database']); all rules when omitted, unless checks is given (then add 'all' to run them too)
`checks`	No	Ad hoc rules for what the user asks to scan, same keys as a configured rule: {'name': 'declined', 'query': 'message:declined', 'threshold': 0} fires on any match; {'query': '...', 'growth': 2, 'min_count': 10} on a doubled rate; {'errors_only': true, 'group_by': 'exception', 'new_groups': true} on new error groups. Add 'per_traffic': true to a growth check on anything that follows traffic (errors, 5xx, timeouts) so it compares shares of traffic, with 'traffic_query' for what counts as traffic. Optional keys: severity, exclude, baseline, baseline_shift, confidence (default 0.99), group_by
`samples`	No	Attach one sample message per finding
`streams`	No	Stream titles or ids; default the repository's focus, else all. ['*'] for everything
`to_time`	No	Absolute end; default now
`baseline`	No	Length of the normal period right before the window, to compare rates with; same as the window by default. A longer one ('24h') is steadier for spiky traffic
`instance`	No	Instance from list_instances, e.g. 'payment/prod'; the default when omitted
`from_time`	No	Absolute start, overrides range: ISO 8601 or 'YYYY-MM-DD HH:MM'
`min_severity`	No	Run only rules at least this severe: critical \| high \| medium \| low	low
`baseline_shift`	No	Seasonal baseline instead: compare with the same window shifted back by this ('1d' for the same hour yesterday, '7d' for last week), several times; the median period is the reference. Use it for traffic with a daily or weekly curve
`baseline_periods`	No	How many shifted periods baseline_shift compares with

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.0Nov 6, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the description is not obligated to cover safety, yet it adds real behavioral context: rules run concurrently against a baseline with exact counts, and the response is filtered to only fired findings ordered by severity and enriched with query, groups and a sample. It omits the cost side of a wide fan-out scan (latency, whether all rules are always executed, behavior when nothing fires), which keeps it out of the top band.

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?

Front-loaded with the core purpose and the "start here" routing cue, with no filler or marketing language. The long enumeration of rule families and the trailing conditional sentence are dense, but they serve retrievability — an agent can confirm coverage questions like "does this check auth failures?" from the description alone.

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?

With 13 optional parameters, no output schema and a nested checks DSL, the description does the necessary work: it explains what comes back (fired findings, severity order, query/groups/sample) and how to scope with rules vs checks. The remaining gap is operational — no guidance on runtime cost, result limits, or what an empty result means for a health check.

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

Parameters3/5

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

Schema description coverage is 100% and all 13 parameters carry detailed prose, including baseline_shift semantics and the checks mini-DSL, so the schema does the heavy lifting and a 3 is the baseline. The description's only added meaning is the rules-vs-checks selection hint, which largely restates schema text; it adds nothing on baseline, baseline_periods or min_severity behavior.

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?

The description opens with a concrete verb and resource ("Health scan in one call") and enumerates the actual rule families it evaluates: crashes, resource exhaustion, error spikes, new error types, 5xx, timeouts/connectivity, database, auth failures. It also states the distinctive output contract (only fired findings, most severe first, with query, top groups and a sample), which separates it from sibling summarizers like error_summary or detect_changes without needing to open the schema.

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 'is anything wrong?', 'scan for errors', 'check X'" gives an explicit default-entry-point rule, and "For a specific need pass rules (names/tags) or checks (ad hoc rules)" tells the agent how to narrow scope, implicitly routing to list_scan_rules for names. It stops short of naming when NOT to use it or pointing at specific alternatives (error_summary, root_cause, detect_changes) for drill-down work.

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