Sipflow

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

Description discloses read-only, pure CPU operation, aligning with annotations. It details the specific checks performed, providing rich behavioral context beyond the annotations alone.

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?

Concise, well-structured description with key information front-loaded. Every sentence adds value—first paragraph details functionality, second paragraph provides usage context and sibling tool suggestions.

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 no output schema, the description covers what the tool returns (list of issues) and the types of checks performed. Given the tool's complexity and the richness of annotations/schema, it is complete enough for the agent to 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% with simple descriptions ('SDP offer body', 'SDP answer body'). The description adds no additional parameter-specific meaning beyond what the schema provides, so baseline score 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?

Clearly articulates what the tool does: compare SDP offer/answer and surface call-breaking issues. Includes specific checks (codec intersection, direction compatibility, DTLS conflicts) and distinguishes itself from sibling tools like parse_sdp 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?

Explicitly states when to use (debugging 488 Not Acceptable Here, no-audio, one-way-audio) and provides pairings with other tools, offering clear guidance on when to use versus 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?

The description goes beyond annotations by stating it is 'cost: free (pure CPU, no network) | read-only', explaining the read-only nature and cost. It also details the two detection modes and the auto fallback behavior, providing full behavioral 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 well-structured and front-loaded: a cost line, a clear purpose sentence, bullet points for input types, return value explanation, and pairing suggestions. Every sentence is informative and non-redundant.

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 explains what the tool returns (a vendor slug) and how it can be used with other tools. It covers the key aspects, though it does not explicitly mention behavior for unknown inputs or edge cases, but is complete for typical use.

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?

While all parameters have schema descriptions (100% coverage), the description adds meaning by explaining how vendor slugs align with search_sip_docs and that filenameHint improves config-mode detection. It adds context 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: 'Identify the SIP product behind a piece of input.' It specifies two distinct input types (SIP trace and vendor config blob) and lists example vendor slugs, making the tool's function unambiguous and differentiating it from siblings.

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 provides pairing suggestions: search_sip_docs, review_sip_config, and troubleshoot_response_code, clearly indicating when to use this tool versus alternatives. This gives strong guidance on tool selection.

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 value by noting 'pure CPU, no network' and confirming 'read-only' cost. It also explains the heuristic nature and outputs, surpassing what annotations provide.

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 yet packed with essential information: cost, sibling relationship, use cases, outputs, and tool pairings. Every sentence serves a purpose, and key details are front-loaded.

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 no output schema, the description fully explains what the tool returns (vendor slug, confidence, signals) and what it does not do. It also provides context for further actions, making it self-contained for a simple detection 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 coverage is 100% with clear descriptions for both parameters. The description hints at the filenameHint's purpose (bias detection) but adds no new semantic detail beyond the schema, meeting the baseline for high 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 specific verb ('detect') and resource ('SIP vendor from a config file'). It explicitly differentiates itself from its sibling 'detect_sip_stack' by being 'heuristic-only' and 'scoped to vendor configs', providing a distinct purpose.

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 cases: 'when the user asks what is this config? or attaches a SIP config file.' It also clarifies when not to use it (detect-only, does not extract directives or flag risks) and suggests pairing with 'review_sip_config' and 'search_sip_docs' for deeper analysis.

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 readOnlyHint annotation, the description adds 'cost: free (pure CPU, no network) | read-only, no persistence' and enumerates all diff categories (added, removed, mutated, etc.), including delegated SDP comparison via compareSdp. This fully discloses 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 compact (5 lines) with front-loaded cost/behavior note, then a concise explanation of what the tool does and when to use it. Every sentence adds value, no repetition or 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?

The description covers the tool's purpose, input (two SIP messages), output (structured per-header diff), edge cases (SDP delegation), and integration with sibling tools. Despite no output schema, the explanation of diff types is sufficient for understanding return value.

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 descriptive parameter definitions (e.g., 'SIP message as observed at the *downstream* hop'). The description adds usage context (upstream/downstream) but no additional parameter semantics beyond the schema, meeting the baseline for high 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 diffs two SIP messages, listing specific diff types (added, removed, mutated, etc.) and the use case (comparing same request at adjacent hops). It distinguishes itself from sibling tools like parse_sip_message and lint_sip_request by mentioning when to use them in conjunction.

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 guidance: 'Use FIRST when the user has two captures...' and suggests pairing with other tools (parse_sip_message, lint_sip_request, search_sip_docs) for specific follow-ups. This provides clear when-to-use and when-not-to-use context.

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?

Discloses cost (external_io), read-only nature, rate limits (10/min, 200/day), egress safety (SSRF guard, depth cap, TLS probe caps). 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?

Well-structured with front-loaded purpose and cost, but lengthy. Uses formatting effectively. Could be more concise but appropriate for 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?

Covers resolution process, return values, TLS details, edge cases (SSRF, rate limits), IP ACL caveat, and sibling tools. Complete for a complex diagnostic tool without output schema.

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%, baseline 3. Description adds meaning: explains target interpretation (SIP URI, host:port, bare host) and transport hint behavior. Adds value beyond 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 walks DNS (NAPTR → SRV → A/AAAA) like a SIP UA and performs TLS handshakes for sips targets. It distinguishes from siblings 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?

Explicitly describes when to use (diagnose carrier routing, TLS cert issues) and provides caveats (IP ACLs). Suggests pairing with other tools and provides alternative scenarios.

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 indicate readOnlyHint=true and openWorldHint=true. The description adds cost details, rate limiting, privacy behavior (pseudonymization, field stripping), truncation handling, and that diagnostics are computed at share-creation time or on the fly. This goes well beyond the annotations, though the openWorldHint is not fully explained.

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-organized, front-loading cost and read-only nature, then purpose, then detailed behavior. Every sentence is informative, though it could be slightly shortened without losing clarity. It remains efficient for an agent to parse.

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 tool without an output schema, the description covers return contents (trace, AI output, diagnostics, metadata, privacy info) and pairing suggestions. Missing explicit error handling (e.g., for invalid URLs), but otherwise comprehensive enough for most use cases.

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 sole parameter 'url' has schema description but the tool description adds valuable constraints: example format, required path structure (/share/<token>), and explicit rejection of /api/share/ endpoints. This significantly helps the agent provide a correct input.

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: to load a Sipflow share URL and retrieve both the SIP trace and any AI analysis. It distinguishes itself from sibling tools by mentioning specific pairing with tools like minimize_sip_trace and render_sip_ladder, and by detailing what it returns that others don't.

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 'Use this whenever a user pastes a /share/<token> URL', providing clear when-to-use. It also explains what is not included (privacy-stripped fields). However, it does not explicitly state when not to use or provide direct alternatives, leaving minor 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?

Annotations already provide readOnlyHint=true and openWorldHint=false; the description adds operational context: 'cost: free (pure CPU, no network) | read-only, no persistence'. It also enumerates specific behavioral traits like the types of checks performed (e.g., two From headers, missing CRLF, tag parameters on PAIPPI, PASSporT mismatches). No contradictions.

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/safety header, then purpose, then enumerated failure modes, then usage guidance, then pairing suggestions. Every sentence is informative, with no filler. Concise yet comprehensive.

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 (SIP RFC compliance linting) and the absence of an output schema, the description thoroughly covers purpose, input requirements, behavioral constraints, and integration with sibling tools. An agent can confidently understand when to invoke this tool and what results to expect.

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 one parameter 'text' with 100% coverage, including a description of format (starts with request line, CRLF/LF separated). The description reinforces that it expects a single raw SIP request (typically INVITE) but does not add significant new detail beyond the schema. Slight enhancement by specifying typical use case.

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 'Run RFC 3261 / RFC 3325 / RFC 8224 / RFC 8225 / CTIA BCID compliance checks on a single raw SIP request (typically an INVITE) and return a list of findings.' It specifies the exact RFCs and compliance domains, lists specific failure modes caught, and distinguishes from sibling tools like parse_sip_message (structural only) and validate_stir_shaken_identity (cryptographic).

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 advises 'Use FIRST when chasing 422 / 400 Bad Request / 484 Invalid FROM on a single INVITE' and provides a 'Pair with:' section listing three alternative tools with clear differentiation (e.g., parse_sip_message for structural checks on any SIP message, validate_stir_shaken_identity for cryptographic verdict). This gives both when-to-use and when-not.

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), description reveals it's free, pure CPU, no network, sub-millisecond. No contradictions.

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?

Three concise, front-loaded sections: cost/tag, return details, usage guidance. No fluff, every sentence earns its place.

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 no output schema, description lists full return content. Combined with usage guidance and context signals, the tool is fully specified for its simple lookup purpose.

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 already fully describes the single parameter (integer 100-699, example). Description adds no new semantic meaning beyond restating the range.

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 specifies static lookup of SIP response codes (100-699). Lists return fields (name, RFC anchor, category, description, causes, vendor variants). Distinguishes from siblings by positioning itself as the first, instant 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?

Explicitly states 'USE FIRST' for any 3-digit SIP code. Provides specific pairing guidance with other tools (e.g., troubleshoot_response_code, lint_sip_request) based on context.

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 destructiveHint=false. The description adds [cost: free (pure CPU, no network) | read-only] and details the return fields (canonical form, compact alias, RFC anchor, etc.), providing additional value beyond annotations. No contradictions.

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 well-structured: it opens with cost/read-only info, then explains what the tool does, provides usage guidance, and lists paired tools. Every sentence adds value, and information is front-loaded.

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 simplicity (single parameter, no output schema), the description fully covers behavior: what it returns, when to use it, how it relates to siblings. No gaps remain for an AI agent to understand selection and invocation.

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 a description for the `name` parameter. The description adds context by noting the parameter is case-insensitive and giving examples ("Via" / "v"), extending the schema's meaning.

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 looks up a SIP header by canonical or compact form, listing examples like "Via" / "v". It distinguishes itself from siblings by advising to use it first for specific headers and pairing with other tools for further analysis.

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 'USE FIRST when the user asks about a specific header... sub-millisecond, no API cost.' It also suggests pairing with `lint_sip_request` and `search_sip_docs`, providing clear context. It doesn't explicitly state when not to use it, but the pairings imply exclusions.

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?

Explicitly declares read-only, no persistence, cost-free, and in-memory processing, going beyond annotations to add behavioral 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?

Description is thorough but somewhat lengthy; front-loaded with key properties. Each sentence adds value, but could be more concise.

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?

Covers input format, preservation/pruning behavior, safety, and pairing with related tools. No output schema, but explanation suffices for a minimization 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 coverage is 100%, and description adds value by elaborating on acceptable input formats for 'text' and truncation behavior for 'maxBytes', exceeding baseline.

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 reduces a raw SIP trace to compact form for LLM, with specific verb 'minimize' and resource 'SIP trace'. It distinguishes from siblings by describing pairing with other tools like detect_sip_stack.

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 detailed input format guidance and pairing suggestions, but lacks explicit when-not-to-use instructions relative to alternatives. It states safe for production, which implies usage context.

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 it with 'read-only' and 'pure CPU, no network'. It adds detail on the structured view returned, but does not mention any edge cases or additional behaviors.

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?

Concise and well-structured: cost hint, then main functionality, followed by use cases and pairings. 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?

The description fully covers the tool's purpose, input semantics, and relationship to siblings. Even without an output schema, it lists the major fields returned, making it complete for the intended use.

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% for the single parameter. The description adds clarity by specifying the SDP body is the part after the empty line in an INVITE/200/UPDATE, which aids 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?

Clearly states it parses an SDP body and returns a structured view, listing key fields such as origin, session, timing, and per-media codecs. Explicitly distinguishes from sibling tools like compare_sdp_offer_answer and webrtc_sip_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 guidance on when to use (debugging WebRTC ↔ SIP interop) and suggests pairing with compare_sdp_offer_answer for full negotiation context and webrtc_sip_checklist for bridge-config angle.

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 behavioral traits beyond annotations: it states the cost ('free, pure CPU, no network'), confirms read-only and no persistence, and details the exact structural flags the parser can detect. This aligns with annotations (readOnlyHint: true) and adds valuable 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 a single paragraph that front-loads essential info (cost, read-only) and then details outputs and usage. It is relatively concise, though a bit dense; every sentence adds value, but could be slightly more streamlined.

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 simplicity (one parameter, no output schema, clear annotations), the description is complete: it explains the output format, flags, use cases, and relationships with sibling tools. No gaps for an agent to interpret.

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 one parameter 'text' with full description covering format requirements (start line, headers). Schema coverage is 100%, so the description does not add new semantic meaning beyond reinforcing the expected input.

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: parsing a single raw SIP message into a structured view. It explicitly lists outputs (start line, headers, body, duplicate-header counts, flags) and distinguishes from sibling tools like lint_sip_request and diff_sip_messages.

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 when-to-use guidance: 'Use FIRST when the user pastes a single INVITE / 200 / NOTIFY and asks...' and suggests pairing with specific sibling tools for complementary tasks. It also notes cost and read-only nature, aiding agent decision-making.

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 details lane labeling logic, fallback behavior, and cost (free, pure CPU). 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 efficiently with a clear opening sentence, structured details (lane labeling), and a pairing section. Every sentence adds value with no 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 the 10 parameters and no output schema, the description covers core functionality, key algorithms, and complements with sibling tools. It could be more explicit about error handling or output format details, but overall it's 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 coverage is 100%, so baseline is 3. The description adds valuable context for parameters like aliases (match order) and compact (drops retransmissions), raising the score above baseline.

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: 'Parse a raw SIP trace ... and emit a Mermaid sequenceDiagram block'. It distinguishes itself from sibling tools by explicitly pairing with minimize_sip_trace, diff_sip_messages, and lint_sip_request.

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' section advises when to use sibling tools instead, and the note about chat hosts rendering Mermaid inline provides usage context. This gives clear guidance on when and with what alternatives 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?

Annotations declare readOnlyHint=true, and the description adds that it's 'pure CPU, no network' and 'read-only'. It details the processing steps (vendor detection, outline extraction, risk flagging, suggested queries) and mentions a specific risk (subst race), giving full behavioral 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 well-structured with numbered steps and a pairing section. It front-loads cost and read-only nature. While slightly lengthy, every sentence adds value and the structure aids readability.

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 no output schema, the description explains return value as structured outline, risk flags, and suggestedQueries. It covers inputs, behavior, and pairing, making it complete enough for this complex 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 coverage is 100% and the description adds context: filenameHint improves vendor detection, vendorHint skips auto-detection. This goes beyond schema descriptions, earning a score above baseline.

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 explicitly states the tool reviews SIP/VoIP configs, detects vendor, extracts outline, and surfaces risk flags. It clearly distinguishes from siblings like parse_sip_message by specifying input type (config files vs. messages).

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 clearly indicates when to use: when user asks to 'review my config' or attaches relevant files. It also suggests pairing with search_sip_docs and webrtc_sip_checklist. While it doesn't explicitly list alternatives, the context of sibling tools provides differentiation.

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 cost structure ('[cost: rag (one embed + one vector search) | read-only, network: outbound to embed model only]'), which goes beyond the annotations that already declare readOnlyHint=true. It also explains that results include source URLs and instructs to cite them verbatim, providing clear behavioral expectations.

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?

Despite being long, the description is well-structured and every sentence adds unique value. It is front-loaded with the most critical use case, then covers corpus, trigger conditions, examples, and pairing advice. 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?

Given the complexity (4 parameters, 28 sibling tools, rich annotations), the description is remarkably complete. It covers purpose, usage, behavior, parameters, and inter-tool relations. It also addresses return format and citation guidance, compensating for the lack of an output schema.

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 all 4 parameters, so the description does not need to explain each parameter in detail. However, it adds value by providing usage tips for the query parameter ('Be specific - include vendor name...') and suggesting how to derive the vendor filter using detect_sip_stack. This enhances the schema's guidance.

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 it is a vector search over a curated VoIP knowledge base, lists specific vendors, RFCs, and topics covered, and provides numerous example queries. It distinguishes itself from sibling tools by saying 'USE FIRST' for anything SIP/VoIP/telecom shaped and explicitly pairs with other tools like detect_sip_stack.

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 when-to-use guidance ('USE FIRST whenever the user asks about - or attaches - anything SIP/VoIP/telecom shaped'), lists trigger conditions, and suggests using sibling tools like lookup_response_code or detect_sip_stack to short-circuit when appropriate. It also includes example queries that cover a wide range of scenarios.

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?

Description adds '[cost: free (pure CPU, no network) | read-only]' beyond annotations, disclosing safety and cost. It also specifies output format and that scenarios are hand-curated. No contradiction with annotations; readOnlyHint=true is consistent.

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?

Three compact sentences plus list of scenarios and pairing guidance. Every sentence serves a purpose: purpose, usage, available scenarios, complementary tools. 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 no output schema, the description fully explains return format (Mermaid diagram + bullet list with RFCs). Verbose and includeExplanation details clarify optional parts. All 4 parameters are covered. For a diagram generation tool, context is 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?

All 4 parameters have schema descriptions (100% coverage), and the description adds value: actorNames mapping 'to the first/second/third lane in left-to-right order,' verbose explains 'off by default to keep responses small,' includeExplanation specifies 'Append a bulleted Notes section.'

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?

Description clearly states 'Return a hand-curated SIP scenario as a Mermaid sequenceDiagram plus a bullet list of step-by-step explanations with RFC references.' It identifies the verb (Return), resource (SIP scenario), and output format, while distinguishing from siblings like render_sip_ladder for real traces.

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 guidance: 'Use this when the user asks "show me what X looks like" and you don't have a real trace handy.' Also pairs with search_sip_docs and render_sip_ladder, clarifying when to use alternatives. The scenario enum list further guides selection.

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?

Disclosures include 'read-only', 'pure CPU, no network', and 'static explainer' which aligns with annotations (readOnlyHint: true) and adds context beyond annotations about cost and 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?

Two compact paragraphs that front-load purpose and usage. Every sentence adds value: first paragraph explains function, second gives pairing guidance. No wasted words.

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 static explainer without output schema, the description adequately covers what it returns (plain-English explanations, RFC anchors, operator causes) and how it fits among many sibling tools.

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. The description restates the two parameters with examples but adds little additional semantic information beyond what the schema 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 states it is a 'static explainer for STIR/SHAKEN' that maps attestation levels and SIP codes to plain-English requirements and RFC anchors. It explicitly distinguishes from siblings like validate_stir_shaken_identity 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?

Provides explicit guidance: 'Provide either attestation (A/B/C) or code' and 'Pair with: validate_stir_shaken_identity... search_sip_docs...' to indicate when to use this tool versus 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description adds critical behavioral context: a) it is a write operation costing a MongoDB row, b) rate-limited per IP (3/min, 20/day), c) returns a ticket id, d) includes a privacy contract with PII-handling rules, and e) discloses a server-side sanitizer backstop. All disclosures align with annotations and there is 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?

The description is well-structured: cost/rate-limits first, then purpose, categories, and a numbered privacy contract. It is front-loaded and organized. However, it is somewhat verbose (especially the privacy contract could be condensed) and the format uses markdown-style elements that may not render in all contexts. Still, it efficiently conveys necessary information.

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 (9 parameters, privacy contract, rate limits, categories), the description is fully complete. It covers all aspects an agent needs to invoke correctly: categories, required fields, consent mechanics, PII restrictions, and return value. No output schema exists, but the return value (ticket id) is described. No gaps remain.

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?

With 100% schema coverage, the description still adds significant value: it explains the categories in depth, reiterates field constraints (e.g., traceExcerpt requires minimization via minimize_sip_trace), and clarifies the consent flow. It also elaborates on the optional fields (contact, relatedTool, etc.) beyond the schema's 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: '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.' It uses specific verbs and resources ('submit feedback about Sipflow tools, docs, or coverage') and is easily distinguishable from all sibling tools, which are SIP analysis and diagnostics tools.

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 when-to-use guidance (e.g., 'when something doesn't work, a vendor or RFC isn't covered, or a tool produced a wrong/incomplete answer') and a detailed privacy contract with numbered rules for when and how to use the tool. It also lists categories (docs_gap, tool_bug, wrong_answer, etc.) that help the agent decide appropriateness. While no alternative feedback tool exists, the guidance is thorough and actionable.

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 adds cost details ('rag: one embed + one vector search'), network outbound, rate limiting, and the specific behavioral trait of folding vendor-specific reason-phrase variants into the embed query. This provides substantial transparency beyond structured fields.

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 and read-only info in brackets. It is structured with clear sections (cost, comparison, usage, pairing). While slightly long, each part serves a purpose, and the information density is high.

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-based tool without an output schema, the description adequately explains inputs and intended behavior. It does not specify exact return format, but the context provided is sufficient for an AI agent to understand when and how to use it. Minor gap but 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?

With 100% schema coverage, the description adds qualitative value: it notes that 'vendorHint' is 'Strongly recommended' and explains how 'context' can be used. This goes beyond the schema descriptions, but does not drastically change understanding, so a 4 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 'troubleshoots a SIP response code' and specifies it returns 'static RFC entry PLUS the top vendor-specific RAG hits'. It distinguishes itself from sibling 'lookup_response_code' by being augmented with vendor-aware search, providing a specific and distinct purpose.

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: 'Use when the user asks "why did <vendor> reject this with <code>?" and you want vendor-grounded common causes'. It also provides pairing suggestions with specific sibling tools for different scenarios, offering clear guidance on 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?

Description adds value beyond annotations (readOnlyHint and cost=free). It explains the underlying library (libphonenumber-js), international coverage, NANP splitting details, and classification tags (toll-free, premium, etc.), providing deep behavioral 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?

Highly concise: cost/read-only info front-loaded, then clear bullet points for features and use cases. Every sentence earns its place with no 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?

Lacks explicit description of the return value or output format. Since there is no output schema, the description should at least mention what the tool returns (e.g., a classification result object). This gap reduces completeness despite other strengths.

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 a good description. The description adds nuance ('in any common form', 'E.164 is preferred; 10-digit US numbers accepted') that aids correct usage, earning a score above baseline.

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-resource combination ('Parse, normalize, classify') and clearly differentiates from siblings by listing paired tools (lint_sip_request, stir_attestation_explainer) and specific use cases (validating From, deciding attestation).

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 guidance with phrases like 'Use when validating...', 'deciding whether...', and 'sanity-checking...'. Also recommends pairing with sibling tools, providing clear context for when to use 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 indicate readOnlyHint=true; description adds cost hint, external IO, and edge case handling (legacy icn with warning/failure). No contradictions.

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?

Well-structured with cost hint upfront, core action, edge case, return type, and sibling pairing. Slightly dense but efficient.

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 tool with 8 params, nested objects, and external IO, description covers validation flow, edge cases, and return type. Output schema absent but return details mentioned.

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 100% parameters with descriptions; description adds minimal extra parameter detail beyond 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 it verifies a SIP Identity JWS, explains the process (fetch x5u, verify signature, validate icon hash), and distinguishes from siblings by naming tools to pair with.

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 pairing suggestions and diagnostic use cases (438 errors, expired certs, tampered PASSporTs). Lacks explicit when-not-to-use but context is clear.

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; description reinforces with 'read-only' and 'no network'. Adds useful detail about regex-based marking when configText is supplied, but doesn't go beyond that.

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?

Description is efficient, front-loaded with cost/read-only, lists checklist items, usage guidance, and pairing. No fluff, but slightly long. Still 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 no output schema and simple behavior, description is fairly complete. Could mention output format explicitly, but context signals and sibling list provide enough overall 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 coverage is 100% with each parameter described. Description repeats schema information (e.g., vendor auto-detection) without adding new 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 states the tool returns a curated checklist of WebRTC↔SIP requirements, listing specific items. It differentiates from siblings by explicitly mentioning pairing with review_sip_config 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?

Explicitly states when to use: building or troubleshooting a WebRTC↔SIP bridge, with concrete failure scenarios. Also provides pairing guidance with related tools.

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