netops-mcp

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

Beyond annotations (readOnly, idempotent), the description adds that the tool sorts results by soonest expiry, flags near-expiry certs, and auto-extracts domains from config files, providing useful 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?

The description is three sentences long, front-loaded with the primary purpose, then input options, then output behavior. 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?

Given no output schema, the description hints at the output format (sorted list with flags) but could be more explicit. It adequately covers the tool's capabilities for a batch check 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 description adds specifics not in the schema: it names supported config file types (nginx, Caddy, Traefik, compose) and clarifies that paths trigger automatic domain extraction, enhancing 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 the tool checks TLS certificate expiry across many domains, distinguishes from siblings like tls_inspect (single domain) by emphasizing batch operation and automatic domain extraction from config files.

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 implies when to use (batch checks) but does not explicitly contrast with sibling tools like tls_inspect for single-domain checks, or mention when not to use (e.g., for other certificate types).

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, idempotentHint, and destructiveHint=false. The description adds value by specifying exactly which local files are read and the nature of the cross-check (live DNS correlation), going beyond the annotation safety profile.

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 consists of two concise sentences. The first front-loads the action and resources; the second emphasizes unique value proposition ('No remote service can do this'). 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?

The tool has low complexity (1 optional parameter, no output schema). The description covers inputs and high-level outcome but lacks explanation of return values or output format, which is necessary since no output schema exists.

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% for the single optional parameter 'domain', so the schema itself provides full meaning. The description does not add any additional context about the parameter beyond what the schema says, meeting the baseline for 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 verb ('Reads', 'cross-checks', 'surfaces'), the specific resources ('/etc/hosts', 'resolv.conf', 'live DNS'), and the outcome ('explains weird resolution'). It distinguishes from sibling network diagnostic tools by focusing on local config files.

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 implies usage for local DNS config debugging ('No remote service can do this'), but does not explicitly state when to use this tool versus siblings like dns_lookup or net_diagnose. Guidance on when not to use it is absent.

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 readOnly, idempotent, non-destructive behavior. The description adds valuable context: it returns a clean Markdown report and includes specific probe types (DNS, reachability, TLS, HTTP timing, global probes). This complements the annotations well without 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 concise: two sentences with no extraneous words. It front-loads the purpose and output format, then lists contents efficiently.

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 (2 parameters, no nested objects, no output schema), the description adequately covers purpose, output format, and contents. It mentions 'local context' but does not elaborate, which is a minor gap. Overall, sufficient for automated 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 clear descriptions for both parameters (target, include_global). The description mentions 'optional global probes' but adds no further detail beyond what the schema already provides. 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 clearly states that the tool runs a comprehensive battery of probes and returns a Markdown report for bug reports. It lists specific areas like DNS, reachability, TLS, HTTP timing, and optional global probes, which distinguishes it from sibling tools that focus on individual checks. However, it does not explicitly differentiate itself 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 implies the tool is for obtaining a full diagnostic report for support tickets, but it does not provide explicit guidance on when to use this tool versus the many siblings (e.g., for specific checks like dns_lookup or http_probe). No exclusions or alternative tools are mentioned.

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 readOnly and idempotent. The description adds that the check is heuristic and requires network access, which is useful context 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?

Two sentences, front-loaded with purpose, efficient and 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?

Despite no output schema, the description explains what is reported (IP, resolvers, leak flag) and notes heuristic nature. Adequate for a no-parameter 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?

No parameters exist, so schema covers 100%. The description adds no param info, which is acceptable; baseline for 0 params is 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 clearly states it reports public egress IP and DNS resolvers, flagging potential leaks. This distinguishes it from sibling tools like dns_lookup and net_ping.

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 mentions it's heuristic and needs network access, implying when to use, but doesn't explicitly state alternatives or 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds supported record types and optional custom resolver, providing useful behavioral context 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?

Two sentences, front-loaded with core functionality, second sentence gives usage guidance. No redundant 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 simplicity, full schema coverage, and comprehensive annotations, the description provides all necessary context: what it does, supported types, and when to 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 coverage is 100% with descriptions for all 3 parameters. Description enriches meaning by listing record types for 'type' and clarifying 'optional custom resolver' for 'server'.

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 uses specific verb 'resolve' and resource 'DNS records', lists supported record types (A/AAAA/MX/TXT/NS/CNAME/SOA), and distinguishes from sibling 'net_diagnose'.

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 this when you ONLY need to check DNS resolution' and provides alternative tool 'net_diagnose' for full connectivity checks.

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, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by detailing the output fields (redirect chain, timing breakdown), which is beyond what annotations provide. 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 a single sentence that front-loads the action ('GET a URL') and enumerates outputs efficiently. No extraneous 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?

With one parameter, 100% schema coverage, and no output schema, the description adequately lists the return components (status, redirect chain, server header, timing breakdown). It is complete enough for an agent to understand what to expect, though additional details on error handling or formatting could improve 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?

Schema coverage is 100% with a single parameter 'url' described as 'URL to probe'. The description adds that the tool performs a GET request, but this is implied by the tool's name and purpose. Baseline of 3 is appropriate as the schema already covers the parameter fully.

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 'GET' and resource 'URL', and lists exactly what is reported (status, redirect chain, server header, timing breakdown). This clearly distinguishes it from sibling tools like dns_lookup or tcp_port_check which perform different diagnostics.

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 implies usage for HTTP probing but provides no explicit guidelines on when to use this tool versus alternatives such as tls_inspect or net_diagnose. No when-not or exclusionary context is given.

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, idempotentHint), the description details the tool's behavior: it sends DF pings, small packets pass while large disappear without ICMP reply. This adds valuable behavioral context not captured by 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 two sentences, well-structured, and front-loaded with the technique and purpose. Every sentence provides essential information 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 the tool's low complexity (one parameter, no output schema) and comprehensive annotations, the description sufficiently covers the diagnostic scenario and return behavior implied. 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?

The input schema has 100% coverage with a single parameter 'host' described as 'host to probe the path MTU to'. The description does not add extra meaning or constraints beyond this, meeting the baseline for 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 it performs Path-MTU discovery via Don't-Fragment pings to detect MTU black holes. It uses specific verbs and resources, and distinguishes from sibling tools by addressing a specific network issue that others like ping or traceroute may not catch.

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 explains the symptom (connections hang on big transfers over VPN/PPPoE), guiding when to use. However, it does not explicitly name alternative sibling tools or state when not to use this tool, missing some clarity on 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 indicate read-only, open-world, and idempotent behavior. The description adds valuable context by detailing the multi-step diagnostic process (DNS, ping, TCP, TLS, HTTP) and the verdict output, going beyond 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?

Single sentence that is front-loaded with the core purpose ('One-shot diagnosis') and efficiently lists all performed checks. No unnecessary 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?

Given the tool complexity and absence of an output schema, the description adequately outlines the multi-step diagnosis and the nature of the result ('verdict on where the failure is'). However, it could mention what happens on errors or timeout.

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 and a single parameter described clearly as 'hostname or URL to diagnose', the description adds no additional meaning beyond the schema. Baseline score 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 one-shot diagnosis that performs multiple checks (DNS, ping, TCP, TLS, HTTP) and returns a verdict, distinguishing it from specific sibling tools like dns_lookup or http_probe.

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 implies use as a comprehensive diagnostic but does not explicitly state when to use this tool instead of more specific siblings, nor does it mention any prerequisites or 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?

The description adds context beyond annotations by specifying the exact resources covered (interfaces, resolvers, WireGuard), aligning with the readOnly and idempotent 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?

One sentence, no wasted words, front-loads the purpose effectively.

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 zero-parameter tool with clear annotations, the description is mostly complete, though it could mention the output is a summary and that no input is needed.

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 zero parameters, the baseline is 4; no additional parameter documentation needed as schema coverage is 100%.

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 provides a snapshot of local interfaces, resolvers, and WireGuard interfaces, which is distinct from sibling tools that focus on specific aspects or deeper diagnostics.

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 implies it's for 'quick context' but does not explicitly state when to use this tool versus alternatives like net_diagnose or wg_status, nor does it provide usage constraints.

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, idempotentHint, openWorldHint, destructiveHint=false. Description adds useful behavioral detail: uses ICMP ping when available, falls back to TCP connect (works without root). No mention of timeouts or limits, but sufficiently covers key behavior 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?

Three concise sentences with no waste. Front-loaded with main purpose, then key constraints and alternatives. Every sentence adds value.

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 tool with two parameters, no output schema, and strong annotations, the description fully covers purpose, usage, exclusions, and fallback behavior. No missing guidance.

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 host and tcp_port. Description reinforces that tcp_port is for fallback and default 443, but adds little beyond schema. 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?

States 'Reachability check' as clear verb+resource. Distinguishes from sibling tools by explicitly noting it does NOT check application ports or HTTP, and names alternatives (tcp_port_check, net_diagnose).

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 'Use this when you ONLY need to know if a host is alive' and provides exclusions: 'It does NOT check application ports or HTTP — for that use tcp_port_check or net_diagnose.'

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, idempotentHint=true, etc., indicating safe, read-only behavior. The description adds that it runs tests from local and global probes and produces a verdict, which aligns with annotations but does not disclose additional traits like rate limits, authorization needs, or what happens on failure. The annotation coverage is sufficient, and the description adds modest operational 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 two sentences long with no unnecessary words. The title front-loads the core idea. Every sentence adds value: the first explains the mechanism, the second states a mode constraint. Perfectly 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?

No output schema is provided, and the description mentions a 'verdict' but does not explain what the verdict looks like or how to interpret it. For a diagnostic tool that combines local and remote results, this is a notable gap. The input schema is simple, but the output behavior is incompletely described.

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 both parameters (target and locations). The description's mention of 'Globalping's worldwide probes' provides slight additional context for the locations parameter, but overall the schema does most of the work. The description does not add new meaning 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 runs reachability tests from both local and global probes and provides a verdict on whether failure is local, network/ISP, or target. The title 'Is it me or them?' further clarifies the diagnostic purpose. It distinguishes from siblings like net_ping or http_probe by the comparative local-global approach.

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 implies usage for diagnosing connectivity issues from both perspectives, but lacks explicit when-to-use or when-not-to-use guidance. It mentions being disabled in --local-only mode, which is a constraint, but no alternatives or context for choosing this over sibling tools.

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, idempotentHint, destructiveHint; description adds behavioral constraints like scope-guard cap and that it doesn't send HTTP or check TLS, adding value 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?

Five concise sentences, each with distinct information, front-loaded with purpose, 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?

Covers purpose, limitations, usage context, and ordering relative to siblings; no output schema needed, complete for its 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 covers both parameters with descriptions (100% coverage), so description adds minimal extra meaning beyond the main purpose; 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?

Description clearly states it checks TCP ports on a host for connectivity, distinguishes from siblings by specifying it's not a discovery scan and doesn't check HTTP or TLS.

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 (verify a specific port is open), when not to use (not a discovery scan, doesn't check HTTP/TLS), and provides context (use after net_ping or when ICMP blocked).

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 the tool as read-only, non-destructive, and idempotent. The description reinforces this by stating it opens a TLS connection and reports information without modification. It adds value by listing the specific data points reported (certificate chain, expiry, SANs, etc.), but does not elaborate on network prerequisites or potential failure modes. Overall, transparency is good but not exceptional.

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, well-structured sentence that immediately conveys the tool's action and outputs. Every phrase adds value, and no redundant information is present. It is appropriately sized.

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 action and explicitly lists the expected outputs, which compensates for the absence of an output schema. However, it does not address potential error conditions, return format structure, or how to interpret the validation status. Given the moderate complexity and the presence of detailed annotations, the completeness is good but could be enhanced with a brief note on error handling or output type.

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 covers 100% of parameters with basic descriptions, so the baseline is 3. The tool description does not add any additional semantic information about the parameters (e.g., format of host, allowed ports, how to handle errors). It simply uses the parameter values implicitly. No extra value is provided.

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 ('Open...and report') and clearly lists the provided outputs (certificate chain, expiry, SANs, etc.), making the tool's purpose unambiguous. While it does not explicitly contrast with siblings like 'cert_sweep', the detailed output list implicitly differentiates it as an inspection tool for a single TLS session.

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 no usage guidelines, such as when to prefer this tool over related siblings like 'cert_sweep' or 'net_diagnose'. It does not mention prerequisites, limitations, or contexts where this tool is appropriate. This lack of guidance hinders an agent in selecting between similar networking tools.

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, openWorldHint, idempotentHint, and non-destructive behavior. Description adds that it wraps system traceroute/tracert, hinting at shell execution, but lacks details on permissions, rate limits, or output format.

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 concise sentences front-load the purpose and include a note about underlying implementation. No unnecessary words 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?

For a simple tool with full schema coverage and robust annotations, the description is largely complete. It mentions 'per-hop latency' hinting at output, but lacks explicit details about return format or additional behavior.

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 descriptions cover 100% of parameters: 'destination host' for host and 'max hops (default 20)' for max_hops. Description adds no additional semantics beyond what the schema provides, meeting the 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?

Description clearly states the verb 'Trace' and the resource 'network path to a host hop by hop, with per-hop latency'. It distinguishes from sibling tools like net_ping (which measures latency/packet loss) by emphasizing hop-by-hop tracing.

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?

Description implies usage for network path tracing but does not explicitly state when to use this tool over alternatives like net_ping, dns_lookup, or tcp_port_check. No exclusion criteria or context is provided.

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 read-only and idempotent behavior; the description adds the explicit need for network access and confirms the comparative nature. 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 compact sentences each add value: action, benefit, prerequisite. 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?

The description does not explain the return format or structure of the comparison results. While it mentions 'egress identity and reachability', the output schema is absent, leaving ambiguity about what the tool returns.

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 both parameters. The description reinforces the interface_ip purpose (VPN interface) but adds no new syntactic or format details 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 compares egress identity and reachability between the default route and a specific interface IP, with explicit use case for split-tunnel surprises. It distinguishes well from sibling tools like net_diagnose or dns_leak_check.

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 mentions the prerequisite of network access and implies use for detecting split-tunnel issues. It does not explicitly state when not to use but provides context that aligns with the tool's name.

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 aligns with annotations (readOnlyHint, destructiveHint) and adds behavioral detail: it generates a keypair and prints config. No contradictions; provides useful context 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?

Two concise sentences that front-load purpose and add a key behavioral note. 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?

No output schema, but description adequately explains the tool outputs config and keys. Could explicitly list what is output, but for a straightforward generation tool, the description is sufficient.

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 the schema already describes parameters. Description does not add much beyond implying they are part of the client config. 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?

Description clearly states it generates a WireGuard keypair and client config. The verb 'generate' and resource 'WireGuard peer config' are specific, and the tool is distinct from sibling tools like wg_peer_add or wg_status.

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 it is read-only and does not modify any interface, clarifying when to use it. It could mention alternatives like wg_peer_add for actually adding a peer, but the 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?

Disclosures beyond annotations: mutating, dry-run unless confirm:true, requires --enable-write and privileges. No contradiction with annotations (destructiveHint=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?

Two concise sentences: first states action, second explains behavior. No superfluous words. Front-loaded with core purpose.

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 key behavioral aspects (dry-run, confirm, privileges) and all parameters are schematically documented. Missing expected output information, but no output schema exists. Minor gap.

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 each parameter. The tool description adds no additional parameter-level details beyond the schema, 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?

Specific verb 'add or update' with resource 'peer on a WireGuard interface' and explicit reference to `wg set`. Clearly distinguishes from siblings like wg_peer_remove and wg_status.

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?

States mutating nature, requirement for --enable-write, dry-run behavior, and privilege need. Provides explicit context for when to use, though no explicit alternatives or 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?

While annotations indicate destructiveHint:true, the description adds that it is mutating, requires --enable-write, and runs as a dry-run unless confirm:true. This goes 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?

Two sentences that are front-loaded with the purpose and include essential behavioral details, with 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 simple removal tool with 3 parameters and no output schema, the description covers purpose, mutating behavior, prerequisites, and dry-run safety completely.

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 only reiterates the confirm parameter's effect, adding minimal extra 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 title 'Remove WireGuard peer' and description 'Remove a peer from a WireGuard interface' clearly state the specific verb and resource, distinguishing it from siblings like wg_peer_add.

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 explains the mutating nature, the requirement for --enable-write, and the dry-run unless confirm:true. This gives clear context, though it does not explicitly name 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details beyond annotations, such as that it runs `wg show` and flags stale handshakes, which helps the agent understand the tool's side effects and output characteristics.

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 two sentences, front-loaded with the key action ('Reads WireGuard interfaces and peers'), and provides essential details without unnecessary words. 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?

Given the tool has no parameters and no output schema, the description covers the key return fields (handshake recency, endpoints, allowed-IPs, transfer) and flags stale handshakes. It is complete enough for a read-only status tool with simple output.

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 zero parameters, and schema description coverage is 100%. The description adds value by explaining the output data (handshake recency, endpoints, allowed-IPs, transfer), which goes beyond the empty schema. For a tool with no parameters, a baseline of 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 it reads WireGuard interfaces and peers via `wg show`, specifying fields like handshake recency, endpoints, allowed-IPs, and transfer. This distinguishes it from sibling tools like wg_peer_add or wg_peer_remove, which modify WireGuard configuration.

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 states 'Read-only' and 'Flags peers with stale handshakes,' indicating it is used for checking WireGuard status. While it does not explicitly state when not to use it or mention alternatives, the context of sibling tools (e.g., net_ping, net_diagnose) implies it is for WireGuard-specific status, not general network diagnostics.

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