DC5 WHOIS

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

Goes well beyond the annotations (readOnly, idempotent, closed-world) by disclosing that evaluation is offline against a local RPKI snapshot, that the procedure is an Internet-Draft rather than an RFC, and that real-router neighbor-AS and AS_SET prerequisite checks are omitted. It also states the path is neither stored nor logged, which is information the agent cannot get from 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?

Front-loads the core action and result semantics, then uses short paragraphs for interpretation and caveats. Slightly longer than strictly necessary (the draft/RFC caveat and the 'not stored or logged' note both appear), but every sentence carries usable information.

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

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

An output schema exists, so return values need not be described; the description instead covers the things it must — offline operation, draft-stage procedure, omitted prerequisite checks, and how to read 'unknown'. Nothing an agent needs to call or interpret 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 both 'path' and 'direction' are already documented, including ordering, separators and AS_SET refusal. The description reinforces that 'only the path is read' but adds no new syntax or semantics, 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?

States a specific verb and resource ('Check an AS_PATH against the published ASPA objects') and defines ASPA inline, so the agent knows this is ASPA-based path validation rather than a generic route lookup. The stated aim ('find out whether a path shows a route leak or an unauthorised provider') further scopes it, but no sibling such as check_route is named for contrast.

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 (detecting route leaks / unauthorised providers) and pre-empts a likely misreading by explaining that 'unknown' means a missing ASPA publication, not a fault. It offers no explicit when-not conditions or named alternatives, so the routing guidance stops short of the top band.

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 only establish that this is a safe read (readOnlyHint, idempotentHint, openWorldHint=false), but the description adds substantial context beyond them: it is offline and instant with no DNS/registry/network call, and it discloses a real limitation — it catches script tricks only, not typo or digit swaps (paypa1.com), so a clean result does not mean the domain is safe. This is unusually rich behavioral disclosure.

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 definition and example, then usage/routing, then behavior and limitations. Every sentence earns its place; no filler or restatement of the title.

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, offline, read-only tool with an output schema already covering return values, the description supplies the remaining essentials: scope of detection, negative-result caveat, and sibling routing. Nothing needed to call 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 description coverage is 100% and the schema already documents the single 'name' parameter including the Unicode/punycode formats and the rejection of full URLs. The description contributes only an illustrative example, so it neither extends nor contradicts the schema — the baseline 3 for a fully covered parameter 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 (check a domain/Web3 name for visual look-alike/homograph) and defines the concept concretely with a worked example ('раураl.com reads as paypal.com'). An agent can distinguish it from lookup_target and the other siblings 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?

Gives explicit use cases (phishing triage, brand monitoring, screening candidate or incoming names) and an explicit alternative with a routing rule: lookup_target already includes this warning, so don't call both for one name. That is exactly when-to-use plus 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?

Annotations already declare readOnly/idempotent/openWorld, and the description goes further with genuinely non-obvious behavioral facts: it reads public DNS only, never connects to mail servers, and therefore cannot test SMTP TLS, certificates, or mailbox existence. It also commits to a latency bound (under 2 s), which helps an agent decide between one bulk call and many.

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, then scope, then routing guidance, then limits — a logical order with no filler sentences. The check enumeration is dense but every clause maps to a real output field, so only its length keeps it from a 5.

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 not required; the description instead supplies what the schema cannot — the meaning of the grade levels (strong/fair/weak/no_mail/none) and the tool's hard limitations. Nothing an agent needs to invoke or interpret 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 description coverage is 100% and the single 'domain' parameter is already well documented in the schema (registered domain or subdomain, not an email address or mail server host). The description adds no additional input semantics, so the 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 (grade) and resource (one domain's email authentication), then enumerates the exact checks covered (SPF limit/all qualifier, DMARC inheritance/pct, MTA-STS, TLS-RPT, BIMI, DANE, null MX). It explicitly distinguishes itself from the sibling lookup_target, so an agent can route correctly without opening either 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?

Gives explicit trigger scenarios ('spoofing, deliverability or a DMARC rollout') and a direct comparison to the alternative: lookup_target gives only the overall grade, while this tool returns per-check status and a one-line finding. The when-to-use-this-vs-sibling decision is fully resolved.

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 cover read-only/idempotent/closed-world, but the description adds information they cannot carry: the tool is answered from local offline snapshots whose dataset coverage varies by instance, and the result only lists datasets actually loaded. It also pre-empts two classic misinterpretations — RPKI invalid may be a stale ROA and an IRR object is only a claim, neither proving hijack or authorisation, and absent RIS visibility does not mean the prefix is unannounced.

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 what is checked and why it matters, then a clearly labelled Behavior section. The caveat paragraph is longer than typical but each clause prevents a specific real-world misreading; only minor trimming would be possible.

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?

Output schema exists, so return values need no explanation; the description instead supplies the interpretive context an agent needs — offline snapshot provenance, variable dataset coverage, and the limits of each signal. Nothing required to call or interpret the result 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, but the description reinforces the key constraint that this is exactly one pair at a time rather than a batch, which shapes how an agent should call it. It does not restate formats (AS13335, CIDR) since the schema already does that thoroughly.

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 the exact input (one prefix, origin AS pair) and the three concrete datasets consulted (RPKI ROA validation per RFC 6811, IRR route objects, RIPE RIS peer visibility). It explicitly contrasts with lookup_target, so an agent can distinguish it from siblings without opening the 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?

Gives three concrete question shapes this answers (is an AS authorised to originate, why a route is dropped by RPKI filtering, does a registry object match an announcement) and explicitly routes all prefix-wide or AS-wide questions to lookup_target. Both when-to-use and when-to-use-something-else are stated.

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, closed-world and idempotent, yet the description still adds substantive context: it is answered from synced IANA and root-zone data, makes no network call, is instant, and fields without data are omitted rather than guessed. It also scopes negatively by naming two fields deliberately absent (registry operator, delegation date), which prevents false expectations.

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?

It is front-loaded: contents first, then usage, then behavior, each in its own paragraph. The one weakness is the very long first sentence, which packs six field groups into a single clause chain and costs more reading effort than a short bulleted list would.

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 a single parameter, an output schema carrying the return shape, and annotations covering safety, the description supplies exactly the remaining pieces: data provenance, offline behavior, omission policy, scope exclusions and the sibling alternative. Nothing an agent needs to call 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 description coverage is 100% and the single tld parameter is fully documented there, including examples, leading-dot tolerance and the punycode/unicode case. The description adds no parameter-level meaning beyond that, 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 first sentence names a specific verb and resource ('facts about one top-level domain') and enumerates exactly which facts are returned (delegation, type, RDAP server, name servers, DS/DNSSEC, Web3 namespace collisions). The closing line of the usage paragraph explicitly separates it from the sibling lookup_target, so the agent can distinguish it without opening the 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?

Three concrete use cases are given ('where to send an RDAP query for a TLD, whether a TLD is signed, or whether a name under it could mean something else on a blockchain') plus an explicit redirect: 'For one domain use lookup_target instead.' That is when-to-use plus the alternative, nothing 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, openWorld=false and idempotent, so the safety profile is covered; the description still adds useful behavior: no arguments, no external calls, and the fact that live-fetched sources never appear in this listing. It stops short of saying how often dataset state changes or how to refresh, but the marginal value over the annotations is real.

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 purpose, then usage, then behavior in three tight paragraphs with no filler. The parenthetical dataset enumeration is long, but it is the one piece of content that tells an agent what coverage to expect, so it largely earns its space.

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 values need no explanation, and the annotations carry the safety/idempotency profile. For a zero-argument inventory tool the description covers purpose, the decision context, the exclusion set, and the no-side-effects guarantee — nothing an agent needs to invoke it correctly is absent.

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 takes zero parameters, which is the baseline-4 case, and the description confirms this explicitly ('takes no arguments'), removing any question of whether filtering arguments are available. There is nothing further to document.

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 ('list the local datasets and feeds behind lookup_target') and enumerates the dataset families covered (RIR, IANA, PSL, cloud/CDN, Tor/Private Relay, reputation, GeoLite2). It also returns concrete fields (state, record count, generation date, stale flag), so an agent can distinguish this inventory tool from lookup_target immediately.

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 ('judge how current a reputation, RIR, cloud or geolocation answer is', 'explain why such a section is missing') and draws a clear exclusion boundary: registry, DNS and Web3 data are fetched live and are not listed here. Both the trigger and the non-coverage are spelled out.

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 live lookup behavior, shared rate limits, partial failures, retryable refusals, concurrency of up to 3, and an approximately 22-second cutoff. These are meaningful operational constraints that an agent would otherwise not know.

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 batch purpose and output shape, followed by usage guidance and then operational behavior. Each sentence contributes useful selection or invocation context without 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?

Although an output schema exists, the description still summarizes the return content and covers rate-limit, timeout, concurrency, and partial-failure behavior. Given the tool's batch complexity and open-world annotations, it is complete enough for an agent to call 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?

Schema description coverage is 100%, so the single queries parameter is already fully documented, including the 10-target cap, supported target forms, and duplicate dropping. The description restates the target types and limit but adds little parameter-level meaning beyond the schema.

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

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

The description states a specific batch lookup action, enumerates supported target types, and explains the per-target result shape. It also explicitly differentiates from the single-target sibling by directing users to lookup_target for a full fact sheet.

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 concrete triage examples such as domains in a phishing report or IPs in a log excerpt, and it names lookup_target as the alternative for single-target full fact sheets. The usage boundary between batch and single lookup is clear.

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

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

Adds substantial context beyond the readOnly/openWorld/idempotent annotations: live registry-DNS-RPC queries with 1-5s typical and ~12s worst-case latency, partial-failure semantics (other sources still returned, failures listed under errors), a reputation caveat that no-match is not a clean bill of health, and a no-logging/no-storage privacy note.

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 purpose, then a scanning paragraph listing per-type returns, then usage routing, then behavior — a logical order with no filler. The per-type return enumeration is long and partly redundant with the output schema, which keeps it from being maximally tight.

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-query, open-world lookup with an output schema already present, the description supplies everything needed to call it correctly: accepted input formats, latency expectations, partial-failure handling, and a pointer to details_url for full provenance.

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 applies; the description's format list ('AS15169', '0x…', 'hns:name') largely restates the query parameter's own schema text. The namespace parameter is left entirely to the schema, and the description adds no new parameter-level semantics such as how ambiguous names are resolved beyond what the schema already says.

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 ('look up') plus an explicit enumeration of accepted resource types (domain, IP, CIDR, ASN, EVM address, Web3 name) and what each returns. This makes it immediately distinguishable from narrow siblings like check_mail_security or get_tld_info.

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 default rule ('use it first for any question about who owns, runs, hosts or registered something') and names two alternatives with the condition that selects them (check_mail_security for per-check detail, check_lookalike for bulk screening without network calls). It omits the obvious batch sibling lookup_many, so an agent asking about many targets is not routed.

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