Skip to main content
Glama

Topolograph

get_events_timeline

Read-onlyIdempotent

Description: This tool returns node/host up/down events already grouped into chronological time waves (server-side), so you can narrate a network incident ("instability started at T from device X; a flapping burst from device Y; reconverged at T+n") without scanning hundreds of raw events. Waves hold adjacency up/down only: metric (cost) changes are not in them, so for "what happened" also call get_adjacency_events for the same window and report its cost changes with the waves. Events exist ONLY for watcher-monitored graphs (is_monitored=true); first call get_all_graphs(is_monitored=true, latest_only=true). Returns wave summaries only (no nested event arrays): to get a wave's individual events, call get_adjacency_events with that wave's start_ts/end_ts.

Input fields: graph_time (str): The graph time to filter events. start_time (str, optional): Start time in ISO format (e.g., 2025-06-30T20:00:00Z) end_time (str, optional): End time in ISO format. Defaults to current time if not provided. last_minutes (int, optional): Look back this many minutes; overrides start_time/end_time. page (int, optional): Page number (1-indexed) over the waves list. per_page (int, optional): Number of waves per page.

Output fields: EventsTimelineResponse: A dictionary with keys: - graph_time, watcher_name - gap_multiplier, median_gap_sec: how the grouping was computed - waves: list of per-wave summaries, each with wave_number, start_ts, end_ts (ISO 8601, reusable as start_time/end_time), duration_sec, event_count, distinct_devices, trigger_device, pattern ("outage" left down / "flap" down then up / "up" only ups), converged (recovery seen within the queried window; a recovery after end_time is not counted) - pagination: page, per_page, total, total_pages

Equivalent to GET /events/{graph_time}/adjacency/timeline.

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": {
      "graph_time": "<graph_time>"
    },
    "name": "get_events_timeline"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo
end_timeNo
per_pageNo
graph_timeYes
start_timeNo
last_minutesNo

Output Schema

NameRequiredDescriptionDefault
wavesYes
graph_timeYes
paginationYes
watcher_nameYes
gap_multiplierYes
median_gap_secYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavior the annotations cannot: grouping is done server-side, waves contain summaries only with no nested event arrays, and 'converged' has a precise edge case (a recovery after end_time is not counted). The monitored-graphs-only constraint is the kind of availability caveat that prevents wasted calls.

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?

The definition is front-loaded: purpose, then the companion-call guidance, then the prerequisite, then the drill-down path, all before the field lists. The narration example in parentheses earns its place by showing the intended output use, but the 'Output fields' block largely restates a return structure that already exists as an output schema, and the trailing REST-endpoint line adds little.

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 a six-parameter, paginated, incident-narration tool, an agent has everything needed to call it correctly: prerequisites, window semantics, pagination, drill-down route, and the meaning of each wave attribute. The output schema covers return shape, so the description's remaining gaps are cosmetic rather than blocking.

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?

With 0% schema description coverage the description carries the full burden, and it does document five of six parameters usefully, including an ISO format example and the override rule that last_minutes supersedes start_time/end_time. The required parameter is the weakest: 'graph_time (str): The graph time to filter events' is near-tautological and never says whether it is an ISO timestamp or an opaque graph identifier, which matters because it is the only required field.

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 first sentence gives a specific verb and resource ('returns node/host up/down events already grouped into chronological time waves') plus the operational payoff. It explicitly separates itself from get_adjacency_events by stating waves hold adjacency up/down only and cost changes are excluded, so an agent can distinguish the two siblings without opening either schema.

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

Usage Guidelines5/5

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

It names a prerequisite call (get_all_graphs with is_monitored=true, latest_only=true), states a hard availability constraint (events exist ONLY for watcher-monitored graphs), and prescribes a companion call ('also call get_adjacency_events for the same window') for the cost-change side of the story. It also routes drill-down to get_adjacency_events with a wave's start_ts/end_ts rather than leaving the agent to guess.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.