drwho.me

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

With no annotations, the description carries the full burden and does well: it discloses the transport (Cloudflare DoH over HTTPS), behavior (follows CNAME chains), timeout (5 s), and return shape (JSON array or error string). It misses rate limits or auth, but these are less critical for a public DoH query.

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?

Five sentences, every one adds value: purpose, usage positioning, behavioral details, return contract, and error handling. It is front-loaded with the core purpose and skips 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 is highly complete for a simple two-parameter tool, covering return values despite lacking an output schema, transport behavior, timeout, and alternatives. The one gap is the record-type contradiction with the schema, which creates a confusion risk that prevents a perfect score.

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%, which would normally give a baseline of 3, but the description lists SOA, CAA, and SRV as supported types while the schema enum only permits A, AAAA, MX, TXT, NS, and CNAME. This mismatch actively misleads the agent into providing values that will fail schema validation, reducing parameter clarity below 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 uses a specific verb ('resolve') and resource ('single DNS record type'), and clearly distinguishes from sibling tools by positioning it as quick and targeted, explicitly contrasting with dossier_dns and dossier_full.

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

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

Provides explicit when-to-use guidance ('Use for quick, targeted lookups of one record type') and names alternatives with reasons ('prefer dossier_dns for a full multi-type DNS audit in parallel, or dossier_full for a complete domain health check'), covering both usage and 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?

No annotations are provided, so the description carries the full burden — and it delivers. It discloses the HTTP fetch target, redirect behavior, off-site redirect handling, timeout, robots.txt parsing, and that a missing robots.txt is treated as data rather than an error. It also previews the CheckResult shape and per-agent values, giving the agent a complete behavioral contract.

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 every sentence earns its place: purpose, use case, fetch mechanics, return shape, and edge-case behavior. The most decision-relevant information is front-loaded, and there is no filler or repetition of the 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?

With a single parameter, no annotations, and no output schema, the description is complete enough for an agent to invoke the tool correctly and interpret the result. It covers success values, the missing-robots edge case, timeout, redirects, and the exact agents checked — nothing essential 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?

The input schema already documents the single parameter thoroughly, including that it must be a public FQDN and that IPs, ports, paths, and protocol prefixes are rejected, giving 100% schema coverage. The description adds context about fetching <domain>/robots.txt, but does not significantly extend the parameter's meaning beyond what the schema already provides. The baseline 3 for high schema coverage is therefore 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: 'Report a domain's AI-crawler policy.' It names the six AI agents and the robots.txt actions, making the tool's scope unmistakable and distinguishing it from the many other dossier_* siblings. The phrase 'Core dossier check' positions it within the suite rather than merely restating the tool name.

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 the use case: 'Use to answer "does this site let AI models train on / retrieve its content?" in a posture audit.' It does not name specific alternative tools or conditions when NOT to use it, but the context is clear enough for an agent to select it appropriately among the sibling dossier tools.

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

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

With no annotations, the description must disclose behavior, and it does: single OPTIONS request via fetch, 5s timeout, and the exact success/failure CheckResult shape. It could mention rate limits or side effects, but for a read-only network check, this is strong 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 concise and front-loaded with 'Core dossier check: ...' then expands logically. No filler; every sentence contributes purpose, usage, behavior, or return format.

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 no output schema, so the description must explain return values; it does. It covers purpose, behavior, parameters, defaults, and success/failure shapes, making it self-contained for a simple 3-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining the effect of providing or omitting origin/method ('simulate a precise preflight') and defaults, going slightly beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Send a CORS preflight OPTIONS request to https://<domain>/ and return the access-control-* response headers.' It specifies a precise verb (send/return), resource (CORS preflight), and scope, distinguishing it from sibling DNS/TLS 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?

It explicitly states when to use: 'Use to verify CORS policy for a specific origin-method pair, or to check whether a domain allows cross-origin requests.' It also provides guidance on parameters: 'provide origin and method to simulate a precise preflight, or omit to use defaults.' This is clear usage direction.

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

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

With no annotations provided, the description carries full behavioral disclosure. It reveals query sources (crt.sh first, certspotter fallback), limitations (cap at 100 subdomains), timeout (10s), and return structure. This is thorough and goes beyond what annotations would typically 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 compact and every sentence contributes value: purpose, usage, behavior, constraints, and return format. It is not padded with filler, and the most important information is front-loaded.

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

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

For a single-parameter tool with no output schema, the description provides enough operational context: what it does, how it works, its limits, and the shape of its result. It effectively covers the essential aspects a caller needs to know.

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 a detailed description for the 'domain' parameter (public FQDN, resolvable, rejects IPs/ports/paths/protocols). The tool description does not add additional parameter-specific insight, but 100% schema coverage means 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: 'Discover subdomains visible in Certificate Transparency logs.' It uses a specific verb and resource, and differentiates itself from the broader dossier_full tool by calling itself the 'Core dossier check' for CT logs.

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

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

Explicitly states when to use it ('for attack-surface mapping') and provides an alternative ('prefer dossier_full when running a complete audit'). This gives clear guidance on selection among 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?

With no annotations, the description carries full responsibility for behavioral disclosure. It goes beyond a simple summary by revealing the parallel Cloudflare DoH query method, the 5-second timeout per selector, and the exact return structure (CheckResult with ok/error statuses, found/notFound arrays). This is detailed and transparent, leaving little surprise about how the tool operates.

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 (roughly 80 words) yet packs a clear purpose, usage guidance, implementation details, and return format into a single paragraph. It's front-loaded with the operative verb and resource, and every sentence adds unique value without repetition or 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 tool with only two parameters, no output schema, and no annotations, this description is remarkably complete. It explains what the tool does, when to use it, how it executes (parallel DoH, timeout), and exactly what the returned data looks like. The explicit output structure compensates for the missing output schema, and the use cases are clearly specified.

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

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

The input schema already provides 100% coverage for both parameters, describing valid domain formats and the default selector set. The description's mention of supplying or omitting selectors merely echoes the schema's own instructions, adding no new semantic insight beyond what the structured schema already conveys.

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 'Core dossier check' and then specifies exactly what it does: 'Probe a domain's DKIM public keys by querying <selector>._domainkey.<domain> for each selector.' This clearly distinguishes it from sibling tools like dossier_dmarc or dossier_spf, and the verb 'probe' plus resource 'DKIM public keys' is specific and unambiguous.

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

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

It provides clear usage context: 'Use to verify signing configuration or discover active selectors.' It also gives practical guidance on when to supply selectors versus omit them to use the built-in set. While it doesn't explicitly name alternative tools for when not to use it, the sibling tool suffix makes the domain-specific scope obvious.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the DNS-over-HTTPS endpoint (Cloudflare 1.1.1.1), 5-second timeout, tag=value parsing behavior, and the exact CheckResult return shape including success and error states. This is highly transparent for a DNS query tool and has no annotation contradictions.

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

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

Three sentences with a logical flow: purpose, use cases, then mechanics and return format. It is information-dense but not bloated, and front-loads the core purpose before technical details.

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

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

Given the single required parameter and no output schema, the description fully covers the invocation context. It explains the return contract (status, raw, tags, error reason), the query process, and the relationship to sibling tools, leaving no ambiguity for an agent to select and call it correctly.

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

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

Schema coverage is 100% and already validates the domain parameter. The description adds meaning by explaining how the parameter is used to construct the _dmarc.<domain> query, and reinforces the public FQDN requirement. This goes beyond the schema's validation errors.

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+resource: 'Retrieve and parse a domain's DMARC policy from its _dmarc.<domain> TXT record, returning all tags.' It clearly distinguishes from siblings by mentioning pairing with dossier_spf and dossier_dkim for full email-auth coverage, and specifies the exact DNS resource queried.

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

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

It explicitly states when to use: 'Use to audit email authentication policy, verify the p and rua settings, or confirm alignment mode,' and points to complementary tools (dossier_spf, dossier_dkim). However, it doesn't provide explicit exclusions or when-not-to-use scenarios, so it's clear but not exhaustive.

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

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

With no annotations, the description carries the full burden and does so admirably. It discloses concurrency ('six Cloudflare DoH queries concurrently'), a timeout ('5 s timeout'), the underlying service (Cloudflare DoH 1.1.1.1), and the exact return shape as a discriminated union (success vs. error with reason). These are behavioral traits beyond what structured data provides.

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 purpose: purpose, usage guidance, implementation details, and return format. There is no fluff or repetition; every sentence contributes essential 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?

Despite having no output schema, the description fully explains the return structure. It covers the single parameter implicitly, the tool's execution behavior, and failure mode. For a tool with one parameter and no output schema, this is exceptionally complete.

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

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

Schema coverage is 100% and the schema itself has a detailed description for 'domain' ('Public FQDN... Must be resolvable on the public internet; IPs, ports, paths, and protocol prefixes are rejected'). The description adds no extra parameter semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Fetch') and names the exact resource ('domain's full DNS profile') with the record types (A, AAAA, NS, SOA, CAA, TXT). It also explicitly distinguishes from siblings by saying 'prefer dns_lookup for a single record type, or dossier_full for all 10 dossier checks at once.'

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 clear when-to-use guidance ('first step of a domain audit or when you need a comprehensive DNS snapshot in one call') and explicit alternatives ('prefer dns_lookup for a single record type, or dossier_full for all 10 dossier checks at once'). This leaves no ambiguity about when to choose this tool.

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

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

No annotations are provided, but the description discloses specific technical behaviors: it fires Cloudflare DoH DS and DNSKEY queries with DO=1, has an 8s timeout, and returns a CheckResult discriminated union with an explicit field list. This goes well beyond a basic summary.

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

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

The description is two sentences, front-loaded with purpose, then usage, then mechanics and return shape. Every clause contributes meaningful information with no redundancy or 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 one-parameter tool with no output schema, the description fully covers what the tool does, when to use it, the underlying queries and timeout, and the return structure. No significant gaps remain that would hinder an agent's ability to invoke and interpret the result.

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

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

Schema coverage is 100% and the schema already fully describes the domain parameter (including constraints on IPs, ports, paths, and protocol prefixes). The tool description adds no additional parameter semantics beyond what the schema already provides, so baseline 3 applies.

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

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

The description uses a specific verb ('Verify') with a clear resource ('DNSSEC chain-of-trust for a domain') and lists key components (DS, DNSKEY, AD flag). It explicitly distinguishes from siblings by directing users to dossier_dns for raw record types and dossier_full for a complete audit.

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 states exactly when to use this tool ('Use to confirm the zone is signed and resolvers accept the chain') and names two alternatives with their preferred use cases, giving clear guidance on tool selection.

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

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

With no annotations, the description fully carries the transparency burden. It discloses that all 10 checks fire concurrently, the transport methods (Cloudflare DoH or direct HTTPS), the 5-second per-check timeout, the paywall call counting, and the exact return structure (JSON keyed by check id with a CheckResult discriminated union). This goes far beyond a minimal safety disclosure.

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

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

The description is front-loaded with the core action, then provides usage guidance, operational details, and return format in a logical sequence. Each of the five sentences contributes unique information, with no filler or redundancy. It is dense but highly efficient.

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

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

Given the tool's moderate complexity (one parameter, no output schema, no annotations), the description is remarkably complete. It covers purpose, usage, alternatives, concurrency, timeout, paywall implications, and return format. A lack of an output schema is compensated by the explicit JSON structure description.

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 'domain' parameter, which already documents the FQDN requirement and what is rejected (IPs, ports, paths, protocol prefixes). The tool description adds no additional parameter-level context, 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 opens with 'Aggregate dossier check: Run all 10 Domain Dossier checks' and explicitly lists the 10 checks (dns, mx, spf, dmarc, dkim, tls, redirects, headers, cors, web-surface). This clearly distinguishes the tool from the individual dossier_* siblings by its aggregate nature and parallel execution.

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

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

The description explicitly states when to use this tool ('Use when you need a comprehensive domain health snapshot in one call') and when not to use it ('For a single focused check, prefer the individual dossier_* tools to minimise latency'). It also adds the paywall-count benefit, giving concrete decision criteria.

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

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

No annotations exist, so the description fully details behavior: single GET, 5s timeout, captures headers before redirects, and specifies both success and error response formats. This goes beyond basic mutation/safety disclosure and sets clear expectations.

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

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

The description is front-loaded with the core purpose, then efficiently covers usage, behavior, and output format. Each sentence adds necessary information without redundancy, earning a high score despite being longer than minimal examples.

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

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

Given no output schema, the description fully specifies the return contract (success and error objects). It also includes timeout and redirect behavior, making it comprehensive for a tool of this complexity.

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

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

Schema coverage is 100%, with the domain parameter fully described (FQDN, reject IPs/ports/paths). The description adds only usage context ('https://<domain>/') rather than new parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool fetches HTTPS headers and audits security headers, with a specific verb and resource. It also distinguishes itself from sibling tool dossier_redirects, making its purpose unambiguous.

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

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

Explicitly states when to use the tool: 'Use to review CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy'. It also names an alternative for redirect tracing (dossier_redirects), providing clear 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?

With no annotations provided, the description carries full disclosure burden and does so thoroughly: it states the exact URL fetched, the 10s timeout, validation rules (non-HTML content type and leading H1), the rejection of SPA HTML pages, and the not_applicable outcome.

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 distinct information: purpose, use case, fetch/validation behavior, and return shape. The description is detailed yet tightly written with no filler.

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

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

For a one-parameter network probe with no annotations, the description covers input, network behavior, validity criteria, success return shape, and the not_applicable case. Nothing essential is missing for an agent to select and invoke it.

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

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

Schema description coverage is 100%, and the domain parameter is fully documented in the schema with format and rejection rules. The description adds context by showing how the domain is embedded in the URL, but does not need to duplicate schema 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 opens with a specific verb and resource: 'Detect whether a domain publishes an llms.txt at its root.' It also defines what counts by requiring a non-HTML content type and a leading markdown H1, which distinguishes it from broad web-fetch checks like dossier_web_surface.

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

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

It explicitly states its context: 'Use in a content-posture audit to confirm a site guides (rather than ignores) AI agents.' It does not name exclusions or a sibling alternative, but the stated use case is clear enough for routing.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the resolution of the _mta-sts TXT record, the policy fetch location, the 10s timeout, and the not_applicable result when no TXT is published. This is strong transparency for a network check, though it omits failure modes and side effects.

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

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

The description is three sentences long, front-loaded with the primary purpose, and each sentence adds value: purpose, use case, and method/timeout/result. There is no fluff or redundant wording.

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-step network check with no output schema, the description covers the key workflow and return semantics (CheckResult and not_applicable case). It could elaborate on what validation entails or error conditions, but the description is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema already documents the single parameter 'domain' with detailed constraints (resolvable public FQDN, rejects IPs/ports/paths/protocols), giving 100% schema coverage. The description adds no parameter-specific semantics, 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 specifies the tool fetches and validates a domain's MTA-STS policy, naming the exact fields (mode, mx, max_age, policy id). It distinguishes itself from sibling dossier tools by focusing on MTA-STS and even states the practical use case of confirming inbound SMTP TLS enforcement.

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

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

It provides a clear use case: 'Use to confirm inbound SMTP is locked to TLS for this domain.' This gives context for when to invoke the tool. However, it does not explicitly mention when not to use it or point to alternatives like dossier_tls or dossier_mx, so it lacks exclusions or alternative guidance.

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

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

With no annotations provided, the description fully discloses behavior: queries Cloudflare DoH, follows CNAME aliases, 5s timeout, and returns a CheckResult discriminated union with success/error details. This goes beyond what annotations would typically provide and leaves no ambiguity about execution or 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?

Two dense sentences pack purpose, usage context, alternative, implementation details, and return format with no wasted words. Information is front-loaded: the core action comes first.

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

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

Despite having no output schema or annotations, the description fully specifies the return shape ('on success, {status:"ok", records:[{exchange, priority},...]}...; on failure, {status:"error", reason}') and covers the tool's role among siblings. All necessary context is present.

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 covers the 'domain' parameter with a detailed description (public FQDN, rejections of IPs/ports/paths). The tool description adds no further parameter-specific semantics beyond restating 'domain' in the context of MX lookup, so the baseline of 3 for high schema coverage applies.

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

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

Description opens with a specific action: 'Look up a domain's MX (mail exchanger) records and return them sorted ascending by priority.' It clearly identifies the resource (domain MX records) and output format, and implicitly distinguishes from siblings by naming dns_lookup and other dossier checks.

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

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

Provides explicit use cases: 'Use when verifying inbound-mail routing or as a precursor to SPF or DMARC checks.' Also states a clear alternative: 'prefer dns_lookup with type=MX if you only need the raw DNS answer without the ranked view.'

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

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

Without annotations, the description carries full burden. It discloses the 10-hop limit, 'no auto-redirect' fetch behavior, 5s per-hop timeout, and the exact success/failure return shape. This is substantial transparency, though it doesn't explicitly state non-destructiveness or mention service-side rate limits.

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 concise sentences: purpose, use cases, behavior/result format. No redundant wording, front-loaded with 'Core dossier check'.

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

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

Given the tool's simplicity (1 parameter, no output schema/annotations), the description fully covers purpose, input constraints, behavior, limits, and return format. It is complete for an agent to invoke correctly.

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

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

The schema covers the domain parameter 100%, but the description adds meaning by specifying the constructed URL starts with https://<domain>/ and clarifies the default path. This provides useful context 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 clearly states the tool traces the full HTTP redirect chain starting from https://<domain>/, recording each hop's status code and destination URL. This specific verb+resource+scope distinguishes it from sibling dossier tools like dossier_headers or dossier_cors.

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

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

It explicitly lists use cases: debug redirect loops, verify HTTP→HTTPS upgrades, audit link shorteners. While it doesn't name alternative tools, the context is clear enough for an agent to select this tool for redirect-related checks.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior, and it largely succeeds: it states the exact URL fetched, a 10s timeout, validation criteria (non-HTML content type and Contact: field), and the result shape. It also explains the not_applicable outcome for absence, which is a meaningful behavioral detail beyond the name and 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?

Four compact sentences each carry distinct value: purpose, usage context, technical behavior, and return format. The core purpose is front-loaded, and there is no redundant or filler content; 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?

For a single-parameter network check, the description covers purpose, usage, behavior, parameter constraints, and result shapes. However, it does not specify behavior on network failure, timeout expiration, or non-conforming content type (beyond saying it requires non-HTML), which is an important gap for an audit tool where an agent may need to distinguish 'error' from 'not_applicable'.

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 baseline is 3. The description adds only a small increment by showing how <domain> is interpolated into the HTTPS URL, but the schema already documents the domain as a public FQDN and rejects IPs, ports, paths, and protocol prefixes. This marginal addition does not warrant a higher score.

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 ('Verify') and names a concrete resource ('security.txt (RFC 9116) at /.well-known/security.txt'), which makes the tool's function immediately clear. It also distinguishes itself from sibling dossier_* checks by focusing on a single, well-known disclosure channel, so an agent can tell it apart 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 directs use 'in a security audit to confirm researchers have a published disclosure route' and even characterizes the absence as a '(minor) audit flag'. It does not mention alternatives or exclusions, but the stated context is unambiguous and sufficient for an agent to decide when to invoke this tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses the network mechanism (Cloudflare DoH), timeout (5 s), record location (v=spf1), and parsing behavior, plus the return schema including success/error states. It would benefit from noting whether includes are resolved or just parsed, but the current disclosure is strong.

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 divided into purpose, usage, and technical details. It's a bit dense but all sentences contribute meaningful information. No fluff.

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

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

With no output schema, the description thoroughly specifies the CheckResult structure on both success and failure, covers network behavior, and lists use cases. It is complete for a single-parameter tool.

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

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

The schema already documents the domain parameter with a full description (public FQDN, restrictions). The tool description adds no further parameter-level detail, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Retrieve and parse a domain's SPF record, decomposing it into mechanisms and qualifiers.' It distinguishes itself from siblings by referencing dossier_dmarc for email-auth coverage and dns_lookup for raw TXT records.

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

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

Explicit usage scenarios are provided: 'verify email sender policy, debug delivery failures, or check the 10-lookup limit.' It also names alternatives: 'pair with dossier_dmarc... or use dns_lookup with type=TXT'.

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

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

With no annotations provided, the description carries the full burden and does so excellently. It discloses that it performs a TLS handshake from the server edge, has a 5-second timeout, extracts the leaf certificate, and describes the exact success/error return structure. No behavioral aspects are hidden.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence adds value: what it does, when to use it, and what it returns. There is 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?

This is a single-parameter tool with no output schema, but the description fully compensates by explaining the return format in detail, including success and error cases. It also covers the timeout, handshake behavior, and use cases, making the tool's behavior and outputs fully actionable for an agent.

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

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

Schema coverage is 100% with a detailed description of the 'domain' parameter (public FQDN, resolvable, rejects IPs/ports/paths). The tool description adds no additional parameter semantics beyond what the schema already provides, 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 tool fetches and inspects the TLS certificate on port 443, with specific details on what it returns (chain details, validity period). It also distinguishes itself from a cipher-suite scanner, making its scope unambiguous among the sibling 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?

Explicitly states when to use the tool (verify certificate expiry, issuer, SANs, detect mismatched/self-signed certs) and provides a clear exclusion ('not a full cipher-suite scanner'). This gives the agent strong guidance on appropriate vs inappropriate uses, even if no alternative tool is named.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the DNS record resolved (_smtp._tls.<domain> TXT), the resolver (Cloudflare DoH), the timeout (5s), and the return behavior (CheckResult, not_applicable when no record). This is strong transparency for a read-only lookup.

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. Every sentence adds useful information: what it does, when to use it, the resolution mechanism, and the return behavior. No filler or repetition of schema details.

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

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

For a single-parameter lookup tool with no output schema, this description is complete. It explains the purpose, the technical mechanism, and the expected result. The sibling context clarifies how it fits into the dossier toolset without needing further elaboration.

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 well-documented. The description adds value beyond the schema by showing exactly how the domain is used in the DNS query (_smtp._tls.<domain> TXT), which helps the agent understand the parameter's semantic role.

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 ('Look up') and clearly identifies the resource ('a domain's TLS-RPT (SMTP TLS Reporting) policy'). It distinguishes itself from siblings like dossier_mta_sts and dns_lookup by focusing on the TLS-RPT policy and its 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 explicitly states when to use it: 'Use to confirm the domain receives reports of SMTP-TLS failures.' While it doesn't name alternatives or exclusions, this clear context is sufficient for a specialized lookup tool, especially given the sibling list.

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

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

No annotations are provided, so the description carries the full burden. It discloses the fetching mechanism (concurrent HTTPS), the timeout (5 s each), the parsing approach (lightweight HTML parser), and the exact return format for both success and error cases. This goes far beyond the schema and gives the agent a precise mental model of what happens when the tool is invoked. There is no contradiction with annotations since none exist.

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

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

The description is three sentences long, each serving a distinct purpose: (1) defining the tool's purpose and components, (2) providing usage scenarios and alternatives, (3) detailing technical behavior and return format. There is no fluff or redundancy; every sentence carries essential information, and the most critical information is front-loaded in the first sentence.

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

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

For a tool with one parameter, no annotations, and no output schema, the description is remarkably complete. It covers the inputs (domain), the behavior (concurrent fetches, timeout, parsing), and the output structure (composite CheckResult with status, meta, robots, sitemapPresent). It also implicitly handles edge cases like missing sitemap via 'sitemapPresent'. The description leaves no critical gaps for an agent to reasonably invoke 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 provides a comprehensive description of the 'domain' parameter, including the requirement that it be a public FQDN with IPs, ports, paths, and protocol prefixes rejected (100% schema coverage). The description adds only implicit context about the domain being used as the base for fetching /, /robots.txt, and /sitemap.xml, but does not elaborate on the parameter itself. Given the high schema coverage, 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 'Core dossier check: Snapshot a domain's public web surface', which clearly combines a specific verb ('snapshot') with a specific resource ('domain's public web surface'). It then enumerates the concrete components (robots.txt, sitemap.xml, head metadata), making the scope unambiguous. It also explicitly distinguishes from sibling tools by naming dossier_headers and dossier_redirects for other concerns.

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 usage scenarios: 'Use for SEO audits, content discovery, or verifying metadata before sharing'. It also provides exclusionary guidance by stating 'for HTTP headers use dossier_headers, for redirect behavior use dossier_redirects', which tells the agent exactly when not to use this tool in favor of alternatives. This is the gold standard for usage guidance.

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

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

With no annotations, the description carries the full burden and does so well. It discloses the protocol (TCP/43), the library used (whoiser), a 15s timeout, and the not_applicable failure mode when registries refuse/redact queries. This goes beyond the schema and gives valuable behavioral context. A minor gap is the lack of detail on response format, but 'Returns a CheckResult' plus failure mode is sufficient.

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

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

Three sentences: purpose, use case, and implementation/behavior. Every sentence earns its place. The most important information is front-loaded, and there is zero filler. This is a model of concise, structured documentation.

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

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

For a single-parameter tool with no output schema, the description is complete: it states what it does, when to use it, how it works, timeout, return type, and a key failure mode. It provides enough context for an agent to invoke it correctly without needing additional information. The sibling context doesn't require further disambiguation given the specificity.

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 describes the single 'domain' parameter comprehensively ('Public FQDN... IPs, ports, paths, and protocol prefixes are rejected'). With 100% schema coverage, the baseline is 3, and the description does not add extra parameter-level semantics beyond what the schema provides. It could have reinforced the rejection criteria, but not necessary.

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 starts with a specific verb+resource: 'Look up the registrar, creation date, expiry date, and registry statuses for a domain.' This clearly distinguishes it from sibling tools like dns_lookup and dossier_headers by naming the exact WHOIS data fields it returns. The phrase 'Core dossier check' further situates it as the foundational WHOIS tool.

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

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

The description provides a clear use case: 'Use for ownership/expiry audit.' It does not explicitly mention alternatives or when not to use it, but the context is unambiguous for an agent deciding between this and other dossier tools. Given the clear context without exclusions, a 4 is appropriate.

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

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

No annotations are provided, but the description discloses that it queries ipinfo.io with a server-side token, never exposes the token to callers, lists the exact return fields, and states the failure mode as an error string. This is good transparency, though it does not explicitly say 'read-only' or mention rate limits.

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 focused sentences, each serving a distinct purpose: purpose, usage/alternatives, and behavior/output. No wasted words.

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

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

Given no output schema and no annotations, the description covers purpose, usage, implementation details, output fields, and failure behavior, making it self-sufficient for an agent to decide when and how to use it.

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

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

Schema description coverage is 100% for the 'ip' parameter, and the description reiterates that hostnames are not accepted, but it does not add new semantic details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Resolve') and resource ('IPv4 or IPv6 address'), lists the output fields (geolocation, ASN, org, city/country), and distinguishes from hostname-resolution siblings by explicitly saying 'prefer dns_lookup or dossier_dns for hostname resolution.'

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

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

It explicitly states 'Use when you need network or location context for a raw IP address' and provides alternative tools for hostname resolution, plus notes that hostnames are not accepted in the parameter description.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool runs synchronously, uses the ua-parser-js library, makes no external calls, returns a specific JSON structure, and sets unknown fields to empty strings. This is thorough behavioral disclosure for a simple parser.

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 efficiently conveys usage and return details in three sentences. The 'Context lookup:' prefix is slightly redundant, but overall there is no fluff or wasted words.

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

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

For a single-parameter local parser with no annotations or output schema, the description is complete: it covers purpose, use case, behavioral traits (sync, local), return structure, and fallback behavior. There are no significant gaps for this complexity level.

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

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

The input schema has 100% documentation coverage for the 'ua' parameter, including an example. The description repeats 'raw UA string' but does not add meaningful syntax or format details beyond what the schema already provides, so it does not exceed 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 description states a specific verb ('Parse') and resource ('User-Agent header string') with clear output components (browser, OS, device type, rendering-engine). It distinguishes itself from sibling network tools by explicitly noting 'entirely local parsing' and 'no external calls', which differentiates it from the dossier/dns/ip lookup 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 provides a clear use context ('when analysing server logs or request headers') and an exclusion ('does not perform any network lookups — entirely local parsing'). However, it does not name an alternative sibling tool explicitly, so it misses the top score of 5.

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