Skip to main content
Glama

SIP dialogs

sip_dialogs
Read-onlyIdempotent

Groups SIP messages by Call-ID to list calls and dialogs, showing method sequences, final outcomes, timings, and duration so you can locate a call and inspect how it ended.

Instructions

Group SIP messages by Call-ID: the list of calls and other dialogs and how each ended. Use it to find a call; then sip_call_detail for one call's timings and SDP, ims_registration for REGISTER flows, sms_over_ims for SIP MESSAGE delivery. Each dialog lists the method/response sequence with timestamps, From, To, Request-URI, P-Asserted-Identity, the method chain, the final status of the initial request, time to that final response and the dialog duration; outcome_status is the final status after any 401/407 challenge was retried (a REGISTER answered 401 then 200 succeeded), attempts counts transactions of the initial method and resent_messages counts retransmissions; no_final_response: true marks requests that never completed. Narrow with call_id (exact), number (digits found in From, To, Request-URI or P-Asserted-Identity) or method (INVITE, REGISTER, MESSAGE, ...): matching messages select the dialogs, then every message of those dialogs is fetched so responses are kept. filter is a raw display filter ANDed with sip; it applies literally to each packet.

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

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
methodNoSIP method (INVITE, REGISTER, ...)
numberNoPhone number digits found in From, To, Request-URI or P-Asserted-Identity
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
call_idNoSIP Call-ID of the call
columnsNoRow keys to keep (frame keys stay)
esp_nullNoRead SIP in NULL-encrypted ESP
max_output_kbNoLower output cap, KB

Output Schema

NameRequiredDescriptionDefault
countNo
errorNo
ipsecNokeys: esp_packets, spis, decoded_null, unreadable, esp_null, hint
offsetNo
windowNo
dialogsNorows with keys: call_id, time, duration_ms, src, dst, initial_method, request_uri, from, to, p_asserted_identity, final_status, time_to_final_ms, outcome_status, attempts, resent_messages, no_final_response, message_count, methods, messages
droppedNo
summaryNokeys: by_message, unanswered, failed, legs_without_response, legs_near_capture_end, unanswered_near_capture_end, duplicates
has_moreNo
returnedNo
selectionNo
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

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavior: how `outcome_status` resolves a 401/407 retry to a final status, what `attempts` and `resent_messages` count, and that `no_final_response: true` flags unfinished requests. It also discloses the non-obvious selection behavior that matching messages pull in every message of that dialog so responses are retained.

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 purpose and alternatives before descending into result-field detail, and the dense semicolon-separated clauses carry real information rather than filler. It is longer than most agents need in one read, and the mid-paragraph field glossary could be tightened, but little is expendable.

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 14-parameter tool with an output schema and full annotations, the definition covers selection scope, filtering semantics, result-field meaning and pagination context. Output schema exists, yet describing `outcome_status`/`attempts` semantics adds interpretation the schema alone would not give.

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 defining matching semantics beyond the schema text — `number` matches digits in From/To/Request-URI/P-Asserted-Identity, `call_id` is exact, and `filter` is a raw display filter ANDed with `sip` applied literally per packet, plus the dialog-expansion rule. It does not re-explain pagination/output/redact parameters, which the schema already covers.

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 verb and resource: 'Group SIP messages by Call-ID: the list of calls and other dialogs and how each ended.' It immediately distinguishes itself from sip_call_detail, ims_registration and sms_over_ims by naming each and its scope.

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?

Explicit routing: 'Use it to find a call; then sip_call_detail for one call's timings and SDP, ims_registration for REGISTER flows, sms_over_ims for SIP MESSAGE delivery.' The agent knows when to pick this tool and which sibling to pick otherwise, with no inference required.

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