Skip to main content
Glama

Compare periods

compare_periods
Read-onlyIdempotent

Compares two Graylog log periods to show new, increased, gone, or decreased error groups, normalized per hour. Use it to spot regressions or improvements after a deploy or between windows.

Instructions

Compare two periods (default: last window vs the one before; or around split_at). Lists groups that are new, increased, gone or decreased, normalised per hour. Defaults to errors only.

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

Input Schema

NameRequiredDescriptionDefault
limitNoGroups to return
queryNoExtra Lucene filter
windowNoLength of each period when using split_at or the default1h
streamsNoStream titles or ids; default the repository's focus, else all. ['*'] for everything
group_byNo'exception', 'logger', 'source' or any fieldexception
instanceNoInstance from describe, e.g. 'payment/prod'; the default when omitted
split_atNoPoint in time (e.g. a deploy); compares [split-window, split] with [split, split+window]
current_toNoExplicit current period end; default now
baseline_toNoExplicit baseline end
errors_onlyNoAND the configured error query (default true)
current_fromNoExplicit current period start
baseline_fromNoExplicit baseline start

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.1
    • 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"
  2. Changed2 schema fields changedv0.2.0
    • 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"
  3. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description's job is to add analytical behavior — and it does: results are normalised per hour, the comparison defaults to the immediately preceding window, and output is bucketed into new/increased/gone/decreased. It omits whether results are sorted or truncated by limit, and says nothing about latency or data-freshness.

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

Conciseness5/5

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

Three compact sentences, front-loaded with the core action and the two comparison modes, then the output semantics, then the default filter. No filler and no repetition of the schema text.

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 12-parameter, no-output-schema analytical tool this covers the essential mental model: two comparison modes, per-hour normalisation, and the error-only default. The remaining gap is the precedence between the explicit *_from/*_to parameters, window, and split_at, which an agent would have to infer.

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%, so the baseline is 3. The description does add real meaning on top of the schema by explaining that window defines each period in the default and split_at modes and that errors_only defaults to on ('Defaults to errors only'), but it does not clarify how the explicit current_from/baseline_from parameters interact with window or split_at.

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

Purpose4/5

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

States a specific verb and resource ('compare two periods') and describes the output shape: groups that are new, increased, gone or decreased, normalised per hour. This clearly separates it from aggregate/scan/search_logs in spirit, but it never names or contrasts a sibling explicitly, so it stops short of a 5.

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

Usage Guidelines3/5

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

Usage is implied through the default mode (last window vs the previous one) and the split_at mode (e.g. around a deploy), which gives an agent a concrete scenario. However, there is no explicit guidance on when to prefer this over aggregate or root_cause, and no statement of when not to use it.

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