Dechonet-MCP

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description's 'Read-only' is redundant but harmless. It adds meaningful extra behavioral context: 'requires no API key; rate-limited.' This helps the agent anticipate authentication needs and possible throttling.

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

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

The description is well-structured and front-loaded, opening with the operation and expected output before usage guidance and constraints. One minor inefficiency is that the final sentence repeats the return values already listed in the first sentence, but this is a small redundancy.

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

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

The tool has only one input parameter, a high-coverage schema, an output schema, and annotations covering safety and idempotency. The description adds the remaining necessary context: use cases, an explicit alternative, authentication requirements, and rate limits. Nothing essential is 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 description coverage is 100% and the query parameter already includes examples and allowed forms ('1.1.1.1' or 'AS13335'). The description adds no new parameter-level details, so the schema carries the semantic burden. Baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Look up') and names the resource (Autonomous System / BGP information for an IP or AS number), plus the concrete data returned: operator, prefixes, abuse contact, and classification. It also names reverse_dns as a distinct sibling, making the tool's purpose easy to differentiate.

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

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

The description gives explicit when-to-use context ('identify who runs a network or whether an IP is cloud/CDN-hosted') and names the alternative tool with the condition for using it ('Use reverse_dns instead for the host-level PTR name of a single IP'). This is clear routing guidance for an agent.

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

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

Annotations already declare readOnlyHint, but the description adds meaningful behavioral context: no API key or authentication required, subject to rate limiting, and returns a text report with status, KPI summary, detected issues, and recommended actions. This goes well beyond the structured annotations.

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

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

Every sentence earns its place: the tool's purpose, record types, output format, alternatives, access requirements, and rate-limit caveat are all covered without redundancy. The most critical usage distinction (single authoritative answer) is front-loaded.

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

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

Given the tool's single parameter, an output schema, and rich annotations, the description covers all necessary context: what the tool does, when to use it, which sibling to choose instead, authentication requirements, output shape, and a caveat. Nothing essential is 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 description coverage is 100%, so the schema fully documents the single 'domain' parameter. The description reinforces the domain concept but adds no new parameter-level syntax or formatting details beyond what the schema already provides.

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

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

The description names the specific verb ('Query'), the resource ('DNS records'), and the domain scope ('for a domain'), and specifies record types and diagnostic outputs. It also explicitly contrasts itself with sibling tools like dns_propagation and email_auth, making its unique role clear.

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

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

The description gives explicit when-to-use guidance ('single authoritative answer about one domain') and names specific alternatives with the conditions that select them: dns_propagation for multi-resolver comparison and email_auth for full deliverability assessment. No inference is required.

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 readOnly and idempotent behavior, and the description reinforces this without contradiction. It adds valuable behavioral context beyond annotations: 'requires no API key', 'rate-limited', and the returned shape ('per-resolver values and a consistency verdict'). This goes beyond the 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 appropriately sized with every sentence contributing: purpose, usage, alternative, constraints, and return summary. It is front-loaded with the core action and outcome, and the guidance about dns_lookup is placed clearly without excess verbiage.

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 two-parameter, read-only tool with an output schema and comprehensive annotations, the description is complete. It covers use case, alternative routing, rate limiting, authentication requirements, and return verdicts, so an agent has everything needed to invoke it 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?

Input schema coverage is 100%, so the schema already fully documents both parameters. The description adds general context about comparing records but does not add meaning beyond what the schema provides. This is the correct 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 uses a specific verb ('Query') with a clear resource ('one DNS record across 8+ global public resolvers') and a concrete outcome ('report which resolvers return stale versus updated values'). It clearly differentiates from the sibling dns_lookup tool by focusing on multi-resolver propagation rather than a single authoritative answer.

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

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

The description explicitly states when to use it ('after changing a record to confirm worldwide propagation') and names the alternative tool with the condition for choosing it ('Use dns_lookup instead for a single authoritative answer with SPF/DMARC validation'). This leaves no ambiguity about 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 mark it read-only and idempotent, and the description adds meaningful behavior: rate-limited, no API key required, probes 15 DKIM selectors, checks blacklists across all MX hosts, and returns a text report with score/KPIs/issues/actions. No contradiction with annotations.

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

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

The description is dense but well-organized: mechanism list first, then use cases, then constraints and return format. Every sentence earns its place, and the most decision-relevant info is front-loaded.

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

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

With only one parameter, output schema present, and annotations covering safety, the description provides everything needed: tool scope, alternatives, rate-limit caveat, authentication requirements, and return content. Nothing important is 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 coverage is 100%, so the baseline is 3. The description adds value by clarifying domain means the part after '@' and explicitly stating an IP address is accepted for reverse/PTR checks — extra semantics 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 names a specific action ('Assess a domain's email authentication...'), lists the exact mechanisms checked, and returns a clear 0-100 deliverability score. It also distinguishes itself from dns_lookup and email_header_analysis, so an agent can confidently select it.

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 ('full sending/receiving readiness review') and names alternatives with conditions: use dns_lookup for raw records and email_header_analysis for a specific sent message. This is model guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds beyond that by noting 'requires no API key; rate-limited' and specifying that the output is a text report rather than a structured JSON object. This enriches the behavioral picture without contradicting annotations.

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

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

Four sentences, each with a distinct job: core function, intended use case, sibling differentiation, and input/output contract. The description is front-loaded and avoids redundancy, though it is slightly longer than the minimal two-sentence ideal; no sentence feels wasted.

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 required parameter, an output schema present, and detailed annotations, the description covers all needed context: input format, output format, intended use, alternative tool, and operational constraints. Nothing an agent needs to select and invoke this tool correctly is 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 description coverage is 100%: the input schema already explains exactly what 'headers' should contain, how to copy it, and what to exclude. The description only restates 'INPUT is the full raw header block,' adding no new parameter semantics beyond the schema. Baseline 3 is appropriate given the 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 states a specific verb and resource: 'Parse raw email headers to reconstruct the delivery path... extract SPF/DKIM/DMARC... measure per-hop delays, and flag unencrypted hops.' It clearly enumerates the tool's outputs and distinguishes it from the sibling email_auth by specifying a different diagnostic use case.

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

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

Explicitly states when to use the tool: 'diagnose a specific message that was already delivered — spoofing, delays, or where mail was lost.' It also names the alternative: 'Use email_auth instead to assess a domain's sending configuration before sending,' and adds operational guidance about being read-only, keyless, 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds valuable context beyond those: the probe follows redirects, sends no payload, requires no API key, is rate-limited, and returns a specific text report structure. No contradiction with annotations exists.

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

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

The description is efficiently structured: primary action and output type first, sibling routing second, safety/behavioral notes third, and return format last. Every sentence carries functional information with 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?

For a one-parameter read-only tool with an output schema, the description covers all essential context: redirect-chain behavior, grading scope, leak detection, rate limiting, auth requirements, and the response format. Nothing an agent needs to select or invoke this tool correctly is 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 description coverage is 100%, so the schema already fully documents the url parameter, including scheme handling and redirect behavior. The description adds no parameter-specific meaning beyond what the schema provides, so the high-coverage 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 uses a specific verb phrase—'Follow a URL's HTTP redirect chain and audit response security headers'—and names the exact resources: CSP, HSTS, X-Frame-Options, COOP, CORP, COEP, Permissions-Policy. It also clarifies the grading output and information-leak detection, making the tool's purpose unmistakable and distinct 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?

It explicitly states when to use this tool: 'Use this for HTTP-layer/header posture.' It then names two sibling alternatives and their conditions: 'Use ssl_check instead for certificate or TLS-handshake issues, or security_scan for a full domain report.' This gives clear when/when-not guidance.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds critical context: the tool reflects the MCP server's egress IP 'which is usually NOT the end user's IP,' preventing a natural misconception. It also discloses that no API key is required and that the tool is rate-limited.

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, each earning its place: what the tool returns, the critical egress-IP caveat, and when to use alternatives. Information is front-loaded with the main purpose first, followed by usage and differentiators.

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 zero-parameter read-only tool with a rich output schema and clear annotations, the description covers every aspect an agent needs: purpose, data returned, caveat, usage, alternatives, auth requirements, and rate limiting. Nothing essential is 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?

With zero parameters, the baseline is 4, and the description clears any doubt by explicitly stating 'Takes no input.' It further explains what 'no input' means operationally — the result is the server's egress IP — adding meaning beyond the empty 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 states a specific verb and resource: 'Report information about the caller's own public IP as seen by the server,' and goes on to enumerate the exact data returned (IPv4/IPv6, ISP, ASN, geolocation, proxy/VPN heuristics). It also differentiates from siblings by explicitly directing users to asn_lookup or reverse_dns 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?

The description provides explicit when-to-use guidance: 'Use this to discover the server's outbound IP or test connectivity.' It also names alternatives ('To inspect a specific, known IP instead, use asn_lookup or reverse_dns'), leaving no ambiguity about 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 mark the tool as readOnly, openWorld, idempotent, and non-destructive, and the description adds real behavioral context: rate-limiting, no API key required, live NS delegation via DoH, and the important caveat that a registered variant is not proof of abuse. This goes well beyond the structured annotations.

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

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

The description is dense but every clause carries critical information: technique enumeration, the live-check method, intended use case, a caveat, follow-up instruction, constraints, and return summary. The core action is front-loaded, and no filler 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?

Given the single parameter, high schema coverage, rich annotations, and an output schema, the description fully covers what the tool does, how to interpret results, and what to do next. Nothing an agent needs to invoke it correctly is 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 coverage is 100% and the parameter description already explains format and constraints. The tool description adds useful meaning by specifying that variants of both the label and TLD are generated, clarifying what the single 'domain' parameter actually drives.

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 ('Generate') and resource ('domain'), listing concrete variant types (homoglyph swaps, TLD swaps, omissions, transpositions, repetitions, hyphenations) and the registration check. It uniquely distinguishes this tool from all listed siblings, which are generic DNS/network or WHOIS utilities.

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

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

The description explicitly says to use this for assessing brand-impersonation and phishing exposure, and gives a concrete follow-up step with whois_lookup. It lacks an explicit when-not-to-use statement or named alternatives among siblings, but the context is clear and actionable.

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

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

Even though annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable behavioral context: it makes an ACTIVE TCP connection, it is non-intrusive and connect-only, it does not authenticate or transfer data, and it is visible in target logs. It also discloses rate-limiting and the lack of an API key requirement. This goes well beyond the annotations and contains no contradiction.

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

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

The description is front-loaded with purpose, then uses a labeled BEHAVIOR section, then alternatives, and then constraints. Every sentence adds information: what the probe does, what it does not do, visibility in logs, authorization, alternatives, rate limit, and return value. There is no filler or tautology.

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, return values do not need explanation. The description covers the tool's network behavior, safety profile, authorization boundaries, rate limits, API key requirements, and sibling tool routing. For a single-parameter tool with rich annotations and output schema, nothing significant is 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?

The input schema already covers the only parameter (host) with a full description including accepted forms and authorization guidance, so schema coverage is 100%. The tool description does not add additional parameter-level meaning beyond the schema; it explains tool-level behavior but not new host semantics. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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

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

The description uses a specific verb ('Probe') with a clear resource ('a host for a fixed set of common TCP ports') and states the exact output: which ports are open, service name, and response time. It also distinguishes itself from sibling tools by naming ssl_check and http_security as alternatives for assessing service configuration, so an agent can tell them apart.

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

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

The description explicitly says when to use this tool ('Use this to confirm which services are exposed') and names specific alternatives for different use cases ('Use ssl_check or http_security instead to assess a specific service's configuration'). It also states the authorization requirement, leaving no ambiguity about appropriate invocation.

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, the description adds rate limiting, API-key requirements, the heuristic provider inference, and the exact return contents (PTR hostname, FCrDNS pass/fail, provider guess). This gives the agent behavioral context that annotations alone do not establish.

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?

Every sentence earns its place: purpose, verification, provider inference, use cases, alternative tool, and operational constraints (read-only, no API key, rate-limited). The structure is front-loaded with the core action and flows logically to outcomes.

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

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

For a single-parameter read-only tool with an output schema, the description covers purpose, use cases, alternatives, constraints, auth, rate limiting, and return values. Nothing an agent needs to select or invoke this tool correctly is 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 coverage is 100%, so the parameter description already fully documents the 'ip' parameter, including IPv4/IPv6 examples and the disallowance of hostnames. The tool description does not add any semantic detail 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?

The description states a specific verb and resource: 'Resolve the PTR (reverse DNS) record for an IPv4 or IPv6 address' and adds the clarifying FCrDNS verification. It distinguishes itself from asn_lookup explicitly by routing network/BGP ownership queries away, leaving no ambiguity about its scope.

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

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

The description gives clear usage context: 'validate mail-server rDNS or identify a single IP's host' and explicitly names an alternative for a different use case ('Use asn_lookup instead for network/BGP ownership of the IP'). It stops short of contrasting with the closely related dns_lookup sibling, so it is clear but not exhaustive in 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 discloses behavioral traits beyond the annotations: it performs an ACTIVE port scan, is otherwise read-only, requires no API key, is rate-limited, and makes multiple backend calls. This is especially valuable because annotations alone do not reveal the active scanning 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 dense but every sentence contributes: purpose, output, usage guidance, behavioral warning, and return summary. The BEHAVIOR section is clearly marked and front-loaded enough, though the length is slightly above minimal and could be tightened.

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

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

Given the tool's complexity, the description covers when to use it, safety/authorization requirements, rate limiting, authentication, and the types of results returned. An output schema exists, so the description does not need to detail return fields, and the provided coverage is complete for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100% and the schema already documents the domain parameter with examples and the port-scan warning. The description adds context about the overall scan but does not meaningfully expand on parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('runs') and a clear resource (domain), listing exactly which checks are performed (DNS, SSL, HTTP headers, email auth, port scan, etc.) and what output is produced (Health Score, grade, action list). It clearly distinguishes this comprehensive tool from the individual sibling tools by naming examples like ssl_check and email_auth.

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 ('default starting point for is this domain healthy/secure?') and when to use alternatives ('Call the individual tools ... when you need depth on one area'). It also includes an authorization caveat, making the usage boundaries clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces this by stating it 'completes a TLS handshake but sends no application data.' It adds useful behavioral context not in annotations: no API key required and rate-limited. It also discloses the grading weights, giving the agent insight into how the result is produced.

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 sentence serves a purpose: core behavior, output, usage context, alternatives, safety profile, and return format. Key details are front-loaded, and the sibling routing comes after the main purpose. 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?

For a read-only single-host diagnostic tool with an output schema already present, the description covers all necessary context: what it inspects, what it returns, when to use it, what alternatives exist, safety behavior, authentication requirement, and rate limiting. There are no meaningful gaps for an agent selecting or invoking 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?

Schema description coverage is 100%, so the input schema fully documents both host and port, including the default port and URL-host acceptance. The description adds no new parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

Description opens with a specific verb and resource: 'Inspect a host's served TLS/SSL certificate and connection,' then lists concrete outputs such as expiry date, issuer, SAN list, chain integrity, TLS version, and HSTS. It also distinguishes itself from siblings by naming http_security and security_scan, making selection 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?

Explicitly states when to use the tool: 'Use this to diagnose certificate or HTTPS-handshake problems for one host.' It also names alternatives and the conditions that select them: http_security for response security headers and security_scan for an all-in-one domain report. This is strong routing 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 annotations, it discloses several operationally important traits: no packets sent to the target, no API key required, rate-limiting, the flagging of risky names and wildcard certs, and the exact return contents. All of this is consistent with readOnlyHint=true, idempotentHint=true, and destructiveHint=false — no contradiction.

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

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

Seven sentences, zero filler, and each sentence carries distinct value: mechanism, passivity guarantee, flagging behavior, when to use, alternatives, constraints, and output contract. The ordering flows logically from what → how → when → alternatives → limits → returns.

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

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

For a single-parameter tool with a fully documented schema, safety annotations, and an output schema, the description covers everything an agent needs before calling: rate limits, no-auth requirement, passivity, and what comes back. Nothing material is 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 coverage is 100% and the schema already explains 'without scheme or path' with an example. The description echoes the registrable-domain concept but adds no new format or syntax guidance beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource+source: 'Enumerate the subdomains of a domain from Certificate Transparency logs.' It adds distinct behavioral markers (fully passive, flags risky operational names, wildcard certificates) that clearly differentiate it from all 14 siblings, especially dns_lookup and whois_lookup.

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

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

Explicitly states when to use it ('Use this as the first recon step to map a domain's attack surface') and names two alternatives with the exact condition that selects each one: dns_lookup to check whether a discovered name still resolves, and lookalike_domains for typosquat variants. Nothing is left to inference.

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 annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds substantial behavioral context: no network call, no API key required, no rate limiting, in-process computation, RFC 3021 handling for /31 and /32, and text-format return. This goes well beyond the structured annotations.

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

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

Three dense sentences cover behavior, outputs, special cases, constraints, and use case without redundancy. The most important distinction (local, no network call) is front-loaded.

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

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

Given the output schema exists, the description does not need to detail return values, and it covers all essential operational context: local computation, authentication/rate-limit status, RFC handling, and intended usage. Nothing critical is missing for calling this 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 input schema has 100% coverage and already explains the cidr parameter with format and example. The description reinforces that the tool computes from CIDR notation but adds little new parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Compute') with a clear resource ('IPv4 subnet details from CIDR notation') and enumerates the exact outputs. It also distinguishes itself from sibling network tools by emphasizing it is entirely local and purely computational.

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

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

The description gives an explicit use case ('Use this for IPv4 address planning') and states what the tool does not do ('It does not query DNS or contact any host'), which implies when not to use it. It doesn't reference a specific sibling alternative, but the local-computation framing is clear enough for an agent to route correctly.

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, but the description adds valuable behavioral context: it is rate-limited, requires no API key, uses RDAP with WHATIS fallback, and returns specific fields. This goes beyond what the annotations express and helps the agent anticipate operational constraints. No contradiction with annotations exists.

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 core purpose, followed by usage guidance and constraints, making it easy to scan. However, the final sentence 'Returns registrar, key dates, nameservers, and status flags' largely repeats the data points already listed in the first sentence. This minor redundancy prevents a perfect score.

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 one required parameter, an output schema, and annotations covering its safety profile, the description is complete. It covers purpose, usage alternatives, authorization requirements, rate limiting, and output highlights. No important operational information is 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?

The input schema covers 100% of the single parameter's meaning, including the subdomain normalization detail. The description does not add additional parameter semantics beyond what the schema already provides. Per the rubric, a baseline of 3 is appropriate when schema coverage is high.

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 verb and resource: 'Retrieve domain registration data via RDAP (with WHOIS fallback)' and enumerates concrete outputs such as registrar, key dates, nameservers, and EPP status flags. It also highlights risk states like clientHold and pendingDelete, which makes the tool's purpose unambiguous. The availability of a WHOIS fallback further clarifies behavior and distinguishes it from a plain RDAP 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?

Explicit guidance is provided: 'Use this for ownership, lifecycle, and expiry questions about a registered domain.' It also names alternatives with conditions: use dns_lookup for live DNS records and reverse_dns/asn_lookup for IP-level ownership. This leaves no doubt about when to choose this tool over its siblings.

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