Sipflow

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

The description starts with '[cost: free (pure CPU, no network) | read-only]', adding non-obvious details beyond the readOnlyHint annotation, such as no network calls and CPU-only operation. It also discloses the exact checks it performs (DTLS setup-role conflicts, ICE asymmetry, fax reinvite mismatches), making its analysis behavior transparent. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: it opens with the core diff function, lists concrete issue categories, then gives usage scenarios and complementary tools. While somewhat long, every sentence serves a purpose—no filler. The cost/read-only prefix is slightly redundant with annotations but adds specific context (pure CPU, no network).

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

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

Without an output schema, the description compensates by enumerating issue categories and linking them to failure symptoms (488, no-audio, T.38 reinvite failures), giving a clear expectation of diagnostic output. It doesn't specify the return format, but the scope of analysis is well defined for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions 'SDP offer body.' and 'SDP answer body.' Baseline is 3. The description adds no additional parameter-level syntax or constraints beyond the schema, but it contextualizes the offer/answer pair within RFC 3264 negotiation, which is marginal extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb+resource: 'Diff a SIP/SDP offer and answer'. It then lists specific analysis dimensions (codec intersection, direction compatibility, DTLS roles, etc.), which distinguishes it from siblings like parse_sdp. The 'Pair with' note explicitly names parse_sdp as an alternative for inspecting each side in isolation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage scenarios: 'Use when the user has both halves of a negotiation and is debugging 488 Not Acceptable Here, no-audio, one-way-audio, or a failed T.38 reinvite...' It also conditions on having both halves, and names complementary tools for single-side inspection and vendor-specific fixes, effectively differentiating when to use this tool.

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

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

The description goes beyond the readOnlyHint annotation by specifying 'cost: free (pure CPU, no network)' and explaining detection methods (structural signatures for configs, headers for traces). It also explains the 'auto' mode's fallback behavior. However, it doesn't disclose potential error cases or limitations, but the annotation already signals safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and appropriately sized. It opens with the cost/read-only note, clearly states the purpose, lists supported input types in a compact list, and then offers concise pairing suggestions. Every sentence adds value without redundancy.

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

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

Given there is no output schema, the description adequately explains the return value (vendor slug) and provides examples of slugs. It also contextualizes the output by noting its alignment with the 'vendor' filter. It slightly lacks discussion of when the tool might fail or return unknown, but for a detection tool this is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters have descriptions in the schema (100% coverage), so the baseline is 3. The description adds some context about input types (trace/config) and examples, but doesn't significantly enhance parameter understanding beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's action ('Identify the SIP product behind a piece of input') and its scope (trace or config). It distinguishes itself from the sibling 'detect_sip_vendor_from_config' by covering both trace and config, and differentiates from 'review_sip_config' by focusing on vendor detection rather than modules/risk flags.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool (for traces or configs), and pairs it with alternatives: 'search_sip_docs(vendor=<slug>)' for doc search, 'review_sip_config' when config details are needed, and 'troubleshoot_response_code(vendorHint=<slug>)' for status codes. This gives clear guidance on choosing this tool over siblings.

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

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

Beyond the readOnlyHint annotation, the description adds valuable context: 'cost: free (pure CPU, no network)' and 'read-only'. It also discloses the heuristic nature, expected return fields, and limitations ('detect-only', does not extract directives or flag risks). This goes well beyond structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with cost/read-only context. Each sentence adds substantive value: purpose, output, usage, and tool pairings. No redundancy or filler.

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

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

Given the tool's moderate complexity, the description is complete enough. It covers what the tool does, what it returns, when to use it, and how it relates to sibling tools. Even without an output schema, the return fields are specified. The cost/network behavior adds essential context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% description coverage for both parameters, so the baseline is 3. The description implicitly refers to the config blob input ('attaches a SIP config file') and mentions structural signals like 'loadmodule syntax, route blocks, profile elements', but does not significantly enhance parameter semantics beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: detect a SIP vendor from a config file, returning the vendor slug, confidence level, and structural signals. It explicitly distinguishes itself from the sibling `detect_sip_stack` by being a 'heuristic-only sibling scoped to vendor configs', and clarifies it does not extract directives or flag risks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use this when the user asks "what is this config?" or attaches a SIP config file.' It also explains pairing with `review_sip_config` and `search_sip_docs`, and explicitly states what the tool does NOT do, setting clear boundaries vs alternatives.

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

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

Annotations already declare readOnlyHint, but description adds 'cost: free (pure CPU, no network) | read-only, no persistence' and details internal behavior like delegating SDP to compareSdp. This is genuinely useful context beyond annotations, with no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Although longer than minimal, every sentence earns its place: it opens with cost/read-only tag, then a concise functional summary, followed by explicit usage guidance and sibling pairings. The structure is front-loaded and scannable with no filler.

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

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

The tool is complex (diff categories, SDP delegation, hop semantics), but the description covers all essential behavioral aspects without an output schema. It explains the diff output categories, edge cases like parameter reordering, and the delegation to compareSdp, making it self-sufficient for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter already has a clear description (e.g., 'before' and 'after' with hop directions). The description reinforces this with examples but does not add significant new parameter-specific meaning beyond the schema's coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Take two SIP messages ... and surface a structured per-header diff' with specific categories (added, removed, mutated, etc.). It distinguishes from siblings by naming exact alternatives and when to use them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('when the user has two captures or two log lines that should be carrying the same message'), and provides direct alternatives and pairings: 'parse_sip_message to inspect either side in isolation; lint_sip_request if the diff reveals the downstream side became malformed; search_sip_docs(vendor=<intermediate>)'.

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

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.

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.

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.

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.

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.

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.

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

The description goes far beyond the readOnlyHint/openWorldHint annotations by detailing cost, rate limits, no persistence, privacy projection (stripped fields, pseudonymization), trace size cap with truncation flag, and that raw PCAP is not returned to agents. It also explains the dual behavior of using persisted diagnostics vs. parsing on the fly. This fully discloses behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded with a concise cost/read-only/rate-limit banner, then moves from core behavior to details and pairings. Every section serves a purpose for a complex tool; however, the length is substantial and some details (e.g., media-quality explanation) could be trimmed without losing essential guidance. Still well-organized.

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

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

For a tool with no output schema, the description thoroughly inventories what the agent can expect: trace text, AI analysis, metadata, rule-based diagnostics, media quality stats, truncation, raw-capture exclusion, and privacy projection. It also gives practical next-step tool pairings, making the response complete enough for an agent to decide and act correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides a detailed description for the url parameter (full URL, path must be /share/<token>, not /api/share). The tool description adds useful semantic context about accepted URL forms ('any sipflow.dev subdomain') and what the tool does with the URL, but the parameter itself is already well-covered by the schema. Baseline is 3, and the added subdomain detail and context raise it to 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('load', 'fetch', 'hydrate') and clearly identifies the resource: a Sipflow share URL. It distinguishes the tool from siblings by stating its unique role: fetching shared SIP traces plus AI analysis in one round trip, and explicitly names sibling tools for different purposes (e.g., render_sip_ladder, review_sip_config).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'Use this whenever a user pastes a /share/<token> URL.' It also frames alternatives and complementary tools ('Pair with: review_sip_config... minimize_sip_trace... troubleshoot_response_code'), clarifying the tool's role relative to siblings. It does not need an explicit when-not because the positive trigger is unambiguous.

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

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

Annotations already declare readOnlyHint=true, and the description adds cost-free, no-network, no-persistence details, plus a list of specific failure modes it catches. It does not describe the output format in detail, but that is minor since it returns 'findings'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose, bulleted failure modes, and usage guidance. It is longer than minimal, but every section carries useful information; there is slight redundancy in the opening but not excessive.

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

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

For a tool of this complexity, the description covers input format, typical use cases, and related tools, making it self-sufficient for selection and invocation. The absence of an output schema is offset by the clear statement that it returns a list of findings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a well-described 'text' parameter, so the description doesn't need to add parameter details. It adds minimal context (typical INVITE use, header separator expectations already in schema) but doesn't go beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: running RFC compliance checks on a single raw SIP request and returning a list of findings. It uses a specific verb (lint) and resource (SIP request), and distinguishes itself from siblings by naming them with complementary roles.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use first (chasing 422/400/484 on a single INVITE) and provides pairing alternatives for different needs (parse_sip_message, validate_stir_shaken_identity, search_sip_docs). This is a clear usage guide with both positive and negative cases.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds context beyond these: cost (free, pure CPU), no network, sub-millisecond performance, static nature, and the type of data returned (name, RFC anchor, category, etc.). It does not contradict annotations, and the added speed/cost details are valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: a cost/read-only tag, a single-sentence purpose, a clear 'USE FIRST' directive, and a compact paired-tools list. Every sentence serves a distinct purpose without verbose padding.

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

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

For a simple, single-parameter, read-only lookup with no output schema, the description is complete. It explains what the tool returns, when to use it, and how it relates to other tools. No additional behavioral or return-value detail is necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully documents 'code' with type, range (100-699), and an example. The description adds marginal value by mentioning that the code maps to name/RFC category and gives a vendor-specific example (OpenSIPS 484), but these do not significantly extend the parameter's meaning beyond the schema's coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Instant static lookup of a SIP response code (100-699).' It clearly states the tool's scope and differentiates from siblings like troubleshoot_response_code (RAG hits) and lookup_sip_header (header lookup).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: 'USE FIRST when the user pastes or asks about any 3-digit SIP code.' It also lists paired tools with specific conditions (e.g., lint_sip_request for 4xx with offending request, validate_stir_shaken_identity for 438 with JWS), which fully covers when to use this tool vs alternatives.

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

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

Annotations already mark the tool as read-only, and the description adds cost and network behavior ('pure CPU, no network') and performance ('sub-millisecond'). It does not cover error handling or result formatting, but the added context is useful beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a cost banner, core functionality, usage guidance, and pairing suggestions. Every sentence serves a purpose, and the length is appropriate given the lack of an output schema.

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

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

With only one parameter and no output schema, the description fully enumerates the return fields, gives use-case examples, and points to complementary tools. It is comprehensive for the tool's complexity and leaves no critical gap for an agent deciding whether to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the name parameter thoroughly, including case-insensitivity and examples. The description reinforces this with additional examples of canonical and compact forms, adding practical context without redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Instant lookup of a SIP header' and provides concrete examples, making the action and resource unmistakable. It distinguishes itself from sibling tools like lint_sip_request or search_sip_docs by focusing on the definitional lookup use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states 'USE FIRST when the user asks about a specific header they saw in a trace' and names specific alternative tools ('lint_sip_request', 'search_sip_docs') for checking or vendor-specific headers. This gives clear when-to-use and when-to-defer guidance.

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

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

Annotations declare readOnlyHint, and description adds 'no persistence', 'not sent off-server', 'in-memory', and 'safe on production traces'. Also discloses exactly what is preserved/pruned, going beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with cost/read-only tag and single-sentence summary, but the input format paragraph is fairly long. All content earns its place given the tool's input complexity.

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

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

For a no-output-schema tool, the description fully covers input requirements, transformation behavior, safety, and integration with sibling tools. No missing critical context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers both parameters at 100%, and description adds input format details not in schema, such as accepted PCAP/syslog/sngrep formats and tolerated annotation lines. For maxBytes it reiterates truncation purpose but adds pipeline context; minor extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it reduces a raw SIP trace to compact form for LLM, preserving SDP and pruning noise. This distinguishes it from siblings like render_sip_ladder and parse_sip_message. The listed pairing also clarifies its niche.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Expected input format' enumerates accepted sources and tolerates annotation lines. Explicitly states when safe and pairs with detect_sip_stack, render_sip_ladder, lint/parse for analysis flow, giving both when-to-use and alternatives.

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

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

Annotations already state readOnlyHint=true; the description adds value by disclosing cost ('pure CPU, no network'), reinforcing read-only behavior, and detailing the exact scope of parsing (including T.38 fax attributes). It does not cover error handling or edge cases, but for a read-only parser with annotations covering safety, this is solid context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a cost/read-only line, a concise first sentence, a 'Useful for' paragraph, and a 'Pair with' list. Every sentence earns its place, front-loading the purpose before usage context. No fluff or redundancy.

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

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

For a single-parameter tool with no output schema, the description thoroughly enumerates return fields, includes practical use cases, and names sibling tools for further analysis. It even covers niche fax (T.38) negotiation details, making it complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for the single 'sdp' parameter, already explaining it is the body after the empty line. The tool description does not add param-specific details beyond that, so the baseline 3 applies since the schema carries the semantic weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Parse') and resource ('Session Description Protocol body') and enumerates the structured output fields (origin, session, timing, codecs, DTLS, ICE, fax-relay, crypto). It clearly distinguishes itself from siblings like compare_sdp_offer_answer and parse_sip_message by focusing on SDP payload parsing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use it: 'debugging WebRTC ↔ SIP interop' and 'inspecting fax negotiation' without re-deriving SDP grammar. It names sibling tools for related scenarios: compare_sdp_offer_answer for both halves, webrtc_sip_checklist for bridge-config. This provides clear when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'read-only, no persistence' and adds cost-free/pure CPU/no-network details. It also discloses the structural flags the parser detects, which is valuable behavioral context beyond the annotations. No contradiction found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a cost/read-only prefix, a detailed output summary, explicit usage guidance, and a pairing section. Every sentence is purposeful, and there is no wasted or redundant wording despite the length.

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

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

Although there is no output schema, the description enumerates the exact return elements: start line, headers in order with line numbers, body, duplicate-header counts, and a list of structural flags. It also names sibling tools and gives clear scope boundaries, making it fully complete for an agent to decide to invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'text' has 100% schema description coverage, including max length and delimiter expectations. The tool description adds the context of 'single raw SIP message' but does not introduce new parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Parse a single raw SIP message (request OR response) and return a structured view', followed by detailed output components. It additionally distinguishes itself from siblings by naming lint_sip_request, diff_sip_messages, and validate_stir_shaken_identity as complementary tools with different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool ('Use FIRST when the user pastes a single INVITE / 200 / NOTIFY...') and gives concrete alternative tools for related tasks. This makes the selection decision unambiguous.

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

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

Annotations already declare readOnlyHint=true; the description reinforces this with '[cost: free (pure CPU, no network) | read-only]'. Beyond annotations, it discloses rich behavioral details: lane keying by IP (not ip:port), merging ephemeral ports, port suffix notation, alias matching precedence order, fallback to peer address rather than 'unknown:5060', truncation notes, hidden-count summarizing in compact mode, and failover separators. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence serves a purpose: cost/read-only, core function, rendering compatibility, lane keying rules, alias matching, and sibling-tool usage. It is logically structured with clear sections and front-loads the primary action. Despite its length, there is no filler.

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

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

Given the tool's complexity (11 params, no output schema), the description covers output format ('Mermaid sequenceDiagram block'), input parsing sources, edge-case behaviors (multi-port, aliases, truncation), and when to use related tools. It provides a thorough operational picture without needing an output schema to clarify results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. Parameters already have detailed descriptions in the schema (e.g., groupByIp, compact, aliases). The main description adds some high-level context such as the alias matching order and groupByIp rationale, but largely repeats what the schema already captures. It does not significantly elevate parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Parse a raw SIP trace... and emit a Mermaid sequenceDiagram block visualizing the call flow.' It uses a specific verb ('Parse') and resource ('SIP trace' → 'Mermaid ladder'). It distinguishes itself from siblings through the 'Pair with' section naming related tools and their different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Pair with' paragraph gives explicit guidance on when to use alternative tools: 'minimize_sip_trace first to compact a noisy trace; diff_sip_messages when two adjacent INVITEs in the ladder differ unexpectedly; lint_sip_request to validate a single message you pulled from the ladder.' It also specifies when to change default behavior, e.g., 'Pass groupByIp: false to restore the legacy layout when you specifically need port-level granularity.'

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

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

Beyond the readOnlyHint annotation, the description discloses additional behavioral traits: 'pure CPU, no network', free cost, a four-step internal workflow, and the specific high-risk race condition it flags (lump-vs-subst). It also explains that it returns suggestedQueries for grounding reviews in vendor docs, which is significant behavioral context not present in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear trigger statement, a numbered workflow, and a pairing note. Every sentence contributes operational or contextual value: cost/read-only status, when to use, what the tool does, and how to integrate with sibling tools. No filler or redundancy.

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

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

For a complex config-review tool with no output schema, the description thoroughly conveys what the user can expect: a structured outline of loaded modules/routes/profiles, risk flags with specific examples, and a list of suggestedQueries. It also covers the filenameHint/vendorHint usage context through the detection step and pairing guidance. This is sufficient for an agent to invoke the tool and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents all three parameters with 100% coverage, including descriptions for text, vendorHint, and filenameHint. The description adds minimal parameter-specific value beyond schema, though step 1 references filename+structural signatures aligning with filenameHint. Baseline 3 is appropriate because the schema does the heavy lifting and the description does not meaningfully enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states this tool reviews SIP/VoIP config files, enumerates specific file types and vendors, and explicitly lists what it does (detect vendor, extract outline, surface risk flags, return suggestedQueries). It also distinguishes itself from siblings like detect_sip_vendor_from_config by focusing on full config review, not just vendor detection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit trigger phrases ('review my config') and example files, and recommends pairing with search_sip_docs and webrtc_sip_checklist for specific cases. However, it does not explicitly state when NOT to use this tool or contrast with the highly similar detect_sip_vendor_from_config sibling, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description adds meaningful extra context: cost (one embed + one vector search), network direction (outbound to embed model only), return behavior (ranked snippets with source URLs), and an instruction to cite source_url verbatim. It also warns that the corpus has current text that training data may not, adding important reliability context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence is information-dense. It is front-loaded with a cost/network/read-only summary, then organized into corpus scope, trigger conditions, return behavior, examples, and tool-pairing guidance. The structure makes the length justified for a tool with many trigger categories and no filler.

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

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

For a RAG search tool with no output schema, the description fully covers what is searched, when to use it, what it returns, and how to cite sources. It also references alternative tools and the optional vendor filter, leaving no obvious gaps for an agent to misuse the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the description doesn't need to restate parameter meanings. It adds only mild context, such as using detect_sip_stack to derive the vendor filter and illustrating query specificity with examples, but the schema already instructs users to include vendor/header/code/RFC. Baseline 3 is appropriate because the schema carries the semantic load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Vector search over Sipflow's curated VoIP knowledge base' and enumerates the corpus (vendor docs, RFCs, STIR/SHAKEN, branded-calling, fax-over-IP). It clearly distinguishes this RAG search from sibling lookup tools by stating 'USE FIRST whenever the user asks about - or attaches - anything SIP/VoIP/telecom shaped' and naming alternatives in the Pair-with line.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit 'USE FIRST whenever' guidance plus extensive trigger conditions: vendor configs, dialplan/routing scripts, SIP headers, response codes, RFC questions, captured traces, STIR/SHAKEN, and T.38 fax issues. It also provides 13 concrete examples and explicitly says to pair with detect_sip_stack, lookup_response_code/lookup_sip_header to short-circuit, and troubleshoot_response_code for status-code-rooted questions, covering when-not-to-use.

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

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

The description adds behavioral context beyond the readOnlyHint annotation: '[cost: free (pure CPU, no network) | read-only]' and notes it is hand-curated. This gives the agent useful constraints about side effects and resource usage without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured. It front-loads cost/read-only info, states the output, gives usage context, lists scenarios, and pairs with sibling tools—all in a few sentences with zero fluff.

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

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

Given no output schema, the description adequately explains the return value (Mermaid sequenceDiagram + bullet list with RFC references). It covers usage scenarios, available options, and alternatives. Combined with the rich input schema, the description is fully sufficient for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds the list of available scenarios (also in the enum) but does not provide substantial extra meaning for any parameter. Baseline 3 applies; schema carries the parameter documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Return a hand-curated SIP scenario as a Mermaid sequenceDiagram plus a bullet list of step-by-step explanations with RFC references.' It clearly distinguishes from siblings by explicitly pairing with render_sip_ladder for real traces and search_sip_docs for vendor quirks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit usage guidance is provided: 'Use this when the user asks "show me what X looks like" and you don't have a real trace handy.' It also names alternatives and when to use them, giving clear when/when-not direction.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds 'cost: free (pure CPU, no network)' and 'static' to reinforce non-mutating behavior, plus details about mapping to RFC anchors and operator causes. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a cost/read-only note, a clear statement of what the tool does, an input instruction, and pairings with alternatives. It is front-loaded and every segment earns its place, staying compact without sacrificing useful details.

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

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

The description covers inputs, purpose, and relationship to siblings, which is sufficient for an agent to decide when to invoke it. Minor gap: no output format is described, but for a static explainer with no output schema this is not a significant deficiency.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with both parameters described ('Attestation level: A Full / B Partial / C Gateway' and 'SIP response code commonly seen in STIR/SHAKEN flows'). The description adds the either/or usage rule and RFC 8588 context, but the schema already carries the core meaning, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as a 'static explainer' that maps attestation levels (A/B/C) and SIP codes to plain-English explanations. It distinguishes from siblings by explicitly noting it is not a validator and pairing it with validate_stir_shaken_identity for cryptographic verdicts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear guidance: 'Provide either attestation or code' and names two sibling tools with specific use cases (validate_stir_shaken_identity for JWS verification, search_sip_docs for ATIS/CTIA/RFC depth). Lacks explicit 'do NOT use when' exclusions, but the pairings effectively communicate scope.

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

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

The description goes far beyond annotations by disclosing cost ('write (single MongoDB row)'), rate limits ('3/min, 20/day per IP hash'), storage behavior ('anonymous row keyed by daily-rotating IP hash'), return value ('ticket id (fb_xxxxxxxx)'), and a server-side sanitizer backstop. It also details the privacy contract, including when userConsent is required. This is rich behavioral context that the annotations alone ('readOnlyHint: false, idempotentHint: false') do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place. It front-loads the core purpose and cost/rate line, then uses structured headers, numbered privacy rules, and bullet-point categories. The layout makes complex consent requirements easy to follow, and there is no filler or repetition.

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

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 explains the return value (ticket id), rate limits, data retention, category taxonomy, and the step-by-step consent workflow. It covers all operational and safety aspects an agent needs to invoke this tool correctly, making it exceptionally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema covers 100% of parameters, the description adds meaningfully to parameter semantics. For example, it instructs to 'Pipe minimize_sip_trace output here' for traceExcerpt, mandates that userConsent 'must be set only after you have shown the user the exact payload above and they have confirmed', and restricts contact to when 'the user explicitly provides an email and asks to include it'. These operational guidelines exceed the schema descriptions and are essential for correct usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Send the Sipflow team feedback when something doesn't work, a vendor or RFC isn't covered, or a tool produced a wrong/incomplete answer' – a specific verb, resource, and scope. It clearly distinguishes this tool from all sibling analysis tools by being the only feedback submission tool, and enumerates feedback categories to further clarify intent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool: only when the user explicitly asks to send feedback, or after completing the primary task with a clear actionable gap. It also provides category selection criteria (docs_gap, tool_bug, wrong_answer, feature_request, general) and includes explicit exclusions such as not including raw PII and waiting for consent. This is comprehensive guidance with no ambiguity.

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

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

Beyond annotations (readOnlyHint=true, openWorldHint=true), the description discloses cost (rag: one embed + one vector search), read-only nature, outbound network only to embed model, rate-limited per IP, and how vendor-specific reason phrases are folded into the embed query. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a leading cost/read-only line, a core behavior sentence, a use-case paragraph, and a pairing list. Every sentence adds distinct value; length is justified by the tool's complexity.

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

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

No output schema exists, so the description must explain return behavior, which it does (static RFC entry plus RAG hits). It also covers cost, network, rate limits, use cases, and pairings. Minor gap: no explicit output format or number of hits, but otherwise comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all three parameters. The description adds some context on how vendorHint and context influence the RAG query (folded into embed), but mostly reinforces the schema's existing semantics, so a baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the static RFC entry plus vendor-specific RAG hits for a SIP response code, and distinguishes it from sibling `lookup_response_code` by highlighting the augmented RAG capability and the 'why did <vendor> reject this' use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use ('Use when the user asks why did <vendor> reject this with <code>?') and provides alternatives and pairings with specific sibling tools for different situations (e.g., `lint_sip_request` for 4xx, `compare_sdp_offer_answer` for T.38 reinvite SDP mismatch).

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

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

The annotation readOnlyHint=true is reinforced and expanded with additional behavioral context: free CPU-only cost, no network, libphonenumber-js international coverage, NANP splitting and tagging categories. This goes well beyond the annotation and fully discloses the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with cost/read-only info and flows logically through purpose, use cases, and related tools. It is slightly longer than necessary, but every sentence adds value and it remains well-structured.

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

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

Given a single-param tool with no output schema, the description provides substantial context: input formats, classification output categories, and use cases. It does not explicitly describe the return type or error behavior, which is a minor gap, but overall it is quite complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the `number` parameter is fully documented). The description does not add new parameter semantics beyond the schema, but it reiterates the input format. Baseline of 3 is appropriate given high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Parse', 'normalize', 'classify') and resource (phone number in E.164 and NANP). It differentiates from sibling tools by emphasizing NANP-specific classification and its use in SIP/SHAKEN contexts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use the tool (validating From/P-Asserted-Identity/SHAKEN orig.tn, deciding attestation needs, sanity-checking caller ID) and pairs it with related tools (lint_sip_request, stir_attestation_explainer), providing clear alternatives and complementarity.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description discloses an external IO cost (HTTPS fetch of x5u cert), the read-only nature, specific edge-case behavior (legacy rcdi['icn'] form handling, strictRfc9795 warning/fail), and that it returns per-check pass/fail/warning. This adds significant behavioral context not present in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place: it leads with a cost annotation, then a concise functional summary, followed by edge-case details, use-case rationale, and explicit sibling pairings. It is well-structured and front-loaded, with no fluff.

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

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

Despite the tool's complexity (8 params, no output schema), the description is thorough: it covers cost, safety, functionality, edge cases, diagnostics use cases, and companion tools. The input schema fully documents all parameters, so the description is complete enough 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (per context signals) and the schema already elaborately describes rcdi, strictRfc9795, expectedIconHash, and the B64 segments. The tool description adds no additional parameter-level meaning beyond what the schema states, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Verify) and resource (SIP Identity: JWS) with detailed cryptographic operations: fetches x5u certificate, parses it, verifies ES256 signature, and validates RCD icon hash. It also differentiates from sibling tools by naming stir_attestation_explainer for A/B/C interpretation and lookup_response_code(438) for SIP context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when the tool is useful ('diagnosing 438 Invalid Identity Header rejections, expired certs, and tampered PASSporTs') and gives explicit alternatives to pair with: stir_attestation_explainer, lookup_response_code(438), and lint_sip_request. This provides clear when-to-use and when-to-use-other tools guidance.

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

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

The description discloses behavior beyond the annotations: it states cost/free, pure CPU, no network, and read-only at the very front. It also explains the regex-based matching behavior for configText ('marked as looks present or check needed based on simple regex signals'). This adds meaningful context that the readOnlyHint alone does not provide, such as the lack of network dependency and the heuristic nature of the analysis.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the cost/read-only note, then immediately states the purpose, followed by usage and pairing. Every sentence carries value: the cost bracket, the topic list, the configText behavior, the use case, and the sibling tool pointers. No fluff or redundant repetition of schema or annotations.

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

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

For a tool with three optional parameters and no output schema, the description covers the primary use cases and clarifies how configText alters results. It does not specify the exact output format or what happens when neither vendor nor configText is supplied, but that is inferable (a generic checklist). The mention of specific SIP/WebRTC domains and the 'Pair with' recommendations make it sufficiently complete for an agent to select and use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage with detailed parameter descriptions (e.g., configText: 'When supplied, items with matching signals are marked as present'; vendor: 'Omit and supply configText to auto-detect'). The description adds little beyond the schema—only restating the regex-signal idea that is already in the schema. Since schema coverage is high, the baseline is 3, and there is no additional semantic enrichment to justify a higher score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with 'Return a curated checklist of WebRTC ↔ SIP requirements' followed by a specific list of items (WSS transport, ICE gathering, DTLS-SRTP, etc.). This clearly states the verb, resource, and scope, and distinguishes it from sibling tools like parse_sdp or review_sip_config by focusing on the WebRTC-to-SIP bridge checklist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage guidance: 'Use when the user is building a WebRTC ↔ SIP bridge or troubleshooting one (no media, one-way audio, ICE failures).' Also names specific alternatives and companions in 'Pair with: review_sip_config for the full structured outline; search_sip_docs... parse_sdp / compare_sdp_offer_answer...' This goes beyond implied usage and gives clear when/where-to-use versus other tools.

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