Skip to main content
Glama

TCP stream health

tcp_health
Read-onlyIdempotent

Analyze per-stream TCP health from a capture: handshake, retransmissions by loss location, reordering, zero windows, resets, and MTU or PMTUD black-hole problems, with duplicate mirrored packets removed.

Instructions

Health of every TCP stream, with copies of the same packet (mirror, SPAN, several interfaces) removed first, so they are not counted as retransmissions the way tshark's own analysis counts them. Per stream: the handshake (SYN retries, SYN to SYN-ACK and SYN-ACK to ACK times as seen from the capture point, MSS, window scale, SACK); per direction the data segments and retransmissions split by where the loss happened (lost_before_capture: a gap later filled by a retransmission; retransmitted_after_capture: the capture saw the original; missed_by_capture: acknowledged by the receiver but absent from the file, so not network loss), reordering, duplicate ACKs, zero windows, keep-alives; resets with likely_from endpoint or middlebox, judged by the reset's TTL and source MAC against that side's other packets, and the idle time before it; ICMP fragmentation-needed / packet-too-big about the stream (a mirrored copy of an ICMP error counts once, summary.icmp_copies_dropped); and MTU problems against mtu (an MSS too large for the path, DF packets above it, full-size segments retransmitted and never acknowledged while small ones pass: a PMTUD black hole). issues says it in plain words; streams with issues come first. stream is tshark's tcp.stream index; filter is a display filter ANDed with tcp.

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": "tcp_health"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoSame forms as start
mtuNoPath MTU in bytes for the MTU checks
pathYesCapture file (absolute, in an allowed dir) or open_capture handle
limitNoMost rows per page
startNoISO 8601, epoch s, +Ns from start, -Ns from end
filterNoExtra display filter, ANDed
offsetNoRows to skip (next_offset)
outputNosummary: all but rows, plus 3 rows (<8 KB)rows
redactNoReplace subscriber identifiers in this result with tokens; ids+ips hides every IP toooff
streamNotcp.stream index of one connection
columnsNoRow keys to keep (frame keys stay)
max_output_kbNoLower output cap, KB

Output Schema

NameRequiredDescriptionDefault
countNo
errorNo
offsetNo
windowNo
droppedNo
streamsNorows with keys: stream, client, server, first, last, duration_s, packets, copies_dropped, handshake, client_to_server, server_to_client, resets, icmp, df_above_mtu, df_above_mtu_acknowledged, loss, issues
summaryNo
has_moreNo
path_mtuNo
returnedNo
next_offsetNo
total_foundNo
total_matchedNo
display_filterNo
packets_matchedNo
packets_scannedNo
total_is_lower_boundNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/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 the description adds substantial behavior beyond them: capture-point deduplication, how loss categories (lost_before_capture, retransmitted_after_capture, missed_by_capture) are assigned, how reset origin is judged via TTL and source MAC, PMTUD-black-hole detection logic, and that streams with issues are ordered first. It stops short of stating cost, performance limits, or pagination behavior, which keeps it 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 core claim is front-loaded in the first clause, and most clauses carry information about returned fields. However, the body is one long run-on paragraph dense with parentheticals and semicolon chains, making it harder to scan than a segmented structure would be.

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 12-parameter analytical tool with a full output schema and safety annotations, the description covers methodology, field meanings, ordering, and filter interaction — everything an agent needs to decide to call it and to interpret the results without guessing.

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 already 100%, so the baseline is 3; the description adds real meaning on top by explaining that `filter` is ANDed with `tcp`, that `mtu` is the path MTU used for the MTU checks, and that `stream` is tshark's tcp.stream index. It says nothing about `redact`, `columns`, `max_output_kb`, or `output: summary`, but those are well covered by the schema itself.

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?

Opens with a specific verb-and-resource statement ("Health of every TCP stream") and then enumerates exactly what per-stream and per-direction health signals are produced, so an agent knows it is a diagnostic per-stream tool, not a raw listing. It distinguishes itself from tshark's own retransmission analysis but never contrasts itself with a sibling such as tcp_connections, leaving that boundary to be inferred.

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?

There is no explicit when-to-use/when-not section and no named alternative. Usage is only implied, chiefly by the statement that duplicate packets are removed so mirrored/SPAN captures are not miscounted the way tshark counts them — which hints this tool is the right choice for multi-interface captures, but that inference is left to the agent.

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