Skip to main content
Glama

TLS handshakes

tls_handshakes
Read-onlyIdempotent

Analyze TLS handshakes per connection from packet captures without decryption to compare client offers and server choices, identify failures, alerts, timing, and certificate details.

Instructions

TLS handshakes per connection, read from the clear part of the handshake. No decryption and no key material. For TCP and QUIC: the client's offer (SNI, ALPN, TLS versions, number of cipher suites without GREASE, fallback SCSV) against the server's choice (version, cipher suite, ALPN when in clear), HelloRetryRequest, time from SYN to ClientHello and from ClientHello to ServerHello, alerts with level, name and who sent them (QUIC CONNECTION_CLOSE carrying a TLS alert too), and for TLS 1.2 and older the leaf certificate (subject, issuer, SAN, notBefore, notAfter, chain length). outcome is established, alert, no_server_hello, reset_by_server, closed_by_server, client_gave_up, client_rejected_likely (TLS 1.3: the client sent one encrypted alert-sized record instead of Finished, usually a certificate it would not accept), unreadable (the server answered but tshark could not read a ServerHello), incomplete, one_sided (only one direction captured: not a failure), or server_hello for QUIC (the rest is encrypted). server_name keeps that SNI and the names under it; filter is ANDed with the base filter. Problem connections come first. More detail: resource schema://tools/tls_handshakes.

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

Input Schema

NameRequiredDescriptionDefault
endNoSame forms as start
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)
server_nameNoTLS SNI (server name), or part of it
max_output_kbNoLower output cap, KB

Output Schema

NameRequiredDescriptionDefault
countNo
errorNo
issuesNo
offsetNo
windowNo
droppedNo
summaryNo
has_moreNo
returnedNo
connectionsNorows with keys: transport, stream, client, server, frame, time, sni, offered, client_hellos, client_hello_missing, hello_retry_request, chosen, tcp_to_hello_ms, server_hello_ms, alerts, certificate, outcome, note, closed, duplicate_copies, issues
next_offsetNo
total_foundNo
total_matchedNo
packets_matchedNo
packets_scannedNo
total_is_lower_boundNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantial behavior: no decryption or key material, per-protocol coverage (TCP and QUIC, including QUIC CONNECTION_CLOSE alerts), timing spans (SYN to ClientHello, ClientHello to ServerHello), certificate extraction limited to TLS 1.2 and older, and result ordering with problem connections first.

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, but the middle is a single run-on sentence that enumerates every outcome value inline, duplicating what an output schema already carries, and the trailing clauses about server_name and filter are awkwardly broken across a line. It is dense but not wasteful at the top; the bulk of the outcome glossary is the weakest use of space.

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 diagnostic tool with 11 parameters and an output schema, this covers what an agent needs: what is and is not decoded, which protocols and TLS versions yield certificates, how outcomes should be interpreted (including the non-failure one_sided and the TLS 1.3 client_rejected_likely case), and ordering of results. Nothing essential to calling or interpreting it is missing.

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 description coverage is 100%, so all 11 parameters are already documented, which sets the baseline at 3. The description adds only marginal param meaning — that server_name retains the SNI and names beneath it, and that filter is ANDed with the base filter (the latter already stated in the schema).

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 opening clause gives a concrete verb and resource ('TLS handshakes per connection') plus an explicit scope boundary ('read from the clear part of the handshake. No decryption and no key material'), and 'For TCP and QUIC' pins the protocols. It does not name or contrast any sibling tool (e.g. tcp_connections, tcp_health), so an agent must infer the boundary from scope alone.

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 only implied: the outcome enumeration and 'problem connections come first' signal that this is a diagnostic tool for failed or anomalous TLS setups, and 'one_sided ... not a failure' preempts a misread. There is no explicit when-to-use/when-not statement and no routing to an alternative for, say, non-TLS TCP behavior or full packet inspection.

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