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

The description discloses rate-limiting and no-API-key requirement, which are not present in the annotations. It also reiterates read-only behavior consistent with the readOnlyHint. This goes beyond the annotations to inform the agent of operational constraints.

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

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

The description is front-loaded with the action and key information, but it repeats the return fields (operator, prefixes, classification, abuse contact) twice. It is not overly verbose, but could be slightly more concise by removing the duplication.

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 one parameter and a clear output schema, the description provides all necessary context: what it returns, when to use it, and how it differs from related tools. It is complete without needing to explain nested objects or complex error 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 parameter 'query' is already well described in the schema with examples for IP and ASN formats. The description does not add additional semantic details about the parameter beyond what is already in the schema, so it meets the baseline for full schema coverage.

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

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

The description clearly states the tool's function: looking up ASN/BGP information for an IP or AS number, including operator, prefixes, abuse contact, and classification. It explicitly distinguishes itself from reverse_dns, making its purpose unambiguous among 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 provides explicit when-to-use guidance: 'Use this to identify who runs a network or whether an IP is cloud/CDN-hosted' and contrasts with reverse_dns for PTR lookups. It also mentions read-only nature and rate-limiting, which helps set expectations for usage.

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 notes the tool is read-only, requires no API key, is subject to rate limiting, and returns a text report with status, KPI summary, detected issues, and recommended actions. This aligns with the readOnlyHint and idempotentHint annotations and fully discloses the tool's behavior.

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

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

The description is concise yet information-dense, covering purpose, usage guidance, behavior, and output format in a few sentences. No redundant phrases or filler; each sentence contributes necessary details.

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

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

Given the output schema exists and the description already summarizes the return format (text report with status/KPI/issues/actions), the context is complete. The description adequately covers what an agent needs to decide when to invoke and what 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 single parameter 'domain' is described with format constraints (no scheme or trailing slash) and examples. Schema coverage is 100%, and the description adds practical guidance beyond the schema's basic type definition.

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 queries DNS records and validates email-related records, including DNSSEC and SPF/DMARC syntax, with severity-rated diagnostics. It explicitly distinguishes itself from dns_propagation and email_auth, making its purpose unambiguous.

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

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

It explicitly says to use this tool for a single authoritative answer about one domain and directs users to dns_propagation for cross-resolver comparisons and email_auth for full SPF/DKIM/DMARC deliverability. This gives clear when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnly/idempotent hints in annotations, the description discloses operational traits such as requiring no API key and being rate-limited, and states what it returns ('per-resolver values and a consistency verdict'). It does not mention edge cases like resolver timeouts, but the added behavioral context is useful.

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

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

The description is compact and front-loaded with the core behavior, followed by usage guidance and a sibling-tool contrast. No redundant or filler wording is present.

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 network diagnostic tool, the description covers the main purpose, usage, and return shape at a high level. The output schema is noted as present, and the description clarifies the key verdict concept. It could mention resolver count specifics or failure behavior, but it is sufficiently complete for an agent to select and call 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?

Both parameters are well described. 'domain' includes an example and format guidance; 'type' lists an enum, has a default, and explains why A is the default. Schema coverage is 100%, and the descriptions add meaningful detail beyond the raw 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?

States a specific action ('Query one DNS record across 8+ global public resolvers...') and resource ('DNS propagation check'). It clearly distinguishes itself from the sibling dns_lookup tool by noting the difference between multi-resolver propagation checks and single authoritative lookups.

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

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

Explicitly says when to use this tool ('Use this after changing a record to confirm worldwide propagation') and when to choose an alternative ('Use dns_lookup instead for a single authoritative answer...'). No ambiguity is left about the intended use case.

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

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

The description goes beyond the readOnlyHint and idempotentHint annotations by explaining that the tool performs DNS probes, blacklist checks, and returns a 0-100 score plus a text report. It also discloses the rate limit and the fact that no API key is required, giving an agent a clear picture of behavior and constraints.

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: it first states what the tool does and what it returns, then gives the primary use case, then explicitly names alternative tools, and finally lists operational constraints. No sentences are wasted and the structure makes it easy for an agent to scan.

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

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

For a tool with many checks (MX, SPF, DMARC, DKIM, BIMI, MTA-STS, TLS-RPT, DANE, blacklists), the description gives enough detail to set expectations without overwhelming. It specifies the output format (score, per-mechanism KPIs, issues, actions) and provides enough context for an agent to decide whether this tool is appropriate.

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

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

The schema covers the single required domain parameter, and the description adds meaningful clarification: it defines the expected input as the part after '@', provides an example, and notes that an IP address is accepted for reverse/PTR checks. This is more helpful than the schema alone, though it does not cover edge cases like punycode or trailing dots.

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

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

The description opens with the specific verb 'Assess' and identifies the exact resource: a domain's email authentication and deliverability posture. It clearly distinguishes this tool from dns_lookup and email_header_analysis by naming those alternatives and their narrower use cases.

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

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

It explicitly states when to use the tool ('for a full sending/receiving readiness review of a domain') and when not to, directing users to dns_lookup for raw records and email_header_analysis for a specific message. It also provides operational constraints: read-only, no API key required, and rate-limited.

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 additional behavioral details beyond the annotations, including that the tool is read-only, requires no API key, and is rate-limited. It also outlines the output format (text report) and input instructions, giving a transparent picture of what happens when invoked.

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 thorough but well-structured, front-loading the primary purpose and then providing usage context, alternative, and expected output. No redundant or irrelevant content; 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?

With only one parameter, the description covers all necessary context: function, input format, output details, usage scenario, alternative, and operational constraints (rate limit). It is complete for an agent to decide when and how to invoke the tool correctly.

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

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

The schema description provides extensive detail about the single parameter 'headers', including exactly what to include (first 'Received:'/'From:' line down to blank line), how to paste (verbatim, with folded continuation lines), and what to exclude (message body). The tool description also reiterates 'INPUT is the full raw header block', reinforcing the 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's function: parsing raw email headers to reconstruct delivery path, extract SPF/DKIM/DMARC results, measure per-hop delays, and flag non-TLS hops. It also distinguishes the use case from the sibling email_auth tool, making its purpose unambiguous.

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 specifies when to use this tool ('diagnose a specific message that was already delivered') and when to use the alternative email_auth ('assess a domain's sending configuration before sending'). This provides clear guidance 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description reinforces and extends this by stating 'Read-only (an HTTP GET-style probe that sends no payload)', adding detail beyond the annotations. No contradictions exist.

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

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

The description is compact and information-dense, covering functionality, alternatives, safety, and output in a few sentences without redundancy. It is well-structured and easy 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?

Given the output format is described ('text report: grade, header findings, redirect trace, issues, and actions'), the alternative tools are named, and the safety profile is clear, the description gives an agent all needed context to select and invoke the tool correctly.

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

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

The single 'url' parameter has a schema description that is 100% covered. The description adds meaningful behavior context: scheme defaulting to https and that redirects are followed, which goes beyond the schema and clarifies expected input handling.

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 audits HTTP security headers, follows redirect chains, grades A-F, and flags info leaks. It also explicitly distinguishes from sibling tools ssl_check and security_scan by explaining when each should be used.

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 guidance: 'Use this for HTTP-layer/header posture' and names alternatives (ssl_check for TLS, security_scan for full domain). It also notes read-only, no API key, and rate-limiting, giving clear practical 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?

Description aligns with annotations (readOnlyHint, idempotentHint, destructiveHint false) and adds useful behavioral context: takes no input, reflects egress IP, read-only, no API key required, rate-limited. No contradictions with annotations.

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

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

Description is compact, front-loaded with the primary purpose, and contains no redundant or filler wording. All sentences add 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?

Despite having no parameters, the description fully covers what the tool does, what data it returns, and its constraints. The listed return fields give enough context for an agent to decide whether this tool fits the task.

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?

Tool has zero parameters and the schema reflects this. Description explicitly reinforces 'Takes no input', leaving no ambiguity about invocation requirements.

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 identifies the resource (caller's own public IP as seen by server) and the action (report), and enumerates the data returned (IPv4/IPv6, ISP, ASN, geolocation, proxy/VPN heuristics). It also distinguishes itself from related sibling tools by noting asn_lookup/reverse_dns are for specific IPs.

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 this tool (discover server outbound IP or test connectivity) and when to use alternatives (specific known IP -> asn_lookup or reverse_dns). This is clear usage guidance.

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

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

The description clearly states behavioral characteristics: it is read-only, returns counts and registered variants with the technique, and warns that a registered variant is not proof of abuse. This aligns with the annotations (readOnlyHint: true, destructiveHint: false) and provides additional clarification about limitations.

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?

While the description is relatively long, every sentence contributes essential information, including purpose, techniques, output, and constraints. It is well-structured in a single paragraph without redundancy, making it appropriately concise for the tool's complexity.

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

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

The description covers all necessary context: what the tool does, its output (counts and registered variants with technique), operational details (read-only, no API key, rate-limited), and follow-up actions (whois_lookup for ownership and registration date). It also explicitly addresses a common misconception about registered variants, making it highly 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?

The single parameter 'domain' is thoroughly described in the schema: it specifies the format (without scheme or path) and explains that variants of its label and TLD are generated. Schema coverage is 100%, and the description adds meaningful context about how the parameter is used.

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 clear purpose: generate typosquat/lookalike variants and check which are registered. It explicitly names the resource (domain), the scope (variants of label and TLD), and the use case (assessing brand-impersonation and phishing exposure).

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

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

It provides explicit usage guidance: 'Use this to assess brand-impersonation and phishing exposure for a domain the user is responsible for.' It also notes the tool is read-only, requires no API key, is rate-limited, and recommends follow-up with whois_lookup, giving clear context for when and how to use it.

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 openly discloses that the tool makes an ACTIVE TCP connection, is non-intrusive, and that the connection is visible in target logs. This aligns with and expands on the annotations (readOnlyHint, idempotentHint, destructiveHint false) 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 clear and well-structured but repeats the 'connect probe only' and authorization guidance multiple times. Slight redundancy, though it does not harm usability.

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 presence of an input schema, sibling tools, and usage notes, the description provides all necessary information for an agent to decide to invoke the tool and understand its effects. The output is described sufficiently for a list of open ports.

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 host parameter is fully described with examples, an accepted 'host:port' variant, and an authorization warning. Schema coverage is 100%, and the description adds practical usage 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 action ('Probe a host for a fixed set of common TCP ports'), the scope ('fixed set'), and the output ('report which are open, the service name, and the response time'). It also distinguishes itself by naming sibling tools for specific service configuration checks, making its purpose unique.

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 tells when to use the tool ('Use this to confirm which services are exposed') and when not to use it ('Use ssl_check or http_security instead to assess a specific service's configuration'). This gives clear selection criteria.

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 behavior beyond annotations: FCrDNS verification, provider inference, return values, and rate limit. Matches readOnlyHint and idempotentHint.

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, front-loaded with main action, then usage guidance and alternative. 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?

Complete for single-param tool: covers input, output, use cases, alternatives, and constraints. Nothing missing.

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 documents ip with full description (IPv4/IPv6, examples, must be IP not hostname). Tool description adds no new parameter details beyond restating it is an IP address.

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 resolves PTR records, verifies FCrDNS, and infers hosting provider, and distinguishes from asn_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 tells when to use (validate mail-server rDNS, identify single IP's host) and when to use alternative (asn_lookup for network/BGP ownership), plus notes read-only, no API key, rate-limited.

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 explicitly discloses the active port scan behavior, the authorization requirement, the read-only nature of the rest of the checks, and the rate-limiting. This goes well beyond the annotations and gives users a clear understanding of what the tool does and any risks involved.

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 dense but well-structured, using a colon-separated summary, a usage sentence, and a behavior warning. Every sentence adds necessary information with no fluff or redundancy, making it long but appropriately scannable.

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 output schema is present and the description names the key return components (score, per-area breakdown, top actions, summaries), there is enough context for an agent to call the tool correctly. The warning about authorization and the distinction from single-purpose tools round out the context.

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

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

The single 'domain' parameter is fully described with an example, clarification that schemes and paths are stripped, and a note that the host is also port-scanned. Schema description coverage is 100%, and the description adds important operational context not present in 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 performs a one-shot comprehensive security audit of a domain, listing all checks (DNS, SSL, HTTP headers, email auth, port scan, etc.) and the outputs (Health Score, grade, action list). It also explicitly positions it as the default tool for domain health/security questions.

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 guidance on when to use this tool versus sibling tools, stating it is the default starting point and directing users to individual tools like ssl_check and email_auth when depth in one area is needed. It also includes an authorization warning for the active port scan.

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

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

The description goes beyond the annotations by detailing that it 'completes a TLS handshake but sends no application data,' requires no API key, and is rate-limited. This aligns with the readOnlyHint and destructiveHint, with 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 dense but every clause earns its place: purpose, output details, usage guidance, alternatives, and behavioral notes are all included without redundancy. It is well-structured and easy 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?

Given the tool's moderate complexity, the description covers input, output format, usage context, alternatives, and operational constraints. An agent has enough context to invoke the tool correctly without needing external details.

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 tool description itself does not add parameter-specific guidance beyond what the input schema already provides. The schema descriptions for host and port are thorough, so the baseline of 3 applies because the description adds no extra parameter semantics.

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

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

The description opens with a specific action—'Inspect a host's served TLS/SSL certificate and connection'—and enumerates the exact outputs (expiry, issuer, SAN, chain, TLS version, HSTS, and grade). It clearly differentiates from sibling tools by naming http_security and security_scan as alternatives.

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

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

It explicitly states when to use this tool: 'diagnose certificate or HTTPS-handshake problems for one host.' It also gives direct alternative tools for other needs, making the selection criteria unambiguous.

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

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

The description goes beyond the annotations by disclosing that it is 'fully passive (no packets are sent to the target)' and that CT logs are public records. It also explains the flagging behavior for operational-looking names and wildcard certificates, plus mentions rate-limiting and read-only nature. This richly informs the agent of the tool's runtime 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 moderately long but every sentence serves a purpose: it states the core action, explains the passive method, describes output flags, gives usage context, points to alternatives, and lists return values. It is well-structured and front-loaded with the primary purpose, so it remains concise despite the detail.

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 recon tool with one parameter, the description is complete: it covers input format, method, output contents, relationship to sibling tools, safety characteristics, and rate-limiting. There is no missing context that an agent would need to decide to call or interpret the results of this 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 schema description covers 100% of the parameters, and the description adds extra semantic detail: the domain must be a 'registrable domain' without scheme or path, with an example ('example.com'). It also clarifies that subdomains found in CT logs for that domain are returned, so the parameter meaning is fully clear.

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 a specific verb and resource: 'Enumerate the subdomains of a domain from Certificate Transparency logs.' It also distinguishes itself from sibling tools by mentioning the passive CT-log method and by referencing dns_lookup and lookalike_domains as complementary next steps.

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 is provided: 'Use this as the first recon step to map a domain's attack surface' and when to use alternatives: 'Use dns_lookup to check whether a discovered name still resolves, or lookalike_domains for typosquat variants.' This leaves no ambiguity about when to choose this tool.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important behavioral traits: no network call, no DNS query, no API key, no rate limiting, and special handling of /31 and /32 per RFC 3021. This goes well beyond the annotation metadata.

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

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

The description is compact and well-structured, with no fluff. Every sentence adds value: purpose, output, use case, computational nature, and edge-case handling. It fits within a few lines and is easily scannable.

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 simple input schema and the presence of an output schema (as indicated), the description fully covers what an agent needs: it enumerates the returned fields (network, broadcast, usable range, total hosts, subnet mask, wildcard mask) and notes the RFC 3021 exception. No additional context is necessary.

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

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

The schema description covers 100% of the single parameter, and the description adds critical semantics: 'IPv4 only' and 'host bits may be any address inside the block.' This clarifies the expected input format beyond the schema alone.

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 ('Compute') and identifies the resource ('IPv4 subnet details'), clearly distinguishing it from sibling network diagnostic tools like port_scan or dns_lookup. It also states the output fields, making the purpose unambiguous.

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

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

It explicitly says 'Use this for IPv4 address planning' and highlights that it is purely computational with no network calls, no API key, and no rate limits. This gives clear when-to-use guidance and indirectly contrasts with the network-bound siblings.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses extra behavioral traits: RDAP with WHOIS fallback, read-only nature, no API key required, and rate-limiting. This enriches the agent's understanding of what to expect.

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

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

The description is compact and information-dense, with no redundant phrases. Each sentence serves a distinct purpose: what it returns, when to use it, and additional constraints.

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 output schema exists, the description appropriately refrains from detailing return structure but still mentions the key output categories (registrar, key dates, nameservers, status flags). It covers all necessary context for correct 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?

The single parameter 'domain' is fully described with an example and the normalization behavior ('A subdomain is normalized to its registrable domain'). Schema coverage is 100%, and the description adds valuable detail 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 uses a specific verb ('Retrieve') and a precise resource ('domain registration data'), and explicitly distinguishes from sibling tools like dns_lookup and reverse_dns/asn_lookup. This makes the tool's purpose unmistakable.

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

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

It provides explicit when-to-use guidance ('Use this for ownership, lifecycle, and expiry questions') and when-not-to ('Use dns_lookup instead for live DNS records'). This removes any ambiguity about selection.

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