Skip to main content
Glama

Capture index (ring-buffer files in time order)

capture_index
Read-onlyIdempotent

Index a directory of capture files in time order without decoding packets: get per-file time spans, packet and byte counts, gaps, overlaps, and which files cover an incident window.

Instructions

Index a directory of capture files (a ring buffer, a day of rotated files) in time order without decoding a packet: per file the first and last packet time, duration, packets, bytes, interfaces and link type, the hole or overlap against the previous file, and with start/end (same forms as on every tool) covers_window: which files to open for an incident window. summary gives the span, totals, holes (gaps longer than min_gap_s seconds between files, default 1), overlaps, ordering (whether name order is time order: a wrapped ring or renamed files break it) and for a window window_files and window_covered. More detail: resource schema://tools/capture_index.

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": {
      "path": "<path>"
    },
    "name": "capture_index"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoWindow end, same forms as start
pathYesAbsolute path of a directory of capture files
startNoWindow start: ISO 8601, epoch s, +Ns from the first file, -Ns from the last
offsetNoRows to skip (next_offset)
redactNoReplace subscriber identifiers in this result with tokens; ids+ips hides every IP toooff
max_filesNoMost files read in this call
min_gap_sNoShortest gap between files reported as a hole, seconds

Output Schema

NameRequiredDescriptionDefault
pathNo
countNo
errorNo
filesNorows with keys: path, name, first, last, first_epoch, last_epoch, duration_s, packets, bytes, interfaces, file_type, link_type, covers_window, gap_before_s, overlap_before_s, error, message
issuesNo
offsetNo
windowNo
droppedNo
summaryNo
has_moreNo
returnedNo
files_foundNo
next_offsetNo
total_foundNo
files_indexedNo
total_matchedNo
packets_matchedNo
packets_scannedNo
files_not_indexedNo
total_is_lower_boundNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/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 closed-world, so safety is covered; the description adds real behavior beyond that: no packet decoding occurs, name order may not be time order (wrapped rings and renamed files break it), and holes are thresholded by `min_gap_s` (default 1). It does not say what happens when `max_files` (default 50) truncates the read, which is the one behavioral gap an agent would want flagged.

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 verb and the no-decoding differentiator, and every clause carries information (output fields, ordering caveat, hole threshold, window mode). The first sentence is very long and backtick-dense, which costs some readability, but there is no filler.

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?

An output schema exists, so enumerating return fields is technically optional, yet the description still covers purpose, window semantics, ordering risk and hole detection — everything needed to decide whether and how to call it. A resource pointer (schema://tools/capture_index) is provided for deeper detail.

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 schema already documents `start`, `end`, `offset`, `redact`, `max_files` and `min_gap_s`; the description mainly restates them. It does add one piece of meaning — that `start`/`end` use 'the same forms as on every tool' and that supplying them switches the result to window mode with `covers_window` — but that is marginal on top of a fully documented schema, so the baseline 3 applies.

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?

Names a specific verb and resource ('index a directory of capture files'), characterizes the input shape (a ring buffer, a day of rotated files) and adds the key differentiator 'without decoding a packet', which separates it from every decode-oriented sibling such as open_capture or filter_packets. The output fields listed (first/last packet time, duration, packets, bytes, interfaces, link type, hole/overlap vs previous file) make the tool's job unmistakable.

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?

Gives a concrete use case — passing `start`/`end` to get `covers_window`, i.e. which files to open for an incident window — which tells an agent this is the pre-flight step before opening captures. It does not name an alternative tool or state a when-not-to-use condition, but the scope is narrow enough that the implied guidance is clear.

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