Domain Health

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds substantive context beyond that: data provenance (RDAP registry, no scraping), the extra live-zone nameserver comparison and DNSSEC check, and graceful degradation when a ccTLD lacks RDAP. It stops short of rate-limit or error semantics.

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 sentences, front-loaded with the core action and data source, and each following sentence contributes a distinct fact (extra checks, subdomain rule, ccTLD limitation). Slightly dense with enumerations, but no filler.

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

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

There is no output schema, so the description carries the burden of describing results – and it does, listing the registry fields, status locks, danger states, nameservers and the DNSSEC/zone comparison. Combined with the annotations, an agent has everything needed to call it and interpret the response.

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 both parameters – including the URL/email normalisation of 'domain' and the summary/full enum – are already fully documented. The description adds no parameter-level meaning beyond the schema, which is the expected baseline 3.

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 verb and resource (read a domain's public registration record) and pins the mechanism (RDAP, not WHOIS scraping). It enumerates the exact fields returned – registrar, creation, expiry, status locks, danger states, nameservers – so an agent can distinguish it from check_email_auth, check_ssl and check_security_headers without opening a schema.

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?

Usage context is implied by the 'check' framing and it clarifies edge behaviour (subdomains are resolved to their registered domain; ccTLDs without RDAP are reported). However, it never states when to prefer this over the sibling full_domain_report, which likely subsumes it, and gives no exclusions or prerequisites.

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, destructiveHint=false and openWorldHint, so safety is covered structurally. The description still adds real behavior: 'Reads public DNS only' (no auth, no mutation), SPF includes expanded and counted against the 10-lookup limit, and 'about 40 common selectors' checked in addition to user-supplied ones. It does not discuss rate limits or failure modes.

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

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

Front-loaded with the plain-language outcome, then the check list, then the output shape and the read-only constraint. Dense and mostly non-redundant, though the middle sentence is a long list that could be tightened slightly.

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

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

With no output schema, the description carries the return-shape burden and does so: every finding includes a severity, a one-sentence fix and the RFC/provider document behind it, and detail controls whether passing checks appear. Combined with 'reads public DNS only', an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so domain and dkim_selectors semantics (including URL/email inputs) and the detail enum are already fully documented in the schema, anchoring the baseline at 3. The description only marginally reinforces this by noting the ~40 always-checked selectors and that findings are filtered in summary mode.

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 verb (check/explain) and a tightly scoped resource (email authentication for a domain), then enumerates the exact record families inspected (MX, SPF, DMARC, DKIM, BIMI, MTA-STS, TLS-RPT, bulk-sender rules). That enumeration makes it unmistakable next to check_ssl, check_security_headers and check_domain_registration.

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?

There is no when-to-use guidance and no reference to alternatives, even though the sibling set includes full_domain_report, which plausibly overlaps. The reader gets rich description of what is checked but nothing about when this tool is the right choice or when a sibling is better.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the retrieval method ('as a browser receives them') and a concrete scope limit (only public web servers on ports 80 and 443). It does not mention rate limits or failure behavior, keeping it short of a 5.

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

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

Two sentences, front-loaded with the action and the full list of checks, followed by a tightly scoped constraint. The header enumeration is long but each item is substantive rather than filler.

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

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

With no output schema, the description must imply what comes back; saying it will 'grade each' header conveys that findings/grades are returned. Combined with the detail enum documented in the schema, an agent has enough to call it correctly, though the exact response shape remains unstated.

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%, including the enum meaning for 'detail' and the flexible 'domain' input format, so the schema does the heavy lifting. The description adds no parameter-level guidance beyond that, making the baseline 3 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 names a specific verb ('Read') and resource ('HTTP security headers a domain's homepage sends') and enumerates exactly which headers are graded, so an agent knows precisely what this returns. It stops short of explicitly contrasting itself with siblings like check_ssl or full_domain_report, though the topic makes the boundary reasonably inferrable.

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?

Usage context is implied by the enumeration of checked headers and the scope note that 'Only public web servers on ports 80 and 443 are contacted,' which tells the agent when the tool is applicable. However, it never states when to prefer this over check_ssl or full_domain_report, nor any prerequisites or exclusions.

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

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

Annotations already declare readOnly/idempotent/openWorld and no destructive behavior, so the safety profile is covered. The description adds useful context beyond that: it checks port 443, auto-checks www for bare domains, and returns findings each with severity, fix, and citation.

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

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

Front-loaded with the core action and a compact enumeration of checks; the two trailing sentences about www handling and finding structure earn their place. The middle sentence is dense but not padded.

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

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

With no output schema, the description compensates by describing the return shape (severity, fix, citation) and the www side-effect. Combined with a fully described input schema, an agent has everything needed to call and interpret 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 coverage is 100%, so the schema already documents domain, detail, and include_www with defaults. The description only lightly reinforces include_www behavior ('Checks www as well when given a bare domain') and adds no syntax not already in the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Check the HTTPS certificate and TLS setup of a domain on port 443') and enumerates exactly what is inspected, which cleanly separates it from check_domain_registration, check_email_auth, and check_security_headers.

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?

Usage is implied by the enumerated scope (certificate/TLS checks for one domain), but there is no explicit when-to-use guidance and no mention of the sibling full_domain_report, which likely overlaps. Nothing is misleading, but the agent gets no routing help.

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, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: an explicit 5-20 second latency budget and a concrete picture of the return shape (score/grade per area, top fixes, findings with severity/fix/citation). It does not mention rate limits or failure modes, keeping it short of a 5.

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

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

Two dense sentences, front-loaded with the verb and scope; the second sentence carries returns and latency. Nothing is wasted, though the opening sentence is long enough that its clauses could be split for faster scanning.

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

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

With no output schema, the description carries the burden of describing returns, and it does so reasonably (per-area score/grade, top fixes, findings with severity, fix and citation). Combined with 100% schema coverage on inputs and complete safety annotations, an agent has enough to invoke and interpret it; only pagination/result-size limits are unaddressed.

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 domain, detail (with enum) and dkim_selectors are all fully documented in the schema itself, including the 's= value' example. The description adds no syntax or format detail beyond that (and never mentions detail or dkim_selectors), so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Run every Domain Health check on one domain at once') and enumerates the covered areas (email authentication, SSL/TLS, security headers, registration, DNSSEC). The 'at once' framing and the enumeration together distinguish it from the four per-area sibling tools without opening any schema.

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 makes the aggregation use case clear ('Run every ... check ... at once'), which implicitly routes the agent here instead of calling check_email_auth, check_ssl, etc. individually. However, it never names those siblings or states a when-not condition (e.g. 'use check_ssl for a single fast SSL check'), so selection still requires inference.

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