Skip to main content
Glama

ICMP errors

icmp_errors
Read-onlyIdempotent

Extract and group every ICMP and ICMPv6 error in a capture by sender, kind, and quoted flow to identify unreachables, firewall rejects, fragmentation needs, or TTL loops.

Instructions

Every ICMP and ICMPv6 error in the capture: who sends unreachables, about which flows, is a firewall rejecting, is fragmentation needed somewhere, is TTL exceeded a traceroute or a routing loop? Rows group the errors per sender, kind and quoted flow (source, destination, protocol; the destination ports are listed): kind is net_unreachable, host_unreachable, protocol_unreachable, port_unreachable, frag_needed (with mtu), packet_too_big (ICMPv6, with mtu), admin_prohibited, ttl_exceeded, reassembly_timeout, source_quench, redirect, parameter_problem, no_route, address_unreachable or source_route_failed; with count, first/last frame, the quoted IP ID and quoted_flow_seen (the frame of the original packet when the capture holds it, IPv4 only). Also by_sender, echo (requests and replies) and issues. sender is an IP address; about an address or address:port of the quoted flow (either end); kind keeps one kind; filter is a display filter ANDed with the ICMP error and echo types. More detail: resource schema://tools/icmp_errors.

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

Input Schema

NameRequiredDescriptionDefault
endNoSame forms as start
kindNoKeep one kind: net_unreachable, host_unreachable, protocol_unreachable, port_unreachable, frag_needed, ...
pathYesCapture file (absolute, in an allowed dir) or open_capture handle
aboutNoIP address inside the quoted packet
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
senderNoIP address that sent the ICMP errors
columnsNoRow keys to keep (frame keys stay)
max_output_kbNoLower output cap, KB

Output Schema

NameRequiredDescriptionDefault
echoNo
countNo
errorNo
errorsNorows with keys: sender, kind, error, family, type, code, count, mtu, mtus, quoted, quoted_ip_id, quoted_flow_seen, first, last, first_frame, last_frame
issuesNo
offsetNo
windowNo
droppedNo
summaryNo
has_moreNo
returnedNo
by_senderNo
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

A4.5/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, closed-world and non-destructive, and the description adds substantially beyond that: results are grouped per sender/kind/quoted flow, `quoted_flow_seen` only appears when the capture holds the original packet and is IPv4-only. It also discloses the summary mode's size cap and the redaction behavior, which are real behavioral traits rather than restated hints.

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 purpose and diagnostic payoff, and the dense semicolon-separated kind list carries real information since the schema's `kind` description is truncated. It is a single run-on paragraph, though, and the by_sender/echo/issues mention is tacked on without structure, so it is dense rather than efficiently organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter tool with an output schema, the description covers grouping, filtering, kinds, quoting caveats and the resource link for deeper detail, which is enough to invoke correctly. The trailing `by_sender`, `echo` and `issues` sections are named but never explained, leaving some ambiguity about what those result sections contain.

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 the baseline is 3, but the description adds genuine meaning: `sender` is the ICMP sender IP, `about` matches either end of the quoted flow and may include a port, `kind` keeps a single kind, and `filter` is a display filter ANDed with the ICMP error and echo types. That clarifies matching semantics the schema descriptions only partially convey.

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 a specific resource and scope: 'Every ICMP and ICMPv6 error in the capture', then enumerates the exact questions it answers (who sends unreachables, is a firewall rejecting, is fragmentation needed, is TTL exceeded a traceroute or a routing loop). The row-grouping key (sender, kind, quoted flow) and the full kind list make it unmistakable which tool this is.

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?

Usage context is clear from the diagnostic questions the tool answers (unreachables, firewall rejects, MTU/fragmentation, TTL loops), which tells an agent when to reach for it. It does not name exclusions or point at an alternative sibling (e.g. filter_packets or expert_info) for narrower cases, so it stops short of full routing guidance.

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