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

Annotations already declare readOnly, openWorld, idempotent, non-destructive, so the safety profile is covered. The description adds meaningful behavioral context beyond that: result caching for 6h and the truncation policy on prefixes (first 100, IPv4 then IPv6, with totals). It stops short of stating rate limits or error behavior, so not 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?

Front-loaded with the return shape, then usage, then the sibling disambiguation, then the caching note. Four dense sentences with no filler, though the parenthetical about prefix ordering is slightly crammed mid-sentence.

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?

No output schema, so the description carries the return-value burden itself and does so by enumerating the returned fields and prefix truncation. Caching and sibling routing are covered. It omits error handling and rate-limit behavior, but for a read-only lookup tool this is close to 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 coverage is 100%, and both parameters carry descriptive text including accepted query syntax and default values. The description's note about prefixes being limited to the first 100 adds runtime behavior the schema does not, but otherwise the schema does the heavy lifting. 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?

States a specific verb (look up) and resource (IP or AS number), enumerates exactly what is returned (announcing AS, covering prefix, holder, announcement status, prefixes), and clarifies it works for every RIR, not just RIPE. An agent can distinguish it from ip_whois and dns_lookup 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 (find hosting/network provider behind an IP, map an organisation's address space) and names the alternative (ip_whois) with the condition that routes to it (registration record and abuse contact). Clear when-to-use and when-to-use-something-else.

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 read-only, idempotent, open-world, non-destructive behavior, and the description adds real operational detail beyond them: ID deduplication, truncation reporting, a shared six-hour cache, and the staleness caveat that CT history is not live state. This is exactly the kind of context the 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?

Front-loads the returned data before the caveats, and each sentence carries distinct information (fields, dedup/truncation, isolation, cache, staleness). Slightly dense and list-like but nothing is 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 no output schema, the description compensates by enumerating the returned fields, and it also covers caching, truncation, deduplication, and the key limitation about current serving. An agent has everything needed to decide and invoke 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 coverage is 100% for both parameters, and the schema already documents the domain format and the 1-100 limit with newest-first ordering. The description adds no syntax or format detail beyond what the schema provides, 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 (Read) and resource (crt.sh certificate entries) and enumerates the returned fields (issuer, validity dates, logged time, related names, certificate link). The closing line 'CT history does not show what is served now' implicitly separates it from the current-state tls_certificate sibling.

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 clear context: it reads historical CT log data with 'No direct connection to the target' and does not reflect current serving, which steers the agent toward live-check tools for present state. It stops short of explicitly naming tls_certificate as the alternative for current certs, so no full when/when-not routing.

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 and non-destructive traits, and the description adds substantial non-obvious behavior: it returns the underlying records plus unavailable checks, makes no HTTP/TLS connection, warns that shared hosting makes matches non-conclusive of ownership, and notes RDAP cache can be six hours stale.

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 short sentences, front-loaded with the core purpose, then return shape, then two high-value caveats. No filler; every sentence 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?

With no output schema, the description usefully explains the return content (records per match plus unavailable checks). It also covers freshness and interpretation limits, so an agent has everything needed to call and read the result 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 coverage is 100% and the single param is already documented (2-6 domains or URLs). The description adds no parameter-level detail such as URL normalization or the item limit, so it matches the baseline of 3 when the schema carries the full 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 states a specific verb (find/compare) and resource (shared IPs, nameservers, mail servers, registrars) and the methodology (DNS and RDAP). It clearly distinguishes itself from single-lookup siblings like domain_whois or dns_lookup by being a cross-domain correlation tool.

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 rather than stated: an agent can infer this is for finding shared infrastructure across multiple domains. However, no alternatives are named and there is no explicit when-to-use/when-not guidance against siblings such as domain_whois or recon_domain.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds behavior beyond them: omitted empty types, a 5s timeout rendered as "<timeout>", NXDOMAIN on missing domains, and the return envelope shape. That is exactly the extra context annotations cannot express.

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 return contract and edge cases, then closes with a single-sentence routing note. Every sentence carries information; 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?

No output schema exists, yet the description supplies the response envelope and the two important exceptional outcomes (timeout and NXDOMAIN). For a 3-param read-only lookup this is 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 100%, so the schema already documents domain, nameserver, and record_types with examples and defaults. The description adds no parameter-level syntax beyond that, 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+resource ('Live DNS records for a domain') and immediately distinguishes itself from siblings by naming email_security and recon_domain. An agent can tell what it returns and how it differs from the alternatives 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?

'Use for raw records' is an explicit when-to-use directive, followed by the condition that routes the agent elsewhere ('email_security already reads and grades SPF/DMARC/DKIM'). This is textbook routing guidance with named alternatives.

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 the read-only, idempotent, open-world safety profile, and the description adds non-annotated traits: a 6-hour cache and the 'error' field returned for ccTLDs without public RDAP. It stops short of describing rate limits or whether results can be stale within the cache window.

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 resource and returned fields, then usage, then the caveat and caching note. Every sentence earns its place with no padding.

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 compensates by enumerating the returned fields and explaining the error shape for unsupported ccTLDs. For a single-parameter lookup tool, an agent has everything needed to call it and interpret results.

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 single parameter is already documented including the 'full URL works too' nuance, so the schema carries the load. The description adds nothing further about the domain argument, 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?

States a specific verb/resource (registration info for a domain via RDAP) and enumerates the exact fields returned (registrar, dates, nameservers, status codes, abuse contact). It also explicitly distinguishes itself from ip_whois and asn_lookup, the sibling tools an agent might otherwise confuse it with.

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 both a positive trigger ('Use for who registered a domain and when it expires') and an explicit routing rule for the alternative ('For who hosts it, run ip_whois or asn_lookup on its IPs'). It even covers the failure case for ccTLDs like .ro and .de, so the agent knows what an error result means.

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/idempotent/non-destructive, and the description adds meaningful traits beyond them: it uses live DNS, the only HTTP egress is the MTA-STS policy fetch at mta-sts.<domain>, and DKIM checks are limited to common selectors producing potential false negatives. This is exactly the context an agent needs to interpret results correctly.

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 and output, then checks performed, then the routing hint, then caveats — no filler sentences. Each clause carries distinct operational value.

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

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

With no output schema, the description still conveys the return shape (a letter grade plus a list of issues to fix), the checks covered, the data sources, and the known blind spot. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining why dkim_selectors matters and why the default is incomplete ('only common ones are tried'), plus that the domain input tolerates a full URL. Minor credit above baseline, though most parameter detail already lives in the schema.

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

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

States a specific verb+resource+output shape ('Grade (A-F) how well a domain is protected against being spoofed') and enumerates exactly what is checked (SPF, DMARC, MTA-STS, TLS-RPT, MX, DKIM). It explicitly distinguishes itself from the sibling dns_lookup, so an agent can route 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?

Directly names the alternative and the condition for choosing this tool: 'Prefer this over reading TXT records with dns_lookup, it parses and grades them.' It also flags an important limitation (DKIM selectors can't be listed, so absence of DKIM is not proof of absence), which guides correct interpretation of results.

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 non-destructive, so the safety profile is covered. The description adds meaningful context beyond them: direct network contact, redirect following, and the fact that results are not cached (so repeat calls re-hit the site). What it omits – rate limits or timeout behavior – is minor.

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 return summary, then the caveats (direct contact, alternative tool, no caching). The header enumeration is long but each item is genuinely part of the output contract, so it earns its place; only mild tightening is 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?

With no output schema, the description carries the full burden of describing returns and does so concretely (status, redirect chain, final URL, headers, missing-security-header list). For a single-parameter read tool it leaves nothing essential unspecified.

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?

Only one parameter and schema coverage is 100%, so the schema already documents the URL format and bare-domain handling. The description adds nothing about the parameter, which is the expected baseline when the schema does the heavy lifting.

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 ('One GET request to a URL') with explicit scope (follows redirects) and enumerates the return surface, including a security-header checklist. An agent can distinguish it from siblings like tls_certificate 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?

Explicitly routes the certificate use case to tls_certificate and clarifies that this tool contacts the site directly like a browser visit, which sets expectations for when it applies. It stops short of a full when/when-not rule, 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, yet the description adds substantial behavioral context: it contacts the live site, reads bounded HTML, may take over a minute on slow archives, treats page text as untrusted data, and explicitly cannot verify deliveries/reviews/ownership or assign a safe/scam score.

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?

Dense but front-loaded: the collection scope leads, followed by return shape, then runtime and limitation caveats. Every sentence carries information, though the three-line block is close to the ceiling for its value.

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

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

No output schema exists, so the description correctly summarizes the return ('concrete signals with evidence paths and explicitly missing checks'). Combined with the runtime, safety-boundary and untrusted-data notes, an agent has everything needed to invoke and interpret this complex 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 schema already fully documents url, follow_legal and reference_domain. The description adds no parameter-level detail beyond that, 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?

The description opens with a specific verb+resource ('Collect page details, ... domain registration, DNS, email security, HTTP, TLS and ... Wayback snapshots'), which clearly frames it as a broad reconnaissance aggregator. It distinguishes itself from the many single-signal siblings (dns_lookup, wayback, tls_certificate) by scope, though it never explicitly names an alternative.

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 aggregation scope rather than stated: an agent can infer this is the one-shot comprehensive check, but there is no explicit 'use this when...' or 'use X instead for...'. The stated limitations (cannot verify deliveries/reviews/ownership, no safe/scam score) are capability boundaries, not 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: RDAP data is cached for 6h while the PTR lookup is live — useful for judging staleness. It does not discuss rate limits or failure modes, so not 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?

Three tight sentences with zero filler: returns are front-loaded, then usage/routing alternatives, then a freshness caveat. Every sentence 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?

With no output schema, the description compensates by enumerating the return fields, and it covers purpose, alternatives and caching behavior. An agent has everything needed to select and call 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?

Only one parameter with 100% schema description coverage, and the schema already gives both IPv4 and IPv6 examples. The description adds no syntax or format detail beyond the schema, so the baseline 3 for fully-covered schemas 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?

Opens with a specific verb and resource ('Who owns an IP') and enumerates exactly what is returned: network name, range/CIDRs, country, registrant org, abuse contact, plus PTR names. This is instantly distinguishable from siblings like domain_whois or asn_lookup 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?

Explicitly states the intended use ('for the owning organisation and where to report abuse') and names two alternatives with the condition that selects each: asn_lookup for the routing view, shodan_internetdb for open ports. No inference 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?

Adds substantial traits beyond the annotations: 3-way concurrency, a 90s per-domain deadline, multi-minute worst case, retained source failures/coverage, and that it starts without direct web connections. This meaningfully extends the readOnly/openWorld/idempotent annotation profile.

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 capability, then timing and routing. Every sentence carries signal; 'Starts without direct web connections' is slightly ambiguous but earns its place as a default-behavior cue.

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 report contents (source failures, coverage), timing behavior, and default connection mode. An agent has enough to call and interpret results 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 coverage is 100%, so domains, include_active, and include_subdomains are fully documented in-schema. The description restates batch size and the no-direct-connection default but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource+scope ('Check up to ten domains') with concurrency detail, and explicitly distinguishes itself from compare_domains. An agent can tell this is the batch recon tool 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?

Explicitly routes one case ('Use compare_domains when the question is how sites are related'), but never contrasts with recon_domain, its obvious single-domain sibling. Clear context with a missing alternative and no explicit 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description layers on behavior the annotations cannot express: latency (10-60s, mostly crt.sh), graceful partial failure ('if one source fails, its section holds an "error" and the rest is still returned'), and output caps (subdomains at 100, raw headers dropped). This is meaningful context 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?

Front-loaded with the enumeration of what the report contains, followed by routing guidance and then operational caveats. Three tight paragraphs, each sentence earning its place 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?

With no output schema, the description carries the return-shape burden and does so: it names the sections returned, the trailing 'highlights' list, and the per-section error handling. Nothing an agent needs to call this 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 schema documents all three parameters, establishing a baseline of 3. The description adds genuine meaning that maps to parameters: the subdomain cap of 100 (relevant to include_subdomains) and the omission of raw HTTP headers (relevant to include_active), plus the runtime implication of each. It stops short of syntax details, but adds real value.

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 ('Passive overview of a domain in one call') and then enumerates exactly which data sources it aggregates (whois, DNS, email security, TLS, HTTP headers, subdomains, ASN/reverse DNS/Shodan). An agent can distinguish it from domain_whois, dns_lookup, tls_certificate, etc. 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?

Explicitly says 'Start here for general questions about a domain' and names the alternative condition: 'Use the single-purpose tools when you only need one thing or the full data.' It further sharpens the trade-off by noting this report drops raw HTTP headers and caps subdomains at 100, so the when/when-not decision is fully specified.

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, but the description adds materially: no API key, the IP is never contacted, data may be days old, unscanned IPs return empty ports with a note, and results are cached for 6h. That is exactly the kind of freshness, cost, and failure-mode context 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 short paragraphs: what it returns and its provenance, then when to use it, then a caching note. Front-loaded with the payload contents, zero filler sentences.

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 still tells the agent what fields come back and what an empty result looks like, plus freshness and caching behavior. 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 coverage is 100% and the single parameter already carries format examples (IPv4/IPv6). The description adds no syntax or constraint beyond what the schema provides, 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 exactly what is returned (open ports, hostnames, CPEs, tags, known CVEs) for a specific resource (an IP), and its data source (Shodan's free InternetDB). It is clearly distinguishable from ip_whois and asn_lookup, which it names.

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 when-to-use: on A records from dns_lookup, or on any IP before escalating to ip_whois/asn_lookup. Names the alternatives and the sequencing condition that selects them.

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?

Goes well beyond the annotations: the target is never contacted, names may be stale, crt.sh can take up to a minute, retries twice on 502/503, advises retrying later, and results are cached for 6h. These are exactly the operational traits an agent needs and are not derivable from readOnlyHint/idempotentHint.

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

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

Front-loads what the tool returns, then behavioral caveats and retry guidance, in compact sentences with no filler. Every sentence carries actionable 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?

With no output schema, the description correctly covers the return shape (sorted, de-duplicated names with wildcards stripped, plus matched certificate count) along with latency, failure modes, and caching. An agent has everything needed to call it and handle results.

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% with a single parameter, so the schema already documents the domain argument and its URL-tolerance. The description adds nothing about parameter syntax, so 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 resource and scope - every subdomain from public TLS certificates via certificate transparency logs (crt.sh) - with no ambiguity about what is returned. The mention of dns_lookup and the wildcard/dedup handling further separate it from sibling recon tools.

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 clear context for use and explicitly routes the agent onward to dns_lookup for resolution checks. It does not state when NOT to use it versus recon_domain or tls_certificate, but the CT-log scope makes the boundary fairly evident.

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/non-destructive, but the description adds meaningfully: a 10s timeout, no caching, direct connection 'like a browser would', and the non-obvious contract that invalid certs return valid=false with a reason instead of an error. It also discloses the warning thresholds (14-day expiry, deprecated TLS) that shape the output.

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 action, then the returned fields, then the error contract, then the alternative. Every sentence carries non-redundant information; 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?

With no output schema, the description earns its keep by enumerating the returned fields and the invalid-cert shape, and it covers timeout, caching, and sibling routing. An agent has everything needed to call it correctly and interpret the result.

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%, with the host and port descriptions already documenting verification behavior and mail-server ports. The description adds only the host:port framing, so the baseline 3 is appropriate rather than a bonus.

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+resource ('Connect to host:port and read its TLS certificate') and enumerates exactly what is returned (subject, issuer, validity, SANs, serial, TLS version/cipher, warnings). It also distinguishes itself from the sibling `subdomains` by scoping itself to one host's live certificate.

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 routing: use this tool for the host's own certificate, and 'For other hostnames seen in the domain's past certificates, use subdomains.' It also brackets the appropriate ports (443 vs 465/993/995) so the agent knows the intended scope.

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 safety (readOnly, idempotent, openWorld, non-destructive), and the description adds genuinely new operational context: identical consecutive captures are collapsed, results are metadata only (open archive_url for content), the upstream CDX API often takes 20-30s, may return 503, and the tool retries twice and caches for 6h. That is exactly the latency/failure behavior an agent needs before calling.

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 paragraphs: what it returns, when to use it and its limits, then operational caveats. Front-loaded with the resource and output shape, and no sentence is 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?

No output schema exists, and the description compensates by listing timestamp, original URL, HTTP status, MIME type, and archive_url, plus the deduplication rule. Combined with latency/retry/cache disclosure, 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% and each of the five parameters is documented in-schema (including the /* prefix convention and clamping semantics), so the schema carries the burden. The description's enumeration of returned fields is about output shape, not parameter meaning, so it adds little here.

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+resource: archived snapshots of a URL from the Wayback Machine's CDX index, and enumerates the fields each result carries. It is trivially distinguishable from the sibling recon/WHOIS/DNS tools, which operate on live infrastructure rather than historical archives.

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 concrete use cases ('see how a page changed over time', 'find pages that no longer exist') and clarifies the boundary that it returns metadata, not content. It stops short of naming an alternative tool or a when-not-to-use condition, but the use context is unambiguous.

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