Skip to main content
Glama

TCP connections (refused, filtered, who closed)

tcp_connections
Read-onlyIdempotent

List TCP connection attempts from a packet capture and classify each outcome—connected, refused, filtered, prohibited, or unreachable—to show whether a host and port are reachable.

Instructions

Can this host reach that port, and if not, is it refused, filtered or prohibited? One row per TCP connection attempt (a SYN with a new initial sequence number is a new attempt, the same one a retry; mirrored copies are dropped first) with outcome: connected, refused (the server side answered the SYN with a reset: nothing listens, or a firewall rejects with a reset), filtered (no answer at all: a firewall drops it or the host is down; near_capture_end when the capture stopped less than 3 s after the last SYN), prohibited (ICMP administratively prohibited quoting the SYN), unreachable (another ICMP unreachable or TTL exceeded), reset_during_handshake, handshake_incomplete (SYN-ACK never acknowledged), one_sided (only one direction captured; not a failure) or seen_midway. Failed attempts come first; view="destinations" groups them per server address and port with issues. server, client (IP addresses) and port (the server port) narrow the attempts; outcome keeps one outcome; filter is a display filter ANDed with tcp || icmp errors. For loss, windows and MTU inside a connection use tcp_health. More detail: resource schema://tools/tcp_connections.

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

Input Schema

NameRequiredDescriptionDefault
endNoSame forms as start
pathYesCapture file (absolute, in an allowed dir) or open_capture handle
portNoServer TCP port
viewNoconnections (one row per attempt) or destinations (per server and port)connections
limitNoMost rows per page
startNoISO 8601, epoch s, +Ns from start, -Ns from end
clientNoClient IP address
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
serverNoServer IP address
columnsNoRow keys to keep (frame keys stay)
outcomeNoKeep one outcome: connected, refused, filtered, prohibited, unreachable, reset_during_handshake, ...
max_output_kbNoLower output cap, KB

Output Schema

NameRequiredDescriptionDefault
viewNo
countNo
errorNo
offsetNo
windowNo
droppedNo
has_moreNo
returnedNo
connectionsNorows with keys: stream, client, server, outcome, missing_direction, near_capture_end, syns, syn_retries, syn_retry_gaps_s, connect_ms, bytes_client_to_server, bytes_server_to_client, packets, duration_s, closed_by, completeness, icmp, reset_frame, first, first_frame, last_frame, copies_dropped
next_offsetNo
total_foundNo
destinationsNorows with keys: server, connections, attempts, connected, refused, filtered, prohibited, unreachable, reset_during_handshake, handshake_incomplete, one_sided, seen_midway, failed_then_connected_elsewhere, success_rate, syn_retries, connect_ms_p50, connect_ms_max, duration_s_p50, clients, max_concurrent, first_frame, issues
total_matchedNo
packets_matchedNo
packets_scannedNo
total_is_lower_boundNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/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 beyond-annotation behavior: attempt deduplication semantics (new ISN = new attempt, same ISN = retry, mirrored copies dropped first), result ordering (failed attempts first), and the `near_capture_end` caveat tied to a 3 s window. It stops short of describing cost, page sizing behavior, or what the summary view drops beyond the schema's own note.

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 user-facing question, then the outcome taxonomy, then filtering parameters, then the sibling hand-off — a sensible order with no filler. It is dense and the long parenthetical outcome glossary makes it a heavy read, but each clause carries real classification information.

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 15-parameter tool with an output schema, the description covers the discriminating semantics (outcome meanings, view modes, filter scoping, dedup) and defers the rest to the schema plus the `schema://tools/tcp_connections` resource. Nothing an agent needs before calling it on a capture is missing.

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 baseline is 3; the description earns above that by explaining semantics the schema cannot: `filter` is ANDed with `tcp || icmp errors` (crucial, since it silently restricts scope), `server`/`client`/`port` 'narrow the attempts', and `outcome` keeps exactly one outcome. It leaves `redact`, `columns`, `max_output_kb` and pagination to the schema, which is appropriate.

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?

Opens with the exact question the tool answers ('Can this host reach that port, and if not, is it refused, filtered or prohibited?') and states the unit of output: one row per TCP connection attempt. It then enumerates the concrete `outcome` vocabulary and the alternate `view="destinations"` mode, which distinguishes it clearly from tcp_health and packet_detail.

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?

Explicitly routes the agent away from this tool for in-connection analysis: 'For loss, windows and MTU inside a connection use tcp_health.' It also specifies when to pick the destinations view ('groups them per server address and port with issues') and notes that `one_sided` is 'not a failure', preventing a common misread.

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