drwho.me developer tools

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

With no annotations provided, the description carries the full burden and does an excellent job: it discloses use of Cloudflare DoH over HTTPS, 5s timeout, CNAME chain following, JSON array return format, and error return as a string. This goes well beyond basic read/write safety.

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 the core purpose, and each sentence earns its place: purpose, usage guidance, behavior and output format. 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?

The description covers the key operational context including transport, timeout, return format, error behavior, and alternative tools. However, the enum discrepancy means it is not fully accurate about what input values are accepted, so it loses one point.

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?

Although schema coverage is 100%, the description adds misleading information by listing SOA, CAA, and SRV as supported record types while the schema enum only allows A, AAAA, MX, TXT, NS, CNAME. This creates a conflict and undermines parameter clarity.

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 'Resolve' with a specific resource 'single DNS record type' and explicitly lists the supported record types. It also distinguishes itself from sibling tools by positioning it as a quick targeted lookup versus dossier_dns and 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?

The description provides explicit usage direction: 'Use for quick, targeted lookups of one record type; prefer dossier_dns for a full multi-type DNS audit in parallel, or dossier_full for a complete domain health check.' This names alternatives and states when not to use this tool.

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, the description discloses key behaviors: single OPTIONS request via fetch, 5s timeout, and the CheckResult return structure with success/error states. This covers safety and operational expectations adequately, though it could mention more about error scenarios.

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 and front-loaded, with the core action in the first sentence. It packs essential details (defaults, timeout, return format) without 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's simplicity, no annotations, and no output schema, the description is remarkably complete: it explains the request, timeout, defaults, and return format including error handling. It leaves no major gaps for an AI agent to misuse the 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?

Input schema descriptions already fully document all three parameters (domain, method, origin) including defaults and constraints, so the description adds little beyond contextualizing them for simulating a preflight. Baseline 3 applies due to high schema coverage.

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 sends a CORS preflight OPTIONS request and returns access-control-* response headers. It specifies the verb, target, and outcome, and distinguishes it from sibling tools focusing on DNS, TLS, etc.

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

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

It explicitly states when to use: verify CORS policy for a specific origin-method pair or check if a domain allows cross-origin requests. It also explains how to customize via origin and method parameters. However, it does not mention alternatives or exclusions, so it's not a full 5.

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 responsibility for behavioral disclosure. It goes beyond a basic description by detailing fallback behavior ('Queries crt.sh first, falls back to certspotter'), limits ('capped at 100 unique subdomains'), timeout ('10s timeout'), and return structure ('Returns a CheckResult with { subdomains[], wildcards[], certCount, source }'). This is rich contextual information that aids the agent in understanding the tool's behavior and potential side effects.

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 and front-loaded with the core purpose, followed by usage guidance, then behavioral details and return format. Every sentence conveys essential information without redundancy or fluff, making it highly efficient.

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 moderate complexity, absence of annotations, and lack of output schema, the description is remarkably complete. It covers the purpose, usage context, behavioral quirks, limits, timeout, and return shape. There are no significant gaps that would leave an agent uncertain about how to invoke or interpret the 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%, meaning the schema already fully documents the 'domain' parameter with constraints (e.g., 'Public FQDN, must be resolvable'). The tool description does not add additional parameter-level semantics beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function: 'Discover subdomains visible in Certificate Transparency logs.' It also distinguishes itself from the sibling tool dossier_full by labeling itself a 'Core dossier check' and explicitly recommending dossier_full for complete audits. This meets the criteria of specific verb+resource and sibling differentiation.

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 usage context: 'Use for attack-surface mapping; prefer dossier_full when running a complete audit.' This tells the agent when to use this tool and when to choose an alternative, satisfying the when/when-not requirement.

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 TXT queries), parallel execution, and 5-second timeout, and describes the return structure. This goes beyond a simple read-only hint and provides useful behavioral context, though it does not explicitly state 'read-only' or discuss any potential side effects (which are minimal here).

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 information-dense yet efficient. Every sentence serves a purpose: core action, usage guidance, technical execution details, and return format. It is well-structured and front-loaded with the primary purpose, with 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?

There is no output schema, so the description correctly explains the return value (`CheckResult` with `status`, `found`, `notFound`, and `error`). It also covers edge cases (common selectors, timeout behavior) and input constraints. This is a complete picture for an agent to confidently invoke the 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 schema already covers both parameters at 100%, but the description adds meaningful context: it explains how the domain is combined with selector names to form the DNS query (`<selector>._domainkey.<domain>`), and describes the default selector set. This enhances understanding beyond the schema's basic field descriptions.

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 ('Probe') and resource ('a domain's DKIM public keys') and explains the exact DNS query pattern. It clearly distinguishes this from sibling dossier_* tools by focusing on DKIM key discovery, making its 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?

Provides explicit use cases: 'verify signing configuration or discover active selectors' and gives parameter guidance ('supply selectors when you know the ESP's selector, or omit to probe six common selectors'). However, it does not explicitly mention when to use an alternative tool (e.g., dossier_dns for general DNS lookup), so it lacks a clear exclusion or alternative comparison.

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 significant behavioral details: queries via Cloudflare DoH with a 5-second timeout, parses tag=value pairs, and returns a structured CheckResult with success/error shapes. This is comprehensive, though it doesn't discuss potential errors or DNS failure specifics beyond returning an error reason.

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 approximately four sentences, front-loaded with the primary action, and each sentence contributes essential information (query method, timeout, parsing, return format). No redundant or filler content.

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 explains the return payload details (status, raw, tags) and failure mode, which is usually sufficient. It could additionally mention what happens when no DMARC record exists, but the error reason field covers that. Overall it's complete enough for an agent to safely invoke 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?

The input schema provides 100% coverage of the 'domain' parameter, including constraints (public FQDN, no IPs/ports). The description adds a minor implication that the domain is used to construct the _dmarc DNS query, but this is a natural extension of the schema. Baseline 3 is appropriate since the schema already handles the parameter meaning.

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 function: 'Retrieve and parse a domain's DMARC policy from its _dmarc.<domain> TXT record, returning all tags.' It uses a specific verb ('Retrieve and parse') and resource (DMARC record), and distinguishes itself from siblings by noting 'pair with 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?

It gives explicit usage context: 'Use to audit email authentication policy, verify the p (policy) and rua (reporting) settings, or confirm alignment mode.' It also names complementary tools (dossier_spf, dossier_dkim), guiding the agent on when to use which tool.

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 carries the full transparency burden and excels: it discloses that six Cloudflare DoH queries fire concurrently, that each has a 5-second timeout, and that the result is a discriminated union with explicit success/error shapes. This gives the agent important execution context beyond the schema.

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, each purposeful: purpose, usage/alternatives, and internal behavior/return format. Zero redundancy, and the most decision-relevant information (what and when) 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?

For a single-parameter tool with no output schema, this description is fully complete: it covers purpose, usage timing, internal mechanics (parallel queries, timeout), return shape (including error reason), and alternative tools. The agent can confidently invoke it without needing additional 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 schema already provides 100% coverage with a detailed description of the domain parameter, so the description adds no additional parameter-level guidance. Per the rule for high schema coverage, a baseline of 3 is appropriate; the description does not introduce new constraints 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 uses a specific verb ('Fetch') and resource ('domain's full DNS profile'), lists the record types (A, AAAA, NS, SOA, CAA, TXT), and explicitly distinguishes itself from siblings (dns_lookup for single record type, dossier_full for all checks). This makes 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?

It explicitly states when to use this tool ('Use as the first step of a domain audit or when you need a comprehensive DNS snapshot in one call') and provides clear alternatives ('prefer dns_lookup for a single record type, or dossier_full for all 10 dossier checks at once'). This fully addresses when/why selection.

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 carries the full burden of behavioral disclosure. It reveals the query mechanism ('Fires Cloudflare DoH DS and DNSKEY queries with DO=1'), timeout ('8s timeout'), and return format ('CheckResult discriminated union with { dnssecEnabled, adFlag, ds[], dnskey[] }'). It lacks explicit statements about failure handling, but for a read-only check this is substantial 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 sentences, front-loaded with purpose, then usage/alternatives, then operational details. Every sentence contributes value without redundancy or fluff.

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 remarkably complete: it explains purpose, alternatives, exact queries, timeout, and return structure. It also situates the tool within the sibling set, covering all necessary context for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with the 'domain' parameter fully defined (public FQDN, constraints). The description adds no new parameter-level semantics beyond restating 'domain' in context. Per the rubric, high schema coverage gives a baseline of 3, and this description does not exceed it.

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 function: 'Verify DNSSEC chain-of-trust for a domain (DS, DNSKEY, AD flag)'. It identifies the resource (domain) and specific protocol elements, distinguishing it from siblings by explicitly naming dossier_dns and dossier_full as alternatives for different needs.

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

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

It provides explicit when-to-use guidance: 'Use to confirm the zone is signed and resolvers accept the chain' and gives alternatives: 'prefer dossier_dns for raw record types or dossier_full for the complete audit'. This covers both usage context and tool selection.

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 concurrency (parallel), transport (Cloudflare DoH or direct HTTPS), per-check timeout (5 s), billing behavior (counts as ONE paywall call), and return format (JSON keyed by check id with CheckResult discriminated union). With no annotations, this fully covers the behavioral burden.

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 compact and front-loaded with the core purpose. Each sentence contributes unique value: check list, usage context, billing note, execution mechanics, and return structure. No redundancy or 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?

Given the simple schema (1 param) and no output schema, the description covers all necessary context: what it does, when to use it, how it executes, what it returns, and billing implications. It fully equips an agent to select and invoke 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 schema provides 100% coverage of the single domain parameter, including format and rejection rules. The description adds no extra parameter-specific meaning, so the baseline of 3 applies.

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

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

The description clearly states the tool runs all 10 specific Domain Dossier checks in parallel and returns them in a single response. It lists the exact checks, distinguishing it from the individual dossier_* sibling 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?

Explicitly says to use when a comprehensive domain health snapshot is needed and to prefer individual dossier_* tools for single focused checks. This provides clear when/when-not guidance and names the alternative.

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 behavioral details: 'Single GET via fetch, 5 s timeout, captures raw response headers before any redirect is followed.' It also describes the return structure on success and failure, including the securityAudit array format. No contradictory annotations exist; this exceeds the burden for an unannotated tool.

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, front-loaded with the core purpose, and every sentence adds value: purpose, use case with alternative, and behavioral/return details. No redundant phrasing or filler; it is an exemplar of concise, structured documentation.

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 having no output schema, the description documents the return shape (CheckResult with status, headers, securityAudit) and error case. It covers the tool's use case, HTTP method, timeout, redirect handling, and related tool, making it fully self-contained for a single-parameter check 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% for the single 'domain' parameter, which already includes a clear description and validation rules. The tool description adds minimal parameter-specific meaning beyond the schema, as it only implies the domain is used in the URL. Baseline score of 3 applies because the description does not need to compensate for schema gaps.

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 and resource: 'Fetch https://<domain>/ and return all HTTP response headers, with an audit highlighting missing or misconfigured security headers.' This clearly identifies the tool's function and distinguishes it from siblings like dossier_redirects by explicitly naming the alternative for redirect tracing.

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: 'Use to review CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy.' It also provides an exclusion: 'for redirect tracing use dossier_redirects instead.' This gives clear guidance on appropriate usage versus 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 discloses the resolution steps, fetch URL location, 10s timeout, return type (CheckResult), and the not_applicable edge case. This provides rich behavioral context beyond a simple action statement.

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, each earning its place: purpose, process, and return behavior. Information is front-loaded with the core purpose, making it easy to scan.

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

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

For a one-parameter tool with no output schema, the description covers purpose, usage, resolution process, timeout, return type, and special case (no MTA-STS TXT). It is self-sufficient and 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 the schema description already explains that the domain must be a public FQDN and rejects IPs, ports, paths, and protocol prefixes. The description adds nothing about parameters, 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?

The description uses a specific verb ('Fetch and validate') and names the resource ('MTA-STS policy'), with explicit scope for mode, mx, max_age, and policy id. It clearly distinguishes from sibling dossier tools by focusing specifically on MTA-STS.

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?

States 'Use to confirm inbound SMTP is locked to TLS for this domain,' providing a clear use case. It does not explicitly list alternatives or when-not-to-use, but the MTA-STS focus differentiates it from siblings.

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 discloses behavior: it queries Cloudflare DoH, follows CNAME aliases, has a 5s timeout, and returns a CheckResult discriminated union with exact success/error shapes.

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?

Well-structured and front-loaded: purpose first, then usage guidance, implementation details, and return format. Each sentence provides distinct 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 1-param tool with no annotations or output schema, the description covers purpose, usage, behavior, and return format, making it self-contained and sufficient for correct 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?

The schema already covers the 'domain' parameter with 100% coverage, and the description adds no additional parameter-level meaning beyond using 'domain' as the lookup target; 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 clearly states 'Look up a domain's MX (mail exchanger) records and return them sorted ascending by priority' and explicitly differentiates from dns_lookup with type=MX, making its purpose specific and distinct among siblings.

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

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

Provides explicit usage guidance: 'Use when verifying inbound-mail routing or as a precursor to SPF or DMARC checks' and names an alternative (dns_lookup) for raw DNS answers, satisfying the when/when-not criterion.

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 and does so admirably: it discloses the 10-hop limit, that it follows Location headers with fetch and no auto-redirect, the 5-second per-hop timeout, and the exact success/error return shape. This goes well beyond typical descriptions.

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

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

Three dense sentences: purpose, use cases, and behavior+return format. Every sentence earns its place, and the most important 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 description fully compensates for the lack of an output schema by explicitly describing the CheckResult shape. It also covers limits, timeout, and failure behavior, making it complete for a network diagnostic 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 schema already covers the domain parameter fully (100% coverage), so baseline is 3. The description adds meaning by specifying that the redirect chain starts from https://<domain>/, which clarifies how the parameter is used even though the schema describes domain format.

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 traces the full HTTP redirect chain starting from https://<domain>/, which is a specific verb+resource combination. It distinguishes itself from sibling dossier tools by focusing on HTTP redirects rather than DNS, TLS, or headers.

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

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

The description gives explicit use cases: debug redirect loops, verify HTTP→HTTPS upgrades, or audit link shorteners. It doesn't mention alternatives or when not to use, but the use cases are clear enough for a sibling tool 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?

No annotations provided, but the description fully discloses behavior: fetches TXT records via Cloudflare DoH with 5s timeout, locates the v=spf1 record, parses all mechanisms, and specifies success/error return structures. This exceeds the burden given lack of annotations.

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 a single dense paragraph but well-structured: purpose, use cases, alternatives, behavior, and return format. Each sentence earns its place; no fluff, though slightly longer than strictly necessary.

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 exceptionally complete: it explains network behavior (DoH, timeout), parsing logic, and the exact CheckResult shape. This covers all necessary context for an agent to invoke 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% (single 'domain' parameter fully documented). The description does not add extra param details beyond the schema, but this is unnecessary given high coverage, 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 identifies the tool's purpose: 'Retrieve and parse a domain's SPF record, decomposing it into mechanisms and qualifiers.' It distinguishes itself from siblings by mentioning dossier_dmarc for full email-auth coverage and dns_lookup for raw TXT records.

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: 'verify email sender policy, debug delivery failures, or check the 10-lookup limit.' Provides alternatives: 'pair with dossier_dmarc for full email-auth coverage, or use dns_lookup with type=TXT for the raw record only.'

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 carries the full burden. It discloses the TLS handshake, 5s timeout, leaf extraction, and the exact CheckResult structure for success and failure. Minor inconsistency: mentions 'chain details' but only lists leaf certificate fields, slightly confusing but still transparent about the overall behavior.

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 and structured with a purpose statement, usage, behavior, and return format. The opening 'Core dossier check:' is a minor filler, and the sentence about chain details vs leaf could be tightened, but overall it's well-organized and every substantive point 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?

Without an output schema, the description compensates by detailing the success and failure return shapes. It provides timeout and handshake context, making it sufficiently complete for a single-parameter tool. It could clarify what 'chain details' includes, but overall coverage is strong.

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 schema already describing the domain parameter and its constraints (resolvable, no IPs/ports/paths). The description adds no new parameter semantics beyond reinforcing that the input is a domain, so it meets the baseline but doesn't exceed it.

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 the TLS certificate on port 443, with specific outputs like chain details and validity period. It distinguishes itself from sibling tools by specifying 'not a full cipher-suite scanner', making its scope 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?

It provides explicit use cases (verify expiry, issuer, SANs, detect self-signed certs) and an exclusion (not a full cipher-suite scanner). While it doesn't name alternative tools explicitly, the context of sibling dossier tools and the exclusion offer adequate guidance for when to use this tool.

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 resolution method (Cloudflare DoH), timeout (5s), return type (CheckResult), and an edge case (not_applicable when no record). This is thorough and transparent for a read-only lookup tool.

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, followed by behavioral details. Every sentence contributes value with no waste, achieving high clarity in minimal space.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, method, timeout, and a key edge case. It does not fully describe the CheckResult structure, but for this type of check, the provided information is sufficient for an agent to decide and invoke appropriately.

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 parameter description already specifies domain format and constraints. The description adds a minor detail (how domain is used in the DNS query) but does not significantly enhance parameter understanding beyond the schema, 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 the tool looks up a domain's TLS-RPT policy, with a specific verb ('look up') and resource ('domain's TLS-RPT policy'). It distinguishes from siblings by specifying the exact DNS record (_smtp._tls.<domain> TXT) and the use case (confirming SMTP TLS failure reporting).

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

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

It provides a clear use case: 'Use to confirm the domain receives reports of SMTP-TLS failures.' This gives context for when to use the tool. It does not explicitly mention alternatives or exclusions, but the specificity of the purpose makes the usage scenario 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?

No annotations are provided, so the description carries the full burden. It discloses the exact URLs fetched (/, /robots.txt, /sitemap.xml), concurrency, timeout (5s each), parsing method (lightweight HTML parser), and the full return structure including error reasons. This goes beyond minimal disclosure.

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

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

The description is compact yet information-dense, front-loading purpose, then use cases, then technical details. Every sentence adds value without redundancy or fluff.

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 that makes multiple network requests, the description thoroughly covers the behavior (concurrency, timeouts, parsing), the return shape (CheckResult with status, meta, robots, sitemapPresent, error), and the intended use cases. No output schema exists, but the inline return description compensates fully.

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's single parameter is well documented (FQDN, public resolvability, rejection of IPs/ports/paths/prefixes). The description adds no further parameter information, so the baseline 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?

Description starts with 'Core dossier check: Snapshot a domain's public web surface' and enumerates exactly what is fetched (robots.txt, sitemap.xml, home-page <head> metadata). It also references sibling tools (dossier_headers, dossier_redirects) for other concerns, clearly distinguishing its 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 states use cases: 'Use for SEO audits, content discovery, or verifying metadata before sharing' and names alternatives: 'for HTTP headers use dossier_headers, for redirect behavior use dossier_redirects.' This gives the agent clear invocation 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?

Even with no annotations, the description richly discloses behavior: it uses the whoiser library over TCP/43, has a 15s timeout, returns a CheckResult, and reports not_applicable when registries refuse/redact queries. This is significant behavioral context beyond what the schema or annotations offer.

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, each earning its place: the first states the core function, the second gives the use case, and the third covers implementation details and edge behavior. No fluff 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?

Despite having only one parameter and no output schema, the description covers what the tool does, when to use it, how it executes (library, protocol, timeout), and what happens on failure (not_applicable). This is complete for a WHOIS lookup tool, especially considering the sibling 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 already provides 100% coverage of the 'domain' parameter, including constraints like 'Must be resolvable' and rejected formats. The description adds no new parameter-specific meaning beyond restating the domain focus, so the baseline of 3 applies.

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

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

The description states a specific action ('Look up the registrar, creation date, expiry date, and registry statuses') on a clear resource ('a domain'), and it distinguishes itself from sibling tools by focusing on WHOIS data. The verb + resource + listed outputs provide unambiguous purpose.

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

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

The description gives a clear use case: 'Use for ownership/expiry audit.' It also positions it as a 'Core dossier check,' implying it is foundational. However, it does not explicitly mention when to avoid this tool or mention alternatives (e.g., dossier_full), so it stops short of a 5.

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 behavioral disclosure. It discloses the external service (ipinfo.io), the server-side token (never exposed to callers), the return format (JSON with listed fields), and failure behavior (returns an error string). This is excellent 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 compact and front-loaded with the core purpose ('Context lookup: Resolve...'). Every sentence adds value: usage guidance, alternative tools, security note, return format, and failure mode. No filler or 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 having no output schema, the description clearly lists the expected return fields (ip, city, region, country, org, loc, timezone) and failure behavior. This is complete for an agent to know how to invoke the tool 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?

The sole parameter 'ip' is already fully described in the schema (IPv4/IPv6, examples, hostnames not accepted). The description adds context about what the lookup returns (geolocation, ASN, org) but does not add substantially new parameter detail. Baseline 3 is appropriate given 100% schema coverage.

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 resolves an IPv4 or IPv6 address to geolocation, ASN, org, and city/country. It explicitly distinguishes from sibling tools by noting that dns_lookup and dossier_dns handle hostname resolution rather than raw IP lookup.

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 ('Use when you need network or location context for a raw IP address') and when-not-to-use with alternatives ('prefer dns_lookup or dossier_dns for hostname resolution'). This is exactly the kind of guidance an agent needs to choose correctly.

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. It discloses local, synchronous operation via ua-parser-js, no external calls, and that unknown fields resolve to empty strings. This gives agents a clear behavioral model without hidden side effects.

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, each with a distinct job: purpose, usage, and behavior/output. No filler or repetition of schema details; front-loaded with the core action.

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, local parsing tool, the description covers purpose, usage context, behavioral traits, and returned fields. It is complete enough for an agent to invoke correctly without an output schema.

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 a detailed description of the 'ua' parameter including a concrete example. The description's reference to a 'raw UA string' adds minimal new meaning, so it stays at the baseline for well-covered schemas.

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 a specific verb and resource: 'Parse a User-Agent header string into structured browser, OS, device type, and rendering-engine components.' It differentiates from sibling network tools by explicitly noting 'does not perform any network lookups — entirely local parsing.'

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 advises when to use the tool ('when analysing server logs or request headers') and clarifies what it does not do ('does not perform any network lookups'), which helps exclude network-oriented siblings. However, it does not name specific alternative tools, so usage guidance is strong but not exhaustive.

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