Skip to main content
Glama

Sipflow

by dev.sipflow

RFC 3263 NAPTR/SRV/A walk + sips TLS cert diagnostic for a SIP target

dns_diagnose_sip_target
Read-only

[cost: external_io (DNS via Cloudflare + Google; TLS handshake + a SIP OPTIONS keepalive to public targets when applicable) | read-only | rate-limited per IP: 10/min, 200/day]

Walk DNS the same way a SIP UA does (RFC 3263 §4.1): NAPTR → SRV → A/AAAA. Given a SIP URI ("sip:example.com"), bare hostname ("example.com"), or "host:port" string, return the records that exist and the resolution ladder a UA would try.

When the queried target uses TLS (sips: URI, transport=tls/wss, or any _sips._tcp SRV record), the tool also performs a TLS handshake against each resolved sips target and reports the negotiated TLS version + cipher, the leaf certificate's subject / issuer / SANs / validity, the chain length and whether it validates against Node's default trust store, plus two cert-domain checks: RFC 5922 §7.2 strict (cert must cover the original SIP domain) and a lenient SAN match against the SRV target hostname.

SIP liveness: DNS resolving and a TLS handshake succeeding do NOT prove the endpoint actually speaks SIP - a load-balanced node can accept TCP/TLS yet black-hole SIP. So the tool ALSO sends a real SIP OPTIONS keepalive to each resolved public IP across the relevant transports (UDP/TCP on 5060, TLS on 5061 / SRV port) and reports per-IP answered / timeout / refused. Any SIP response (even 405/403/404) proves the stack is alive on that IP. When a name resolves to multiple IPs it is treated as a load-balancer fan-out and each IP is probed individually, with a warning about the known failure modes of fronting stateful SIP/RTP with a cloud L4 LB (AWS NLB/ALB etc.): cross-zone-off targets that black-hole, the ~120s UDP idle timeout, and per-5-tuple hashing splitting signaling from media.

Egress safety:

  • Per-IP rate limited.

  • Hostnames that resolve only to RFC 1918 / loopback / link-local / documentation / multicast space are refused (SSRF guard).

  • Walk depth capped to prevent runaway NAPTR / CNAME chains.

  • TLS probes capped at 6 (host, port, ip) tuples per call, 5 s handshake timeout each, public-IP only (we connect to the resolved IP, not the hostname, so the system resolver cannot redirect us into private space).

  • SIP OPTIONS probes capped at 6 (ip, transport) tuples per call, 3 s timeout each, public-IP only; the request carries no SDP/body and an unroutable Via, and only the response status line is captured.

Use to diagnose:

  • "carrier doesn't answer" / "wrong port" / "TLS instead of UDP" routing puzzles

  • "DNS looks healthy but calls fail" - per-IP SIP OPTIONS surfaces nodes that resolve and accept the transport but never answer SIP (the decisive step for load-balanced / multi-IP targets)

  • "carrier rejects our target because no SRV is published" - when A/AAAA resolves but SRV is missing the tool synthesises a copy-pasteable suggested zone-record block pointing at the resolved canonical hostname

  • "TLS handshake works but cert isn't valid for the SIP domain" - RFC 5922 §7.2 compliance is checked separately from generic chain validation, since the SAN must cover the original SIP domain (not the SRV-redirected target)

ACL caveat: a SIP OPTIONS timeout can also mean the target authorizes inbound SIP by source IP whitelist on the trunk (Twilio, Telnyx, Bandwidth, …; see https://www.twilio.com/docs/sip-trunking/api/ipaccesscontrollist-resource) and is dropping our probe because our egress IP is not on the ACL. An answered result is conclusive (the node speaks SIP); a timeout is suggestive, not proof of a dead node - confirm reachability from the SBC itself.

Pair with: troubleshoot_response_code when 503 / 408 / 480 are involved; search_sip_docs(vendor=...) for carrier-specific routing docs.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
targetYesSIP URI ("sip:example.com"), "example.com:5060", or bare hostname ("example.com"). Userinfo is stripped before lookup.
transportNoTransport hint. "any" surfaces all NAPTR services; specific transports filter the SRV walk to that service.any

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses specific external behaviors: DNS queries to Cloudflare/Google, TLS handshakes, and SIP OPTIONS keepalives. It details rate limits (10/min, 200/day), SSRF protections, timeout caps (3s/5s), probe caps (6 tuples), and failure modes (load-balanced black-holing, UDP idle timeouts, per-5-tuple hashing). This far exceeds annotation-only transparency.

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 description is long but well-structured with clear sections (cost, walk, TLS, SIP liveness, egress safety, use cases, ACL caveat, pairing). Every sentence serves a purpose given the tool's complexity; the front-loaded 'cost' and 'walk' lines immediately convey scope. While not brief, it is contextually concise—no filler or redundancy.

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?

With no output schema, the description fully informs what the tool returns: DNS records, resolution ladder, TLS certificate details, per-IP SIP OPTIONS outcomes, and even a suggested zone-record block. It also anticipates common diagnostic questions and explains how to interpret inconclusive results (e.g., ACL timeouts vs. dead nodes). The description is self-sufficient for an agent to select and invoke correctly.

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?

The input schema already has full coverage (target and transport with detailed descriptions). The tool description adds extra meaning by explaining that 'any' surfaces all NAPTR services while specific transports filter the SRV walk, and by tying transport to TLS triggering conditions (sips:, transport=tls/wss, _sips._tcp SRV). This adds value beyond the enum/default descriptions.

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?

The description clearly states the tool's function: a DNS resolution walk following RFC 3263 (NAPTR → SRV → A/AAAA), plus TLS certificate diagnostic and SIP OPTIONS liveness probes for a SIP target. It distinguishes itself from siblings by focusing on SIP DNS/lifecycle diagnostics, and explicitly names companion tools like troubleshoot_response_code and search_sip_docs.

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?

The description provides an explicit 'Use to diagnose' section listing concrete scenarios (e.g., 'carrier doesn't answer', 'DNS looks healthy but calls fail') and even includes a 'Pair with' recommendation naming sibling tools and when to use them. It also clarifies a key caveat (ACL-based timeouts) that prevents misinterpreting results.

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

All Sipflow toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0
Disambiguation4/5

Most tools have clearly distinct purposes. The only notable overlap is between detect_sip_stack and detect_sip_vendor_from_config, which could cause confusion. Otherwise, each tool covers a unique aspect of SIP debugging.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., compare_sdp_offer_answer, detect_sip_stack, validate_stir_shaken_identity). No mixing of styles.

Tool Count4/5

22 tools is slightly above the typical 3-15 range, but each tool serves a specific and necessary function for comprehensive SIP debugging. The count is justified by the server's broad scope.

Completeness4/5

The tool set covers a wide range of SIP debugging tasks: parsing, diffing, DNS, STIR validation, config review, codec comparison, etc. Minor gaps exist (e.g., no dedicated RTP analysis tool), but core workflows are well-supported.

Resources