drwho.me

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

With no annotations, the description carries the full burden. It discloses the backend (Cloudflare DoH), behavior (follows CNAME chains, 5s timeout), return format (JSON array), and error handling (string). It lacks mention of rate limits or read-only nature, but overall is transparent.

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 concise (4 sentences) and front-loaded with the core function. The inclusion of an inconsistent record type list slightly harms clarity and conciseness.

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

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

Given no annotations or output schema, the description covers usage, behavior, and alternatives reasonably well. However, the mismatch between described and allowed record types leaves incomplete context, and no mention of idempotency or read-only nature.

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 baseline is 3. However, the description overpromises by listing record types (SOA, CAA, SRV) not in the schema enum, which directly contradicts the parameter constraints and misleads agents.

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

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

The description clearly states that the tool resolves a single DNS record type and returns raw answers, distinguishing it from sibling tools like dossier_dns and dossier_full. However, the list of record types in the description (including SOA, CAA, SRV) does not match the schema enum, causing potential confusion.

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

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

The description explicitly provides when to use this tool ('quick, targeted lookups') versus alternatives ('dossier_dns for full multi-type audit, dossier_full for complete health check'), offering clear usage 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?

With no annotations provided, the description carries full burden and excels. It discloses that a single OPTIONS request is made with a 5-second timeout, defaults for origin and method, and the exact structure of the response (CheckResult with status and headers on success, error on failure). This level of detail is highly transparent and aids agent understanding.

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 a single, well-structured paragraph of about four sentences. It front-loads the purpose, then explains usage, behavior, and output. Every sentence is informative and non-redundant, making it concise yet complete.

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

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

Given the absence of an output schema, the description compensates by detailing the return format (CheckResult with status and headers). It covers inputs, defaults, timeout, and error case. No further context seems necessary for effective tool selection and 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%, but the description adds significant value by explaining how parameters interact: 'provide origin and method to simulate a precise preflight, or omit to use defaults'. It also gives concrete default values, which the schema descriptions do not fully convey. This goes beyond the schema's basic type and description.

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

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

The description clearly states the tool's purpose: sending a CORS preflight OPTIONS request and returning CORS headers. It uses specific verbs ('verify', 'check') and identifies the resource ('CORS policy'). It is clearly distinct from sibling tools like dns_lookup or tls checks, which target different aspects.

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

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

The description provides explicit guidance on when to use the tool: to verify CORS policy for a specific origin-method pair or to check if a domain allows cross-origin requests. It explains how to customize with optional parameters and mentions default values. However, it does not explicitly state when not to use it or suggest alternatives, though the sibling list implicitly provides context.

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?

Discloses all relevant behavioral traits: query sources, cap, timeout, return structure. No annotations exist, so description carries full burden and meets it.

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 purpose, then guidelines and behavior. No extraneous 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?

For a simple tool with one parameter and no annotations or output schema, the description covers input, behavior, and return keys. Lacks explanation of wildcards and certCount, but adequate given tool simplicity.

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 100%, but description adds valuable constraints beyond schema: domain must be 'Public FQDN... Must be resolvable on the public internet; IPs, ports, paths, and protocol prefixes are rejected.'

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: 'Discover subdomains visible in Certificate Transparency logs.' Explicitly mentions attack-surface mapping and distinguishes from sibling dossier_full.

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

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

Explicit guidance: 'Use for attack-surface mapping; prefer dossier_full when running a complete audit.' Also documents fallback behavior (crt.sh then certspotter), capacity cap (100), and timeout (10s).

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?

No annotations are provided, so the description carries full burden. It transparently describes parallel Cloudflare DoH queries, 5-second timeout, and error handling. The return structure is also detailed, though some edge cases (e.g., rate limits) are not mentioned.

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 concise (~4 sentences) and front-loaded with the core purpose. Every sentence adds value, and there is no redundancy.

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

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

With no output schema, the description fully covers the return values (CheckResult with status, found, notFound, or error). It also describes parameters and behavior completely, leaving no significant gaps for a query 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?

The input schema has 100% coverage, but the description adds significant meaning: it explains the query format `<selector>._domainkey.<domain>`, lists the default selectors, and clarifies the effect of omitting the selectors 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?

The description clearly states it probes a domain's DKIM public keys via TXT queries for specific selectors. It distinguishes from sibling dossier tools by focusing on DKIM, and the verb 'probe' is specific.

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 supply selectors (when you know ESP's selector) and when to omit (to probe six common selectors). While it doesn't provide when-not-to-use or alternatives, for a single-tool use case it 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?

With no annotations provided, the description carries the full burden. It discloses the query mechanism (Cloudflare DoH), timeout (5 s), parsing behavior, and return format (CheckResult with success/failure). This is thorough and transparent.

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 concise yet comprehensive, with each sentence serving a purpose. It is front-loaded with the core function, followed by use cases and technical details.

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?

Despite no output schema, the description explains the return structure. It covers the query method, timeout, and error handling. The context of sibling tools is included. For a single-parameter tool, it is 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?

The input schema has 100% description coverage for the single parameter 'domain', so the description adds no new meaning beyond the schema. Baseline is 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 clearly states the tool retrieves and parses a domain's DMARC policy from a TXT record, specifying the action and resource. It distinguishes itself from siblings by mentioning dossier_spf and dossier_dkim for complete email-auth coverage.

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

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

The description explicitly states when to use the tool: to audit email authentication policy, verify specific tags, and pair with sibling tools. It provides clear context and situational 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?

Discloses concurrent Cloudflare DoH queries, 5s timeout, and the CheckResult discriminated union format. No annotations present, so description carries the burden; it covers key behavioral traits but omits rate limit details.

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 compact sentences, each serving a purpose: purpose, usage guidelines, implementation detail, return format. No fluff, front-loaded with core purpose.

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

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

Given no output schema, the description fully documents the return value. Parameter is well-explained. Differentiates among 17 siblings. Covers all necessary aspects for a single-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 coverage is 100%; the description adds value by specifying that the domain must be a public FQDN and rejecting IPs, ports, paths, and prefixes, which is not in the schema description.

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

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

The description clearly states the verb 'Fetch' and the resource 'domain's full DNS profile', listing specific record types. It distinguishes from sibling tools 'dns_lookup' and 'dossier_full' by contrasting scope.

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

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

Explicitly tells when to use ('first step of a domain audit', 'comprehensive DNS snapshot') and when not to (prefer dns_lookup for single record, dossier_full for all checks), with alternative tool names.

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?

No annotations provided, but description fully discloses behavior: fires Cloudflare DoH queries with DO=1, 8s timeout, returns CheckResult discriminated union with specific fields. No contradictions.

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 purpose, no wasted words. Efficient and clear.

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, but description explains return type and key fields. Covers behavior, constraints, and alternatives. Fully complete for a simple 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?

Only one parameter with 100% schema description coverage. Description adds constraints: public FQDN, must be resolvable, rejects IPs/paths/ports. Adds significant value beyond 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?

Clearly states the tool verifies DNSSEC chain-of-trust for a domain, listing specific record types (DS, DNSKEY, AD flag). Differentiates from sibling tools dossier_dns and dossier_full by specifying their use cases.

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 (confirm zone is signed and resolvers accept chain) and when not (prefer dossier_dns for raw records, dossier_full for complete audit). Provides clear context.

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?

With no annotations provided, the description fully discloses behavior: concurrency, 5s per-check timeout, Cloudflare DoH/HTTPS methods, paywall billing, and return format (keyed CheckResult union). No annotation contradiction exists.

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

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

Single paragraph with front-loaded summary ('Aggregate dossier check'), followed by usage guidance, technical details, and return format. Every sentence adds value with no redundancy.

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

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

Despite no output schema, description fully explains return structure (JSON keyed by check ID with CheckResult union). Covers all behavioral aspects (parallelism, timeout, paywall) for a complex aggregated tool with one parameter.

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 domain parameter already well-described. Description does not add new semantic details beyond the schema, but context reinforces parameter purpose. 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?

Description clearly states it aggregates all 10 Domain Dossier checks in parallel, using the verb 'Run all 10' and naming the specific checks. It distinguishes from sibling tools by explicitly recommending individual dossier_* tools for single checks, making the purpose unambiguous.

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

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

Explicitly states when to use (comprehensive snapshot) and when not to (single checks), with alternatives named ('prefer the individual dossier_* tools'). Also notes paywall counting benefit, aiding agent decision-making.

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?

No annotations provided, but the description fully discloses behavior: single GET, 5s timeout, captures headers before redirect, and outlines return format (CheckResult with success/error).

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?

Efficiently packs purpose, usage, behavior, return format, and sibling reference into a few sentences without unnecessary words.

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

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

Given no output schema and no annotations, the description covers all needed context: what it returns (headers and audit), error handling, timeout, and redirect behavior.

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 the single parameter, but the description adds validation rules (rejects IPs, ports, paths, protocols) beyond the schema's 'Public FQDN' hint.

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

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

The description clearly states the verb 'Fetch' and resource 'HTTP response headers of https://<domain>/', includes specific security headers to review, and distinguishes from sibling dossier_redirects.

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 (review security headers) and provides alternative (dossier_redirects for redirect tracing), leaving no ambiguity.

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?

No annotations are provided, so the description carries the full burden. It transparently describes the process (DNS TXT lookup, HTTPS fetch from mta-sts.<domain>/.well-known/mta-sts.txt, 10s timeout) and the return behavior (not_applicable when no TXT). No side effects or auth needs are mentioned, but for a read-only check this is sufficient.

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 extremely concise: two sentences. The first sentence states the purpose and what it does; the second covers technical details and return behavior. No filler words, and the key information is front-loaded.

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

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

The tool has only one parameter and no output schema. The description explains the process and the return value (CheckResult, with a specific not_applicable case). It is complete for the given complexity, though it could optionally list the fields returned to further enhance context.

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

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

The input schema has 100% coverage with a detailed param description for 'domain'. The tool description adds context about the MTA-STS check but does not further elaborate on the parameter beyond what the schema already provides. Baseline 3 is appropriate as 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?

The description explicitly states the tool fetches and validates a domain's MTA-STS policy, listing key fields (mode, mx, max_age, policy id). It positions this as a 'core dossier check' for confirming inbound SMTP TLS locking, clearly distinguishing it from sibling tools like dns_lookup or dossier_dmarc.

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

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

The description gives clear usage context: 'Use to confirm inbound SMTP is locked to TLS for this domain.' It explains the technical steps (resolving TXT record, fetching policy) but does not explicitly state when not to use it or suggest alternatives, which would be helpful given the many sibling tools.

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?

Given no annotations, description fully discloses behavior: queries Cloudflare DoH, follows CNAME aliases, 5s timeout, and return format (CheckResult discriminated union with success/error).

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?

Description is front-loaded with purpose, then usage, then behavioral details. Every sentence is informative with no redundancy.

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

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

Tool has one parameter and no output schema; description covers purpose, usage, behavior, and return format completely.

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 the single parameter, and description repeats the schema's description without adding new meaning. 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?

Description explicitly states 'Look up a domain's MX records and return them sorted ascending by priority', with clear verb and resource. Distinguishes from sibling tools like dns_lookup and other dossier checks.

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?

Provides explicit when-to-use context ('verifying inbound-mail routing or as a precursor to SPF or DMARC checks') and alternative ('prefer dns_lookup with type=MX if you only need the raw DNS answer').

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?

No annotations provided, so description carries full burden. It discloses starting URL, follow behavior (fetch with no auto-redirect), per-hop timeout (5 s), hop limit (10), and return format for both success and failure. This is comprehensive.

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

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

The description is three sentences, front-loaded with purpose, followed by use cases and behavioral details. Every sentence adds value with no redundancy.

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

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

For a tool with one parameter and no output schema, the description fully explains input constraints, behavior (include hop limit, timeout, follow behavior), and return format for both success and error cases. No gaps remain.

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 'domain' with schema description already clear. The description adds context about how the domain is used (prepended with https://) and reinforces constraints. With 100% schema coverage, baseline is 3; the description adds marginal value 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 explicitly states the tool traces the full HTTP redirect chain starting from https://<domain>/, recording each hop's status code and destination URL. It uses specific verbs and clearly distinguishes from sibling tools by focusing on redirects.

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

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

The description provides explicit use cases: debugging redirect loops, verifying HTTP→HTTPS upgrades, auditing link shorteners. It also notes the 10-hop limit to prevent infinite loops and constraints on domain input. While it does not name alternative tools, the context 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?

Without annotations, fully discloses behavior: fetches TXT via Cloudflare DoH, 5s timeout, parses v=spf1 record, returns CheckResult with status, raw, mechanisms, lookupCount on success; error on failure.

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?

Single well-organized paragraph: purpose, usage, technical details, return format. Every sentence contributes; no wasted words.

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

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

Given no output schema and simple input (1 param), description fully covers input constraints, behavior, and return structure. Suitable for agent to 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 covers domain 100% with description 'Public FQDN'. Description adds constraints: 'Must be resolvable on the public internet; IPs, ports, paths, and protocol prefixes are rejected.' Adds value beyond 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?

Clearly states it retrieves and parses SPF records, decomposing mechanisms and qualifiers. Distinguishes from siblings: dns_lookup (raw record) and dossier_dmarc (complementary 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?

Explicit use cases: verify email policy, debug delivery failures, check 10-lookup limit. Recommends pairing with dossier_dmarc and contrasts with dns_lookup for raw records.

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?

Given no annotations, the description fully discloses behavior: performs a TLS handshake from server edge, 5s timeout, extracts leaf certificate, and returns success/error objects with specific fields. No contradictions.

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 a single paragraph, front-loaded with purpose and quickly gets to details. Every sentence adds value with no redundancy.

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

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

Even without an output schema, the description completely covers input constraints, behavioral details, and the return structure (CheckResult with status fields). For a simple tool with one parameter, it is fully adequate.

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 baseline is 3. The description adds extra semantics: domain must be a public FQDN, rejects IPs/ports/paths/protocols, and requires resolvability. This compensates above baseline.

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

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

The description clearly states the tool fetches and inspects TLS certificates, specifying port 443, and lists use cases like verifying expiry, issuer, SANs, or detecting mismatched/self-signed certs. It distinguishes from sibling tools like dossier_cors or dossier_dns by focusing on TLS.

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 tells when to use (verify certificate details) and what not to expect (not a full cipher-suite scanner). This provides clear guidance for the agent to select appropriately among dossier tools.

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?

With no annotations provided, the description compensates fully by disclosing key behavioral traits: it resolves a specific DNS record (_smtp._tls.<domain> TXT) via Cloudflare DoH, has a 5-second timeout, returns a CheckResult, and handles the 'not_applicable' edge case when no record exists.

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

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

The description is two sentences long, each serving a distinct purpose: first explains what the tool does, second adds technical details. No redundant or extraneous information is present, making it highly concise.

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

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description covers all necessary aspects: purpose, usage, technical behavior (DNS resolution method, timeout), return type, and an important edge case. It is fully complete for an agent to use the tool correctly.

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

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

The input schema already provides a detailed description for the 'domain' parameter (e.g., 'Public FQDN, must be resolvable on public internet'). With 100% schema coverage, the description adds no additional parameter semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Look up a domain's TLS-RPT (SMTP TLS Reporting) policy.' It specifies the verb ('look up') and the resource ('domain's TLS-RPT policy'), and distinguishes itself from sibling tools like dossier_dmarc or dossier_spf by focusing on a specific record type.

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

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

The description provides a clear use case: 'Use to confirm the domain receives reports of SMTP-TLS failures.' While it does not explicitly state when not to use or list alternatives, the use case is specific enough to guide the agent. A score of 4 is appropriate as it gives clear context without exclusions.

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

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

The description discloses concurrency, timeouts (5 s each), HTTPS requirement, and return format (CheckResult with status, meta, robots, sitemapPresent). No annotations are provided, so the description carries the full burden and does so comprehensively.

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

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

The description is three sentences long, each serving a distinct purpose: purpose/usage, behavior, and return format. It is front-loaded with the core action. Slightly longer than minimal but no redundancy.

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

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

Given the tool has only one parameter and no output schema, the description thoroughly covers input constraints, behavior, and output structure. It explains concurrent fetching, return fields, and error patterns, making it fully self-contained.

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 the single parameter 'domain'. The description adds critical constraints beyond the schema: 'Must be resolvable on the public internet; IPs, ports, paths, and protocol prefixes are rejected.' This enhances the agent's understanding of valid input.

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

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

The description clearly states the tool's purpose: 'Snapshot a domain's public web surface: robots.txt, sitemap.xml, and the home-page <head> metadata.' It uses specific verbs and resources, and distinguishes from siblings by referencing dossier_headers and dossier_redirects.

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

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

The description explicitly states when to use this tool ('SEO audits, content discovery, or verifying metadata before sharing') and when not to use it (for HTTP headers or redirects), providing alternative sibling tools.

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?

No annotations are provided, so the description carries the full burden. It discloses the protocol (TCP/43), library (whoiser), timeout (15s), return type (CheckResult), and a special case (not_applicable when registry refuses). This is good transparency.

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

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

The description is three concise sentences: first states purpose, second gives use case, third covers technical details. No wasted words, front-loaded with key 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?

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, usage, technical behavior, and edge cases. It is sufficient for an agent to select 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?

The only parameter 'domain' is fully described in the input schema with the same text as the tool description. Since schema coverage is 100%, the description adds no new meaning, so baseline 3 is appropriate.

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

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

The description clearly states it looks up WHOIS data for a domain, listing specific fields (registrar, creation date, expiry date, registry statuses). It is distinct from sibling tools like dns_lookup or dossier_dns.

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

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

The description explicitly says 'Use for ownership/expiry audit', providing clear context for when to use this tool. It does not explicitly state when not to use it, but the parameter description implies it is for domains, not IPs.

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?

Despite no annotations, the description fully discloses behavior: it queries ipinfo.io with a server-side token (never exposed), returns specific fields, and on failure returns an error string.

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?

Concise, front-loaded, and structured: purpose first, guidelines second, internals third, return format fourth, error handling last. Every sentence adds 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?

For a single-parameter tool with no output schema and no annotations, the description is complete: covers purpose, when to use, behavior, return fields, and error case.

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 has full coverage with description for 'ip'. Description adds examples (e.g., 1.2.3.4) and explicitly states 'Hostnames are not accepted', adding meaning beyond 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 'Resolve an IPv4 or IPv6 address to its geolocation, ASN, org name, and city/country', clearly indicating verb, resource, and output. It also distinguishes from siblings like dns_lookup and dossier_dns.

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 'Use when you need network or location context for a raw IP address; prefer dns_lookup or dossier_dns for hostname resolution', providing clear when-to-use and when-not-to-use guidance with 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?

With no annotations, the description fully carries the burden. It discloses that parsing is synchronous, local, uses ua-parser-js library, makes no external calls, and describes the exact output fields, including that unknown fields are empty strings.

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 are efficient and front-loaded with purpose. Every sentence adds value: purpose, usage guidance, behavioral details, and return format. No redundancy.

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

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

For a single-parameter tool with no output schema, the description is complete. It explains input, processing, and output format thoroughly. No gaps given the tool's simplicity.

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

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

Schema coverage is 100% and the schema already describes 'ua' as a string. The description adds context by specifying the input is a 'full User-Agent header value' and provides an example, which is helpful but not essential given the schema description.

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

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

The description clearly states the verb ('Parse') and resource ('User-Agent header string'), and specifies the output components (browser, OS, device type, rendering engine). It implicitly distinguishes from sibling tools (e.g., dns_lookup, ip_lookup) by stating it is entirely local parsing with no network calls.

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 when to use the tool ('when analyzing server logs or request headers') and what it does not do ('does not perform any network lookups'). This helps the agent select it over siblings that involve network operations.

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