Skip to main content
Glama
mcp-prometheus

mcp-prometheus

by mgcrea

Prometheus: Query Range

prometheus_query_range
Read-only

Evaluate a PromQL expression over a time range to find spikes, trends, or when a change started, returning per-series min, max, avg, and last stats or step-by-step values.

Instructions

Evaluate a PromQL expression over a time range, for how something changed: a spike, a trend, when it started. Each series comes back with stats (min, max, avg, last) and, with view=values, one value per step on a shared grid given by start and step (null where there was no sample) — no per-point timestamps. The step is picked for about 60 points unless given. Many series are expensive: aggregate in the query (sum by), or use view=stats with sort=max to find the outliers first.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "prometheus_query_range"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoRange end: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now.
sortNoOrder of series, applied before `limit` cuts: labels keeps Prometheus's order; max/avg/last rank highest first, so a cut keeps the biggest.labels
stepNoResolution, as a duration (30s, 5m, 1h) or seconds. Defaults to a round step giving about 60 points. Each series costs one value per step.
viewNovalues: stats plus the value at every step. stats: min/max/avg/last only, about a tenth of the size — use it to survey many series before plotting a few.values
limitNoMaximum series to return (1-500). Defaults to 20.
queryYesA PromQL expression, e.g. `sum by (namespace) (rate(http_requests_total{status=~"5.."}[5m]))`. Aggregate inside the expression (sum by, topk, count) rather than fetching raw series and reading them: Prometheus does the arithmetic exactly and the answer is a fraction of the size.
startNoRange start: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to an hour before end (now-1h when end is not given).
precisionNoSignificant digits to round fractional values to (whole numbers are never rounded). Defaults to 4; 0 returns the exact value. Raise it only when comparing values that differ past the fourth digit.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.2.0
    • changedInput schema / properties / start / description
      Previous value: -"Range start: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to now-1h."New value: +"Range start: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds. Defaults to an hour before end (now-1h when end is not given)."
  2. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description explains the return shape: per-series stats, optional per-step values, a shared start/step grid, nulls for missing samples, and no per-point timestamps. It also discloses cost behavior, noting that many series are expensive and that step resolution determines per-series cost. This is substantial behavioral context for an agent calling the tool.

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?

The description is front-loaded with the purpose, then immediately covers return shape, the step default, and performance guidance. Every sentence contributes either selection guidance or behavioral context, with no filler or repetition for its own sake.

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

Completeness5/5

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

For an 8-parameter, read-only range-query tool with full schema coverage and no output schema, the description supplies the key missing context: what comes back, how values align on a grid, how missing samples appear, and how to manage costly multi-series queries. An agent has enough information to call it correctly and interpret the result.

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 description coverage is already 100%, so the baseline is 3. The description nonetheless adds useful meaning beyond the schema: view=values returns a value per step on a shared grid with nulls where samples are absent, and sort=max with view=stats is a strategy for finding outliers before plotting. Most parameter mechanics are still carried by the schema, which keeps this below a top score.

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?

The description states a specific verb and resource: 'Evaluate a PromQL expression over a time range.' It also frames the intended question type (spike, trend, when it started), which distinguishes a range query from a current-value query. It does not explicitly name prometheus_query as the instant-query sibling, so sibling differentiation is implied rather than stated.

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?

It gives clear usage context: use this to see how something changed over time, such as a spike or a trend. It also advises on expensive queries by recommending aggregation in PromQL or surveying with view=stats and sort=max before plotting. It does not explicitly say when to prefer prometheus_query instead of this range tool.

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