drwho.me

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

Beyond the readOnlyHint annotation, the description reveals important behaviors: acceptance of standard and URL-safe alphabets, tolerance for missing padding and line breaks, failure on invalid input, refusal to return binary data, and local execution. These details meaningfully inform an agent's expectations about edge cases and limitations.

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 primary action. Each sentence earns its place by covering input formats, failure conditions, and execution context without any redundant filler.

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

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

For a simple one-parameter read-only tool, the description covers everything an agent needs: what the tool does, what input formats are accepted, when it fails, and what it will not return. The absence of an output schema is mitigated because the decoded UTF-8 text is clearly implied.

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 only describes the parameter as 'Base64 or base64url string,' but the description adds valuable format semantics: standard and URL-safe alphabets, optional padding, and line break handling. This enriches the parameter's meaning beyond the schema's 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 states a specific verb and resource: 'Decode base64 to UTF-8 text.' This clearly differentiates it from base64_encode and other decoder siblings like url_decode and jwt_decode, leaving no ambiguity about what the tool does.

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 context for when this tool is appropriate: decoding base64 input into UTF-8 text. It also provides a de facto exclusion by stating that binary data is not returned, implying the tool should not be used when binary output is needed. However, it does not explicitly name alternative tools or provide explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the description correctly reinforces that this is a pure function. It adds the valuable detail that it 'Runs locally', implying no network calls or external dependencies. The description also clarifies padding behavior for url_safe, which is beyond what annotations cover. No contradiction found.

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, optional variant, and execution context. Information is front-loaded and there is zero filler.

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

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

For a simple two-parameter encode tool with a trivial string output, the description covers purpose, behavior (local, deterministic), parameter options, and return type. No critical information is missing that an agent would need to 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 both 'text' and 'url_safe' already explained. The description adds a JWT use-case reference and clarifies the alphabet substitution, but these are minor enhancements over the schema. Baseline of 3 is appropriate since the schema already carries the main 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 states a specific verb ('Encode'), a resource ('UTF-8 text'), and the target format ('base64'), with a clear differentiation from sibling base64_decode. It also mentions the URL-safe variant, leaving no ambiguity about what the tool does.

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 context for when to use the url_safe parameter ('as used in JSON Web Tokens') and implies this is the encode counterpart to base64_decode. It does not explicitly state when not to use it, but the purpose is so obvious that exclusion is unnecessary. Slight deduction for not mentioning that this is the only encoding tool for general text.

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

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

Beyond the readOnlyHint=true and openWorldHint=true annotations, the description adds meaningful runtime behavior: 'Queries Cloudflare DNS-over-HTTPS' identifies the data source, and the return format is specified with a notable semantic detail — 'an empty array means the name exists but has no record of that type.' It stops short of clarifying error behavior for a nonexistent name (e.g., NXDOMAIN), but the added transparency is substantial.

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 four sentences, each with a distinct job: what it does, when to use it vs. the alternative, the backend, and the return format. There is no filler or repetition of the schema, and the most decision-relevant scoping guidance 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 simple read-only two-parameter tool with 100% schema coverage, the description covers the essentials: supported types, valid name forms, backend, return shape, and empty-result semantics. The only notable gap is what happens when the queried name itself does not exist (an error vs. a distinct empty response), but overall the description is complete enough for correct invocation.

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

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

Schema description coverage is 100%: both 'name' and 'type' already have explanatory descriptions in the schema, so the baseline is 3. The tool description adds only minor context, such as 'names such as _dmarc.example.com,' which reinforces the schema's example but does not meaningfully deepen parameter understanding beyond 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 opens with a specific verb and resource: 'Resolve one DNS record type ... for a name and return the raw answers.' It enumerates every supported record type (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, SRV) and explicitly separates itself from the sibling dossier_dns, leaving no ambiguity about what this tool does.

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 guidance is explicit: 'Use for a quick, targeted lookup, including on subdomains and names such as _dmarc.example.com; prefer dossier_dns for a domain's main records in one call.' This directly tells the agent both the best context for this tool and the alternative to choose instead, which is exactly the decision guidance needed.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral detail beyond that: it defines the full status field contract ({status:"ok", data, fetchedAt}, not_applicable, timeout, error), clarifies that a missing robots.txt is treated as data rather than an error, and mentions the one-fetch/10s timeout. This gives the agent precise knowledge of what to expect in responses, going well beyond the annotation flags.

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 well-structured and front-loaded with the core purpose, then explains edge-case behavior and output format. Every sentence contributes unique value: the crawler list, the 'missing file is data' nuance, the timeout, and the status enum. It is slightly long but not verbose; the detail is justified given the complexity of the output contract.

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 complexity (multiple crawlers, conditional statuses, edge cases) and the absence of an output schema, the description fully specifies the return structure and how to interpret each status. It also clarifies the semantics of 'not_applicable' versus 'error'. An agent has all necessary information to call the tool and handle results correctly.

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

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

Schema description coverage is 100% for the single parameter 'domain', which is already fully documented in the schema (including rejections of IP addresses, ports, paths, and protocol prefixes). The description adds no further parameter-specific guidance beyond what the schema already provides, 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 verb ('Report') and resource ('domain's robots.txt') and enumerates the exact crawlers covered (GPTBot, ClaudeBot, Google-Extended, etc.). It clearly distinguishes itself from siblings like dossier_llms_txt and dossier_web_surface by focusing on AI crawler policy, so an agent can select it without opening the schema.

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

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

The description explicitly says 'Use to answer whether a site lets AI models train on or retrieve its content,' giving clear context for when to invoke it. It also explains the behavior for missing robots.txt ('a missing robots.txt is data, not an error'), which indirectly sets expectations. It does not name alternative tools for comparison, but the use case is specific enough that siblings like dossier_llms_txt are obviously different. Lacks explicit 'when-not-to-use' but remains 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses operational details: it sends exactly one OPTIONS request, has a 5-second timeout, targets https://<domain>/, and returns a status field with specific success, not_applicable, timeout, and error shapes. It also tells the agent how to interpret the result, which is valuable behavioral context.

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 information-dense: purpose, request behavior, timeout, response envelope, and result interpretation in three sentences. It is front-loaded with the action, and every sentence earns its place.

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

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

With no output schema, the description fully documents the response format and status variants, including field names and fallback behaviors. Combined with complete parameter coverage in the schema, an agent has everything it needs to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the schema already explains domain, method, and origin meaning and defaults. The description adds only a general reference to 'given origin and method' without new details, 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?

The description opens with a specific verb ('Send a CORS preflight') and a clear resource (https://<domain>/), then explains the purpose: checking whether a site accepts cross-origin requests from a given origin and method. It differentiates itself from sibling tools like dossier_headers by focusing on CORS preflight behavior and access-control-* 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 explicitly states when to use the tool: 'Use to check whether a site accepts cross-origin requests from a given origin and method.' It also provides interpretation guidance for the not_applicable and error statuses. It doesn't state exclusions or alternatives, but no close sibling requires such a contrast.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds substantial behavior beyond that: the two-source query chain with fallback, the 100-name cap, the 10-second timeout, the caveat that a log name is not proof the host still exists, and the full status response contract. It even tells the agent how to interpret not_applicable versus error, which is critical for correct action.

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 front-loads the core purpose in the first sentence, then packs each subsequent sentence with non-redundant operational detail: fallback behavior, limits, interpretation caveat, and return-status semantics. Every sentence earns its place; there is no filler or repetition of schema or annotation 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, read-only tool with no output schema, the description is unusually complete. It covers the data source, failure fallback, scaling caps, timeout, and a full enumeration of possible status values with their semantic meanings. An agent has everything needed to invoke the tool and interpret the result correctly.

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

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

Schema description coverage is 100%, so the schema fully documents the domain parameter, including what is rejected. The tool description adds nothing about the parameter itself, which is fine because the schema already carries that burden. Per the baseline rule, a 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'List subdomains of a domain that appear in Certificate Transparency logs.' This clearly distinguishes it from sibling DNS and web-surface tools by naming the data source (CT logs) and the exact output (subdomain names). The additional 'map what hosts a domain has exposed' phrasing reinforces the intent without ambiguity.

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

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

The description states a concrete use case: 'Use to map what hosts a domain has exposed through the certificates issued for it.' It also clarifies behavioral context (fallback from crt.sh to certspotter, caps, timeout) that helps an agent decide when this is appropriate. It does not explicitly name alternatives or exclusion criteria, but the use case is clear enough for routing among the 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?

Beyond readOnlyHint/openWorldHint, the description discloses exact status contract, the parallel Cloudflare DNS-over-HTTPS mechanism, and the caveat that empty results are not proof of absence. Treating not_applicable as a finding and error as unknown is exactly the operational nuance an agent needs.

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 dense but efficient, front-loading the core lookup and then covering selector semantics, result statuses, and interpretation. Every sentence contributes useful guidance 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?

With no output schema, the description fully documents the JSON status variants and their meanings. Combined with schema-covered parameters and safety annotations, nothing critical is missing for invoking this tool correctly.

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

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

Schema coverage is already 100%, but the description adds beyond the schema by explaining the built-in selector list targets large mail providers and that a selector not on the list will not be found. This helps agents decide whether to supply selectors and how to avoid false negatives.

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 ('Probe') and resource ('DKIM public keys at <selector>._domainkey.<domain>'), which is enough to separate it from generic DNS siblings like dns_lookup and dossier_dns. It also adds a distinctive behavior, distinguishing absent vs unresolved selectors.

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 context for using the tool, including when to omit selectors and how to interpret an empty result. It does not explicitly name alternatives or when-not-to-use conditions, but the use case is unambiguous enough for an agent.

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 substantial behavior beyond the readOnlyHint/openWorldHint annotations: it names the backend (Cloudflare DNS-over-HTTPS), the 5-second timeout, and the complete JSON status contract with ok, not_applicable, timeout, and error variants. It also tells the agent how to interpret not_applicable versus error, which is exactly the kind of behavioral nuance annotations cannot express.

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

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

Every sentence earns its place: purpose, use case, infrastructure, timeout, and return-status semantics are packed into four tight sentences with no filler. The most important information is front-loaded and the status contract is clearly structured.

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 that there is no output schema, the description fully compensates by specifying the exact status shapes and interpretation guidance. It covers success, absence, timeout, and error, and lists the parsed tags, making the tool self-sufficient for an agent to invoke and understand the result.

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

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

Schema description coverage is 100% and the parameter is simple. The description adds value by clarifying that the supplied domain is the base domain to which '_dmarc.' is prepended, and reinforces the accepted format via example.com. This goes slightly beyond the schema's rejection list, so a 4 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 states a specific verb and resource: 'Find and parse the DMARC policy at _dmarc.<domain> into its tags'. It also names the exact policy tags and the security question it answers (rejected, quarantined, reported), which distinguishes it from sibling DNS tools like dns_lookup, dossier_spf, and dossier_dkim.

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 see whether spoofed mail is rejected, quarantined or only reported'. However, it does not explicitly contrast it with alternative tools such as dossier_spf or dossier_dkim, nor state when NOT to use it, so it falls short of 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?

Goes far beyond the readOnlyHint and openWorldHint annotations by disclosing the exact execution model (six parallel Cloudflare DoH queries, 5 s timeout each) and the complete status return contract (ok, not_applicable, timeout, error) with guidance on interpretation. This is rich behavioral context that annotations alone do not provide.

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 but every sentence earns its place: purpose, usage routing, execution details, return format, and interpretation guidance. It is front-loaded with the primary action and efficiently organized, with 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?

For a multi-record-type tool with no output schema, the description fully covers the return contract and error semantics, including how to treat each status. It also provides sufficient operational context (timeouts, parallelism) and routing to alternatives. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema description for 'domain' is thorough (public domain name, rejects IPs/ports/paths). The tool description does not add parameter-specific semantics beyond restating the resource scope. With full schema coverage, a baseline of 3 is appropriate; no extra value is added by the 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 states a specific verb ('fetch'), a precise resource (domain's A, AAAA, NS, SOA, CAA and TXT records), and enumerates the record types. It clearly distinguishes itself from dns_lookup by naming the alternative and its use case, so an agent can select it unambiguously.

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 instructs when to use this tool ('first step of a DNS review') and when to prefer an alternative ('prefer dns_lookup for a single record type or for MX, CNAME and SRV'). This leaves no ambiguity about selection criteria and names the sibling explicitly.

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 operational behavior beyond the annotations: it queries Cloudflare DNS-over-HTTPS with DO=1, an 8-second timeout, and defines all possible JSON response statuses (ok, not_applicable, timeout, error). It also explains how to interpret not_applicable and error. The readOnlyHint and openWorldHint annotations are consistent, and the description adds meaningful behavioral 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?

The description is dense but each sentence serves a purpose: purpose, operational details, and response contract. It is front-loaded with the primary function and avoids filler.

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

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

The description fully defines the response envelope and status handling, and infers the contents of data from the purpose statement (DS/DNSKEY records and AD flag). However, it does not explicitly enumerate the fields inside the data object, leaving a minor gap given there is no 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?

The input schema already fully describes the single domain parameter and its validation rules, so the description need not add more. It doesn't repeat or expand on parameter semantics, but schema coverage is 100%, which meets the 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 title and description clearly state a specific action: checking whether a domain's zone is signed with DNSSEC and validating DS, DNSKEY, and the AD flag. It distinguishes itself from sibling tools like dossier_dns and dns_lookup by focusing on DNSSEC validation rather than general DNS 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?

The description provides clear context about what the tool does and when it is relevant (for DNSSEC validation checks), but it does not explicitly name alternatives or state when not to use it. The context is unambiguous, though no exclusions or alternative tool mentions are provided.

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

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

Beyond the annotations (readOnlyHint=true, openWorldHint=true), the description adds meaningful operational detail: one GET, 5 s timeout, final URL after redirects, headers as served, and the full status envelope with ok/not_applicable/timeout/error variants. This gives the agent accurate expectations for side effects and failure modes.

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?

Every sentence carries useful information: purpose, what is returned, timeout, sibling alternative, and response status semantics. The purpose is front-loaded and the response format is compactly documented, making the description dense yet easily parseable.

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 well-documented parameter, no output schema, and read-only/external-safe annotations, this description covers what an agent needs: what headers are returned, how redirects are handled, timeout behavior, and how to interpret each status value. It also points to the sibling for redirect hops, making the surrounding toolset context clear.

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 for the single parameter, including rejecting IPs, ports, paths, and protocol prefixes. The description adds no new parameter-level meaning—it references <domain> but does not clarify or extend beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Fetch https://<domain>/ and return every response header," and lists the exact security headers an agent should look for. It also explicitly distinguishes itself from dossier_redirects by noting that redirect hops are handled there, so there is no sibling ambiguity.

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

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

The description clearly states when to use the tool: to review response security headers, and gives an explicit alternative: "For the redirect hops themselves use dossier_redirects." It also provides decision guidance on interpreting results, such as "Treat not_applicable as a finding and error as unknown," which helps the agent decide how to consume the output.

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 annotations only declare readOnlyHint and openWorldHint, so the description carries the behavioral burden. It fully discloses the fetch behavior, 10 s timeout, validation criteria, and every status variant including the important guidance to treat not_applicable as a finding and error as unknown.

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, front-loaded with the core purpose, and every sentence earns its place, especially the response format and semantic interpretation. Despite covering multiple statuses and edge cases, it remains easy to parse.

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 compensates by enumerating all possible return shapes and their meanings. It also documents the validation criteria and timeout, so an agent has everything needed to call it correctly and interpret the result.

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

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

The single parameter is fully documented in the schema, including an example and what is rejected. The description adds no parameter-specific detail beyond what the schema already states, 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?

States a specific resource (llms.txt), the exact action (check whether a domain publishes it), and clarifies what does not count, namely a catch-all HTML page. This clearly distinguishes it from related dossier tools like dossier_web_surface or dossier_security_txt.

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

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

Gives clear context on when the tool is appropriate: verifying llms.txt presence on a domain. It explains the acceptance criteria but does not explicitly name alternatives or state when not to use it, so it stops just 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?

The description thoroughly explains behavior beyond annotations: it resolves a TXT record, fetches from a well-known URL, includes a timeout, and defines four possible return statuses with their semantics. This is rich operational detail that annotations (readOnlyHint, openWorldHint) do not cover.

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, covering the process, protocol, timeout, and return formats in a few sentences. It is front-loaded with the key action and outcome, making it easy for an agent to parse quickly.

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 a single parameter fully documented, annotations for safety, and no output schema, so the description must define return values—and it does comprehensively. The agent has everything needed to call and interpret the result.

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

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

The schema already documents the domain parameter at 100% coverage, including constraints on IP addresses and paths. The description adds no new parameter-specific detail, so a baseline score of 3 is appropriate given the schema's completeness.

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 validates a domain's MTA-STS policy, specifying the exact records and endpoints involved. It distinguishes itself from sibling DNS/email security tools by focusing specifically on MTA-STS policy validation.

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 explains the tool's purpose for confirming TLS delivery requirements and lists distinct return statuses that help the agent interpret results. However, it does not explicitly state when not to use this tool or name alternative siblings for similar tasks.

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 though readOnlyHint and openWorldHint are already present, the description adds valuable behavior: it names the Cloudflare DNS-over-HTTPS source, the 5-second timeout, the exact status response variants, and how to interpret not_applicable vs error. This goes well beyond the 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?

The description is front-loaded with the core purpose and use case, then compactly covers source, timeout, response shapes, and interpretation. Every sentence adds needed information with 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?

With only one parameter and no output schema, the description fully compensates: it documents success, absence, timeout, and error response shapes, and clarifies operational semantics. An agent has what it needs to call the tool and interpret results correctly.

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

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

Schema coverage is 100%, and the schema already explains that domain accepts public names and rejects IPs, ports, paths, and protocol prefixes. The tool description adds no additional parameter-level meaning, so the baseline 3 applies.

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

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

The description states an exact verb and resource: it lists a domain's MX records sorted by priority. The phrase 'see where a domain's inbound mail goes' and the linkage to SPF/DMARC distinguish it from generic sibling tools 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?

It gives clear when-to-use guidance: use it to inspect inbound mail routing or before checking SPF and DMARC. However, it does not explicitly name alternatives or state when not to use it, so the guidance stops short of a full when/when-not 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses the full response envelope (status field with ok, not_applicable, timeout, error), explains how to interpret each status (treat not_applicable as a finding, error as unknown), and mentions the per-hop timeout. This is rich behavioral context that exceeds annotation-level info.

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, followed by use cases, timeout, and response format. Every sentence adds value—there is no fluff. The JSON response structure is embedded in a code block, making it immediately parsable, and the overall length is justified by the amount of behavioral detail.

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 read-only tool with one parameter and no output schema, the description covers purpose, usage, behavior, and error interpretation. It hints at the data structure ('one entry per hop with its status code and target') but does not specify the exact fields of the 'data' object. Given the absence of an output schema, this is a minor gap, but the description is otherwise complete enough for an agent to call 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 of the 'domain' parameter (e.g., public domain, rejects IPs/ports/paths). The tool description adds the nuance that the domain is used with an https:// prefix, which is a minor semantic addition. Schema coverage is 100%, 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?

The description clearly states the action ('Trace the redirect chain'), the resource (from https://<domain>/), and the output (one entry per hop with status code and target, up to 10 hops). This is specific and distinguishes it from sibling tools like dossier_dns or dossier_headers, which serve different purposes.

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 names two use cases: 'debug redirect loops' and 'confirm an HTTP to HTTPS or apex to www redirect.' It also notes a 5 s per hop timeout, which is a practical usage constraint. While it does not mention alternative tools for when not to use it, the given scenarios are clear and actionable.

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

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

The description discloses the single fetch, 10s timeout, content-type and Contact requirements, and the full status vocabulary with semantics (ok, not_applicable, timeout, error). It adds substantial behavioral context beyond the readOnlyHint and openWorldHint annotations, and doesn't contradict them.

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 dense but well-structured: purpose first, then requirements, then return statuses. Every sentence contributes value, though it's slightly long due to the status vocabulary enumeration.

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 the purpose, prerequisites, return statuses, and how to interpret each status. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the domain parameter is already well described, including rejected inputs. The description adds no additional parameter-specific meaning beyond referencing 'domain' in context, 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 verb (check), resource (security.txt at /.well-known/), and standard (RFC 9116), plus the returned fields. It clearly distinguishes itself from sibling dossier_* tools by the specific file it targets, even though it doesn't name alternatives.

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 purpose implies when to use it (to verify security.txt presence), but it doesn't contrast with other dossier tools or state explicit when-not-to-use conditions. The 'requires non-HTML content type and Contact field' is more about behavioral conditions than selection 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?

The description goes well beyond the readOnlyHint annotation by disclosing the transport (Cloudflare DNS-over-HTTPS), edge-case handling (lookalike records behind byte-order marks), and RFC 7208 behavior for multiple SPF records. It also explains the response statuses and their semantics, which is valuable behavioral context the annotations do not provide.

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 dense but every sentence earns its place: purpose, use cases, sibling pairing, transport, edge-case behavior, and complete status contract. It is front-loaded with the core action and usage, with finer behavioral details following in a logical order.

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 fully explains the return contract: ok, not_applicable, timeout, and error, including how an agent should interpret not_applicable versus error. Combined with the single fully-documented parameter, nothing essential is missing for selecting and invoking 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?

There is only one parameter, and the schema already describes it fully with examples and exclusions ('IP addresses, ports, paths and protocol prefixes are rejected'). The description adds little beyond the schema's domain coverage, so the high schema-description coverage 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?

The description opens with a specific verb and resource: 'Find and parse a domain's SPF record into its mechanisms.' It then states the practical use cases (check authorized senders, debug delivery failures) and distinguishes itself by naming dossier_dmarc and dossier_dkim as complementary tools rather than substitutes.

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 guidance on when to use the tool: 'Use to check which servers may send mail for a domain, or to debug delivery failures.' It also recommends pairing with dossier_dmarc and dossier_dkim for the full email-authentication picture, giving clear context for choosing this tool. It does not explicitly state when not to use it, but the guidance is still actionable.

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

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

Annotations provide readOnlyHint and openWorldHint, but the description goes far beyond: it explains parallel execution, the per-check grading with severity levels, the fact that raw records and fix instructions are not returned, the exclusion of web/discovery checks, and the complete JSON response envelope with status variants (ok, not_applicable, timeout, error) and how to interpret them. This is rich behavioral disclosure with no contradiction.

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 dense but efficiently organized: purpose first, then usage guidance, then behavior and return format. It is longer than typical, but every sentence adds necessary information for a tool that produces complex graded output across nine checks. The structure front-loads the key action and the most critical exclusions.

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

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

With no output schema, the description compensates by fully specifying the return structure: the top-level JSON fields, the per-check object shape, and the status envelope with all possible statuses and their meaning. It also clarifies what is not included (raw records, fix instructions, web checks) and the grading reference. An agent has all necessary information to invoke and interpret results correctly.

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

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

There is only one parameter, domain, and the schema already describes it fully: 'Public domain name, e.g. example.com. IP addresses, ports, paths and protocol prefixes are rejected.' Since schema coverage is 100%, the description adds no additional parameter-specific meaning beyond the tool's overall purpose, 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?

The description explicitly states the tool runs nine specific DNS, email-authentication and TLS checks in parallel and returns graded lines. It names the checks individually, distinguishing it from the single dossier_* tools that provide raw data. This is a precise, actionable 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?

It gives explicit when-to-use guidance: 'Use it first when asked how a domain is set up or whether its email can be spoofed; then call the single dossier_* tool for any check you need the raw data for.' This clearly directs the agent to the summary for overview and to the specific tools for raw data, 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses the exact execution behavior: one TLS handshake from a specific server, a 5 s timeout, and a full status envelope with ok, not_applicable, timeout, and error variants. It even tells the agent how to interpret non-success results, which is valuable operational context.

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?

Every sentence earns its place: the purpose and fields come first, then the use case and non-goals, then the concrete protocol behavior, then the return contract and interpretation guidance. It is compact while carrying a lot of decision-relevant information.

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

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

With one parameter and no output schema, the description fully compensates by documenting the output shape, all possible status variants, the timeout behavior, and how the agent should interpret not_applicable vs error. Nothing essential for selecting or invoking this tool is missing.

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

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

Schema description coverage is 100%, and the schema already explains that domain must be a public domain name and rejects IPs, ports, paths, and protocol prefixes. The description adds the port-443 context but does not materially enrich the parameter meaning beyond the schema, 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?

The description opens with a precise verb and resource: 'Read the TLS certificate a domain presents on port 443', then enumerates the specific certificate fields returned. It also distinguishes itself from sibling tools by explicitly stating it does not test cipher suites or protocol versions.

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 clearly says when to use the tool ('Use to check expiry or a name mismatch') and states an important non-goal ('It does not test cipher suites or protocol versions'). It does not, however, name a specific sibling tool as the alternative for cipher/protocol testing, so the guidance stops short of fully explicit rerouting.

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 fully discloses the tool's behavior beyond the readOnlyHint and openWorldHint annotations. It specifies the underlying query mechanism (Cloudflare DNS-over-HTTPS), the JSON response structure with all possible statuses (ok, not_applicable, timeout, error), and provides interpretive guidance (treat not_applicable as a finding, error as unknown). This is exemplary behavioral 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 information-dense but not padded. The primary purpose is front-loaded in the first sentence, followed by a concise explanation of return statuses. It avoids unnecessary details while covering all essential aspects. It could be slightly trimmed, but every sentence earns its place.

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

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

Given the tool's moderate complexity, no output schema, and a single parameter, the description is complete. It explains the return format thoroughly, distinguishes genuine absence from errors, and notes the use of Cloudflare DNS-over-HTTPS. An agent has everything needed to call the tool and interpret results correctly.

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

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

The schema description coverage is 100%, fully documenting the 'domain' parameter with format restrictions (no IPs, ports, paths, prefixes). The tool description adds no additional parameter-level information beyond what the schema already provides, so the 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 a specific action ('Look up a domain's SMTP TLS Reporting policy'), the exact DNS record queried (_smtp._tls.<domain>), and the intended use case (confirm the domain receives reports). This distinguishes it from sibling dossier tools, which target different record types or surfaces, even without naming them.

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 context for when to use the tool: 'Use to confirm the domain receives reports about failed TLS delivery of its inbound mail.' It does not name alternative tools, but given the unique purpose among siblings, this is sufficient. It could be more explicit about when NOT to use it, but the purpose is clear enough for an agent to select it appropriately.

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 adds substantial behavior beyond the annotations: three parallel HTTPS fetches, 64 KB caps per fetch, and the full set of status responses including 'not_applicable', 'timeout', and 'error'. It also advises how to interpret those statuses, which is valuable because there is no output 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?

The description is front-loaded with purpose and use case, then packs behavior and response semantics into a compact set of sentences. The status payload examples earn their place because they define the tool's contract.

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 one simple parameter, no output schema, and only readOnly/openWorld annotations, the description explains the request behavior and response statuses thoroughly. The only minor gap is that the shape of the 'data' field for the successful case is not detailed, though it is roughly inferable from the listed surface components.

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 documents the 'domain' parameter thoroughly, including rejected forms like IPs, ports, paths, and protocols. The description reinforces that the domain is the subject of the summary but adds no new parameter-level meaning, 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?

The description states a specific verb and resource: 'Summarise a domain's public web surface' followed by explicit components (robots.txt, sitemap.xml, home page meta tags). It clearly distinguishes this from sibling recon tools by focusing on SEO/link-preview surface rather than DNS, headers, or 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?

It gives clear usage context: 'Use for a quick SEO or link-preview review.' It does not explicitly name alternatives or state when not to use the tool, so it falls short of the top score, but the intended scenario is unambiguous.

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 goes well beyond the annotations (readOnlyHint, openWorldHint) by detailing the protocol fallback (TCP 43 then RDAP over HTTPS), the 15-second timeout, and the exact response statuses including not_applicable, timeout, and error, with guidance on how to interpret them ('Treat not_applicable as a finding and error as unknown'). This fully discloses the tool's behavior and edge cases.

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 four sentences, each carrying essential information: purpose, use case, protocol behavior with timeout, and return format with interpretation. It is front-loaded with the core purpose and avoids any filler. The length is justified by the tool's complexity and the lack of an output schema.

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

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

For a tool with fallback mechanisms, timeout, and multiple status codes, the description is remarkably complete. It explains the full response format, including the status field and its variants, and provides guidance on interpreting each. Since there is no output schema, the description carries the full burden of return-value explanation, and it does so thoroughly. No critical information is missing for an agent to call it correctly.

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

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

The schema provides 100% coverage for the single domain parameter, including type, example, and rejection criteria for IPs, ports, paths, and protocols. The description adds no additional parameter-specific semantics beyond the schema, so the baseline of 3 applies. The description's focus is on behavior and output, not parameter details.

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 ('Look up') and resource ('a domain's registrar, creation date, expiry date and registry statuses'), which clearly distinguishes it from sibling tools like dossier_dns or dns_lookup that handle different record types. It also explicitly mentions 'Use for an ownership or expiry check,' reinforcing its purpose and differentiating it from other dossier_* 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?

The description gives an explicit when-to-use instruction ('Use for an ownership or expiry check') and explains the fallback behavior (WHOIS then RDAP), which informs the agent of the tool's process. It does not explicitly state when not to use it or name alternatives, but the purpose is distinct enough from siblings that this is clear. A 4 is appropriate because usage context is present but no explicit exclusions.

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

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

Annotations already cover readOnlyHint and openWorldHint. The description adds meaningful behavioral context: data source (ipinfo.io), approximate location accuracy, and the exact JSON return shape. This goes beyond annotation coverage without contradicting 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 compact sentences, each earning its place: what it returns, when to use it and what it cannot do, and source/accuracy plus output shape. Front-loaded and free of filler.

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

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

For a single-parameter, read-only lookup tool, the description covers input constraints, output shape, data source, and routing to dns_lookup. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the input restriction ('does not accept hostnames') and tying the parameter to the use case, adding semantics beyond the schema's format example.

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

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

States a specific verb ('Look up') and resource (IPv4/IPv6 address), and enumerates the exact fields returned (city, region, country, coordinates, timezone, network/ASN). It also distinguishes itself from dns_lookup by noting it does not accept hostnames, so an agent can tell them apart.

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 it ('when you need location or ownership context'), what it cannot do ('does not accept hostnames'), and names the alternative ('resolve those with dns_lookup first'). This is unambiguous routing guidance.

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

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

Beyond the readOnlyHint annotation (which already marks it as a safe read), the description adds 'Runs locally' (execution environment) and 'Returns the formatted JSON, or the parser's error message' (output behavior on failure). These are useful behavioral details not captured in annotations, though it could mention potential size limits or encoding assumptions.

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 exactly two sentences, front-loading the core purpose and options in the first sentence, then adding usage context and a note about local execution. There is zero fluff; every word contributes to understanding the tool's function and behavior.

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 two parameters and no output schema, the description covers validation, formatting options, indent defaults, execution locality, and the return value on success and failure. It does not mention edge cases like empty strings or very large inputs, but these are not critical for a formatter and are reasonably implied. The description is complete enough for an agent to call 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 fully documents both parameters: 'text' is described as 'The JSON text.' and 'indent' has a detailed description covering 0 (minify), 2, 4, and default 2. The description only restates the indent purpose ('indent of 2 or 4 spaces, or minified with indent 0') without adding new meaning beyond the schema. Per the rubric, baseline 3 applies when schema coverage is 100%.

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 specific verbs ('Validate' and 're-print') with a clear resource (JSON) and explicitly lists indent options (2, 4, or minified 0). This is distinct from all sibling tools (encoding, DNS, JWT, etc.), so an agent can immediately identify what this tool does and that it is unique among its 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?

The description states 'Use to check whether a string is valid JSON or to make it readable,' providing clear use cases. It also notes 'Runs locally,' which helps an agent decide when to invoke it (e.g., offline or when network tools are not needed). It doesn't explicitly name alternatives, but given the sibling set is unrelated, the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true; the description goes well beyond by stating it does not verify signatures, runs locally with no token storage/transmission, and returns a specific JSON structure. No contradiction with 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?

Four sentences, each carrying essential information: purpose, security caveat, usage context, and local behavior/return format. No fluff; the most critical safety warning 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, low-complexity tool with annotations covering read-only behavior, the description provides everything needed: return shape, security caveat, and local execution. No output schema exists, but the JSON structure is explicitly stated.

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

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

Schema description coverage is 100% and already explains the token format ('three base64url parts separated by dots'). The description adds no new meaning about the parameter beyond what the schema provides, so the baseline of 3 applies.

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

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

States precisely what it does (decodes JWT header and payload) and is distinct from all sibling tools – no other JWT-specific tool exists. The verb 'Decode' plus the resource 'JSON Web Token's header and payload' leaves no ambiguity.

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

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

Explicitly gives when to use ('while debugging' to inspect claims) and a strong when-not (does not verify signature, so never treat claims as trusted). Though no alternative tool is named, no sibling performs JWT decoding, so the guidance is effectively complete.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavior: 'Fails on a malformed sequence such as a lone % sign,' plus sign handling semantics, and that it 'Runs locally.' These details materially affect how an agent should expect the tool to behave and interpret results.

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

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

Four short sentences, each carrying useful information: the core operation, an edge-case failure, a common input variant, and execution locality. There is no filler, and the essential purpose 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?

With only one required parameter, no output schema, and readOnly annotations, the description covers everything an agent needs to invoke the tool correctly: input format, failure behavior, plus-sign handling, and local execution. No critical gap remains.

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 fully describes the 'text' parameter, but the description adds valuable semantics: it clarifies percent-encoded input, the malformed-sequence failure mode, and the plus-sign nuance. This enriches the parameter beyond the schema's bare 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 opens with a specific verb and resource: 'Decode percent-encoded text.' This clearly distinguishes the tool from siblings like base64_decode and url_encode. The title matches the described behavior, leaving no ambiguity about what the tool does.

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 concrete usage context, including when to preprocess input: 'A plus sign is left as a plus; replace it with a space first if the text came from an HTML form.' It does not explicitly name sibling alternatives or say when not to use this tool, so it falls just 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?

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral detail: it runs locally, returns the encoded string, and follows encodeURIComponent rules. No hidden side effects or network calls are implied. This exceeds the baseline given the 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?

Two efficient sentences with no filler. The core purpose is front-loaded, and the encoding details and local-execution note both earn their 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?

For a single-parameter, read-only tool with no output schema, the description fully covers what the agent needs: what input to provide, what encoding rules apply, where the result is used, and what the tool returns.

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

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

Schema coverage is 100%, so the parameter is already documented. The description adds useful semantic context by specifying the encoding rules and the URL contexts where this encoding applies, going beyond the schema's simple 'Text to encode.'

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

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

States a specific verb ('Percent-encode') and a clear resource (text for URL query values or path segments), and specifies the exact encoding rule (encodeURIComponent). This clearly distinguishes it from sibling tools like url_decode and base64_encode.

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 explains when to use it: when percent-encoding text for URL query values or path segments. It also notes that it runs locally, implicitly distinguishing it from network-dependent tools. It does not explicitly name alternatives or exclusions, but the use case is clear enough.

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

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

Beyond the readOnlyHint annotation, the description adds valuable behavioral details: execution runs locally with no network call, the exact JSON return shape is specified, and unknown fields are revealed to be empty strings. This is particularly important because there is no output 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 tight sentences: the first states the primary function, the second gives usage context, and the third details return structure and edge-case behavior. Every sentence earns its place 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 simple, single-parameter parser, the description is fully self-sufficient. It covers purpose, usage context, runtime behavior, return shape, and unknown-value handling, so an agent can invoke it correctly without any external reference.

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 fully describes the single 'ua' parameter with 100% coverage, so the description doesn't need to add parameter-level detail. It stays at the baseline 3 since there is no extra semantic 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 opens with a precise verb and resource: 'Parse a User-Agent header into browser, operating system, device and rendering engine.' This clearly distinguishes the tool from sibling decode/parse utilities and states exactly what output categories are produced.

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 context for when to use the tool: 'Use when reading server logs or request headers.' It also notes it runs locally with no network call, which helps an agent choose it over network-dependent sibling tools, though it doesn't explicitly list exclusions or alternative 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?

The description discloses that generation is local, uses a cryptographic random source, and returns a JSON array of strings. This goes beyond the readOnlyHint annotation by specifying execution environment and output format, giving an agent confidence about side effects and network usage. No contradiction with 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?

The description is four sentences, front-loaded with the core purpose, then logically expands on versions, execution, and output. Every sentence contributes new information with no filler or repetition of the title or schema.

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

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

For a simple two-parameter tool with no output schema, the description covers the essential context: what it does, version behavior, execution environment, and return format. The schema covers parameters, and the annotations cover safety. An agent has everything needed to call this tool correctly.

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

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

The schema already documents both parameters fully (count range/default, version constraints/default). The description adds value by explaining the semantic difference between version 4 (fully random) and version 7 (timestamp-based, sortable), which is not captured in the schema's brief descriptions. This enriches parameter understanding without redundancy.

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 clear verb+resource ('Generate UUIDs') and immediately distinguishes the two versions (v4 random, v7 timestamped). This is specific and unambiguous, and while it doesn't name a sibling, none of the siblings are UUID-related, so the purpose is fully clear on its own.

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 implicit usage guidance by noting v7 'suits database keys', which helps an agent choose between versions. It also notes the tool runs locally, which is relevant for privacy-sensitive contexts. However, it does not explicitly state when to use this tool vs. an alternative (though no direct alternative exists among siblings), and it doesn't mention any constraints like the count limit (though the schema does).

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