Skip to main content
Glama

Trace request

trace_request
Read-onlyIdempotent

Follow a single request across services by searching trace fields on all streams, then return a chronological timeline, per-service durations, and the first error.

Instructions

Follow one request across services: searches the configured trace fields (falls back to full text) on all streams and returns a chronological timeline, per-service steps with durations, and the first error.

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": {
      "trace_id": "<trace_id>"
    },
    "name": "trace_request"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax messages in the timeline
rangeNoRelative range ending now or at to_time: '15m', '2h', '1d'24h
streamsNoStream titles or ids; default the repository's focus, else all. ['*'] for everything
to_timeNoAbsolute end; default now
instanceNoInstance from describe, e.g. 'payment/prod'; the default when omitted
trace_idYesCorrelation / request / trace id to follow
from_timeNoAbsolute start, overrides range: ISO 8601 or 'YYYY-MM-DD HH:MM'

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. Changed5 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 / range / description
      Previous value: -"Relative range ending now (or at to_time): '15m', '2h', '1d', '1h30m'"New value: +"Relative range ending now or at to_time: '15m', '2h', '1d'"
    • 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

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds real behavioral detail beyond that: the lookup searches configured trace fields first and falls back to full text, and the response is a chronological timeline with per-service step durations and the first error. It does not mention cost, truncation via the limit, or latency, so it is not fully saturating.

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?

One sentence, front-loaded with the purpose and then a compact colon-led breakdown of mechanism and return shape. No filler, and the parenthetical fallback note earns its place by explaining matching behavior.

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 seven parameters, no output schema and full schema coverage, the description does the right work: it sketches the return value (timeline, per-service durations, first error) without duplicating parameter docs. The claim of searching 'all streams' sits slightly at odds with the schema default of the repository's focus stream, and no note on result truncation is given, keeping it below a 5.

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 would be acceptable, but the description actually adds meaning: it clarifies how trace_id is matched (configured trace fields, then full-text fallback) and that the search spans streams, which contextualizes the streams and limit parameters. It still leaves range/to_time/instance semantics to the schema.

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 names a specific verb and resource — follow one request across services — and adds the mechanism (search configured trace fields, fall back to full text). That mechanism naturally separates it from a generic log search, but no sibling such as search_logs or root_cause is named 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 by the phrase 'follow one request across services', which suggests calling it when you have a correlation id and need an end-to-end view. It gives no explicit when-not conditions and never points to an alternative tool for cases where the timeline output is overkill or where no trace id is available.

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