Skip to main content
Glama

Capture file metadata (writer, interfaces, drops)

capture_metadata
Read-onlyIdempotent

Reads capture-file metadata without decoding packets to report drops, snaplen, capture filters, writer tool/OS, interfaces, statistics, and plain-language issues.

Instructions

What the capture file says about itself, read from the pcapng blocks without decoding a packet: did the capture box drop packets, which snaplen and capture filter were used, which tool and OS wrote the file, which interfaces are in it. file: format, version, byte order, compression, section count. writer: the section header's application, OS, hardware and comment. interfaces[]: id, name, description, link type, snaplen, timestamp resolution and offset, capture filter, and from the Interface Statistics Block (tshark has no field for it) statistics.received, dropped_by_interface, dropped_by_os, accepted_by_filter, delivered with their timestamps; plus packets, bytes, first/last packet, packets cut to the snaplen, timestamps going backwards, and when the first packet came relative to interface 0. drops_total sums the drop counters (absent when no statistics block was written). packet_comments: count and the first five. issues in plain words (drops, a tiny snaplen, a capture filter, no statistics block, concatenated sections). A legacy pcap returns its header with metadata_available: false. Bounded by the file size cap and the run timeout; strings come from the file's writer and are untrusted.

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_metadata"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesCapture file (absolute, in an allowed dir) or open_capture handle
redactNoReplace subscriber identifiers in this result with tokens; ids+ips hides every IP toooff

Output Schema

NameRequiredDescriptionDefault
fileNo
noteNo
pathNo
errorNo
issuesNo
windowNo
writerNo
packetsNo
sectionsNo
interfacesNorows with keys: id, section, name, description, link_type, link_type_name, snaplen, timestamp_resolution, timestamp_offset_s, capture_filter, statistics, packets, bytes, first, last, truncated_packets, timestamps_backwards, first_packet_after_interface_0_s
drops_totalNo
read_warningsNo
packet_commentsNo
metadata_availableNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real operational context: it is bounded by a file size cap and run timeout, legacy pcap returns metadata_available: false, drops_total is absent when no statistics block exists, and writer strings are untrusted. The untrusted-string warning and the timeout/size limits are exactly the kind of disclosure annotations cannot carry, though return-shape redundancy with the output schema trims this from a 5.

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

Conciseness3/5

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

The purpose is front-loaded in the first clause, but the body is a long run-on enumeration of every returned field (statistics counters, timestamp resolution, snaplen cuts), much of which duplicates the output schema that already exists. It reads as a documentation dump rather than a selection aid.

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 metadata-extraction tool with an output schema and full parameter coverage, nothing an agent needs is missing: edge cases (legacy pcap, missing statistics block), resource limits (file size cap, run timeout), and a security caveat about untrusted writer strings are all present.

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 coverage is 100% with only two parameters, so the schema already documents both `path` (absolute or open_capture handle) and the `redact` enum. The description adds no format, path-resolution, or interaction detail for either parameter — notably it never mentions redaction at all — so this sits at the baseline.

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 opening sentence gives a specific verb and resource — reading what the capture file says about itself from pcapng block headers — and draws an explicit boundary ('without decoding a packet') that separates it from packet-level siblings like packet_detail or filter_packets. It then enumerates the concrete sub-resources returned (file, writer, interfaces[], drops_total, packet_comments, issues).

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 rather than stated: the 'without decoding a packet' framing and the drops/snaplen/filter field list tell an agent this is the cheap file-level triage call, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. versus pcap_info or capture_quality). The agent must infer the routing decision.

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