Domain Intelligence

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

Annotations already declare readOnlyHint, openWorldHint and idempotentHint, so the safety profile is covered. The description adds one real behavioral detail — that lookups are 'resolved in parallel' — but says nothing about failure modes (NXDOMAIN/timeouts) or rate limits.

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?

A single front-loaded sentence with no filler; the record-type enumeration is the informative payload and it carries its weight.

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?

Because an output schema exists, return values need not be described, and annotations cover the safety profile. What remains thin is edge-case behavior (missing domains, partial resolution), which keeps it from being fully complete.

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

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

Schema description coverage is 0% for the single 'domain' parameter, but the description's phrase 'for a domain' at least implies the parameter's meaning and the record types it returns. It adds no format guidance (apex vs subdomain, trailing dot, etc.), so it only partially compensates.

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?

Clear verb+resource: fetches DNS records for a domain, and it enumerates the record types returned (A, AAAA, MX, TXT, NS, CAA, SOA), which is genuinely specific. It does not, however, distinguish itself from siblings like domain_lookup or email_security, which likely overlap in purpose.

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

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

There is no when-to-use guidance, no mention of alternatives such as domain_lookup, and no stated preconditions. The agent must infer from the sibling list which tool fits a given DNS task.

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, it discloses non-obvious behavior: per-section failure isolation (a failed section returns an object with an `error` field while the rest is unaffected), the latency tradeoff of wait=true (~20 s), and subdomain ordering (live hosts with IPs first). These are exactly the runtime traits annotations don't capture.

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 tight sentences, front-loaded with the full report scope, then usage, then failure behavior and the wait tradeoff. No filler and nothing buried.

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?

An output schema exists, so return structure needn't be described, and the description still adds the error-field convention and the wait latency bound. For a read-only aggregate lookup, everything an agent needs to select and call it correctly is present.

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 0%, so the description must carry parameter meaning, and it explains wait (wait for all subdomain sources vs. fast first result) — but only partially, since the ~20 s ceiling is a skew-check. `domain` is self-evident, but `subdomain_limit` is never described anywhere, leaving one of three parameters semantically empty.

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 concrete verb (report) and resource (domain) and enumerates exactly the five sections produced — WHOIS/RDAP, DNS, SSL, subdomains, email authentication — which map one-to-one onto the sibling tools. An agent can tell this is the aggregate one-call variant of dns_records/whois_lookup/ssl_certificate/subdomains/email_security 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?

It gives clear usage contexts ('triage a suspicious domain', 'profile a company's domain'), which is strong routing guidance. It stops short of explicitly naming the siblings as the alternative when only one section is needed, so the when-not is left to inference from the section list.

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 establish readOnly, idempotent and openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses how DKIM is discovered (probing ~29 common selectors) and the concrete limitation that custom selectors are missed, which directly sets expectations about result completeness.

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 tight sentences, no filler. The mechanism and scope come first and the coverage limitation is appended concisely where it is most relevant.

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?

An output schema exists, so return-value detail is unnecessary here. The description covers what is fetched, how DKIM is discovered, and where results are incomplete, which is sufficient for correct invocation; only an explicit tie-breaker against dns_records 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 0% and the single 'domain' parameter carries no format detail in the schema. The description references 'a domain' but adds no syntax, apex/subdomain convention, or example, so it only partially compensates for the coverage gap on an otherwise self-evident parameter.

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?

Names a specific domain resource (SPF, DMARC, DKIM email authentication records) and the probing mechanism, so the agent knows exactly what is retrieved. The only gap is that it never explicitly contrasts with the sibling dns_records, which plausibly also surfaces TXT-based records, leaving the boundary to inference.

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 resource (auditing a domain's email authentication posture), but there is no explicit when-to-use guidance or named alternative such as dns_records. The 'custom selectors may not be found' line is a coverage caveat, not routing guidance, so it does not lift this above implied 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds real context beyond them: the data comes from an actual live TLS handshake on port 443, which tells the agent this is a network-dependent, potentially slow or failing operation. However, it says nothing about failure modes (no TLS, timeout, unreachable host) or rate limits.

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?

A single dense sentence that front-loads the core resource and mechanism before the field list. No filler, though the trailing field enumeration duplicates what the output schema likely already provides.

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 tool with annotations covering safety and an output schema covering return structure, the definition is nearly sufficient. The remaining gap is behavioral: it omits what happens when the handshake fails or the domain has no certificate, which matters for a live-network query.

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 0% – the single 'domain' parameter has no description and no format hints. The description only implicitly refers to 'a domain' and does not clarify acceptable forms (bare hostname vs URL, wildcards, IP addresses, ports). With low coverage, the description should compensate but does not.

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 concrete resource (the TLS certificate a domain serves on port 443) and the mechanism (a live TLS handshake), then enumerates the exact fields returned. An agent can tell this apart from dns_records, whois_lookup, and subdomains by the 'certificate' + 'TLS handshake' wording, though it never explicitly contrasts itself with those 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?

There is no when-to-use guidance, no exclusions, and no mention of the sibling tools. It does not say to call this when you need certificate expiry/inspection data, nor does it note any precondition (e.g. the domain must serve TLS on 443).

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 and idempotentHint, so the safety profile is covered. The description adds genuinely non-obvious behavior: the first lookup is a fast partial snapshot while later lookups are fuller, and wait=true blocks for all sources up to ~20 s. This latency/completeness tradeoff is exactly the kind of disclosure annotations cannot carry.

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, front-loaded with the core purpose and sources before the operational notes. Slightly cluttered by the `live`/`subdomains`/`pools` discussion, which reads like mode names but maps to no parameter in the schema.

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?

An output schema exists, so return-value documentation is not owed. However, the description introduces `live`, `subdomains` and `pools` as if they were selectable outputs without any corresponding schema parameter, which risks the agent attempting an invalid mode argument, and `limit` remains entirely unexplained for a 3-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains wait (blocks for all sources, ~20 s) with real semantic content, but leaves limit completely undefined — an agent cannot tell whether limit caps hosts, names, or sources, nor what the default 100 applies to. Partial compensation only.

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 resource (subdomains of a domain) and the data sources it aggregates (certificate transparency logs, passive DNS, DNS brute force), which is far more informative than the bare name. It does not, however, contrast itself with siblings like dns_records or domain_lookup, and the references to `live`/`pools` modes muddy what the tool's actual output shapes are.

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

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

The description implies when to set wait=true ('to wait for every source, up to about 20 s') and hints at a latency/coverage tradeoff, which is useful operational guidance. It gives no explicit when-to-use or when-not-to-use guidance relative to the sibling tools (dns_records, domain_lookup), so tool selection is still 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?

Annotations already declare readOnly, idempotent and openWorld, so safety is covered. The description adds genuinely new behavioral context: the RDAP-first strategy (rdap.org, IANA bootstrap, 22 fallback servers), the port-43 WHOIS fallback for 60+ TLDs, and that `_source` reports which backend answered. This explains variability in results that annotations cannot convey.

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 tight sentences with no filler; the payload (fields returned) is front-loaded, followed by the resolution mechanics and the usage trigger. Every clause earns its place.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description still flags the `_source` field and the fallback chain an agent needs to interpret results. The only gap is the accepted format of the `domain` input.

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?

There is a single required parameter with 0% schema description coverage, so the description must carry the load and does not. It never says whether `domain` accepts bare registrable domains, subdomains, URLs, or IDN forms — a meaningful ambiguity for a WHOIS/RDAP tool.

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 ('Registration data for a domain') and enumerates the returned fields (registrar, created, updated, expiry, nameservers, status), so the agent knows exactly what comes back. It does not explicitly distinguish itself from the close sibling domain_lookup, which is the only remaining ambiguity.

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?

Gives a clear use-case trigger: 'Use it for domain age, expiry or registrar checks.' That tells the agent when this tool is the right pick, but it names no alternatives or exclusions relative to domain_lookup or dns_records.

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