Skip to main content
Glama

DNS transactions

dns_transactions
Read-onlyIdempotent

Analyze DNS exchanges by pairing queries with responses to reveal unanswered queries, retransmissions, and server latency in packet captures.

Instructions

DNS queries paired with their responses (by transport, client and server address and port, DNS id and question name), including the queries that never got one, which tshark's own dns.time cannot show. Each transaction gives name, type (A, AAAA, NAPTR, SRV, HTTPS, ...), client, server, rcode and its name (NOERROR, NXDOMAIN, SERVFAIL, REFUSED, ...), answers and addresses, round-trip ms, unanswered (with near_capture_end and a note when the capture on its interface stops before the answer was due: the resolver's slowest answer plus 0.2 s, at most 2 s; counted in summary.unanswered_near_capture_end), retransmissions (the same query resent with the same id and port), retry_of (a new query for a name whose last query was unanswered or failed), truncated_tc and tcp_fallback_frame (a TC answer followed by the same query over TCP). servers gives per resolver queries, answered, unanswered share, rcodes and latency min/p50/p90/p99/max; names lists the names that failed, were retried or were slow (over 1 s); issues says it in plain words. Copies of one packet (a capture on several interfaces or GTP legs) are counted once. DNS inside GTP-U tunnels is read from the inner packet. name keeps that name and the names under it (case-insensitive); filter is ANDed with dns. Transactions with a problem come first, then the rest in capture order.

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

Input Schema

NameRequiredDescriptionDefault
endNoSame forms as start
nameNoQuery name, or the end of it
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
columnsNoRow keys to keep (frame keys stay)
max_output_kbNoLower output cap, KB

Output Schema

NameRequiredDescriptionDefault
countNo
errorNo
namesNorows with keys: name, queries, unanswered, failed, rcodes, retries, slow, types, servers
issuesNo
offsetNo
windowNo
droppedNo
serversNorows with keys: server, queries, answered, unanswered, unanswered_share, rcodes, retransmissions, transports, clients, icmp_errors, rtt_ms
summaryNo
has_moreNo
returnedNo
next_offsetNo
total_foundNo
transactionsNorows with keys: frame, time, client, server, transport, id, name, type, response_frame, rcode, rcode_name, answers, addresses, cnames, rtt_ms, unanswered, near_capture_end, note, retransmissions, retry_of, truncated_tc, tcp_fallback_frame, fallback_from_udp, duplicate_responses
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.1/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 still adds substantial behavior: duplicate packet copies across interfaces or GTP legs are counted once, DNS inside GTP-U is read from the inner packet, results are ordered problem-first then capture order, and case-insensitive sub-name matching. It also defines the non-obvious `unanswered` heuristic precisely (resolver's slowest answer plus 0.2 s, capped at 2 s) and where it is aggregated. This is real disclosure an agent could not infer from the annotations.

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?

The purpose is front-loaded in the first sentence and the rest is substantive rather than filler. However, it is one dense paragraph with deeply nested parentheticals (the near-capture-end timing rule in particular) that make it hard to scan, and the output-structure sentences partly restate what the output schema already provides.

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 an 11-parameter tool over a rich output, the definition covers the non-obvious semantics an agent needs: dedup rules, tunnel parsing, ordering, the unanswered boundary heuristic, and name matching. Return values are already covered by the output schema, so the remaining explanatory text is supplementary rather than a gap.

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; the description earns above that by adding semantics the schema lacks, notably that `name` matches the given name plus everything under it case-insensitively, and that `filter` is ANDed with an implicit `dns` filter. It does not deepen `redact`, `columns` or `output`, but those are adequately enum-documented.

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?

The description opens with a precise statement of the resource and what is joined: DNS queries paired with their responses, keyed by transport, addresses, ports, DNS id and question name. The added clause about including unanswered queries that 'tshark's own dns.time cannot show' sharpens the scope further. It never names or contrasts a sibling tool, so it stops short of the 5 bar.

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 emphasis on unanswered queries, retries, `truncated_tc`, `issues` and slow names signals a DNS troubleshooting use case. There is no explicit 'use this when' clause, no statement of when another tool (e.g. filter_packets or packet_detail) is the better choice, and no prerequisites beyond the path description in the schema.

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