Have I Been Pwned

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

Annotations already indicate non-read-only and non-idempotent behavior. The description adds the authentication requirement but does not elaborate on side effects, token expiration, or whether repeated calls invalidate previous tokens. It meets the baseline with annotations present.

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 consists of two efficient sentences: the first defines the purpose, and the second states a prerequisite. No redundant or unnecessary information is present.

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

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

The description covers the core purpose and authentication requirement. An output schema exists, so return values are not needed. It could be slightly improved by hinting at the workflow (generate token, add DNS record, verify), but it is still adequately complete for this simple tool.

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

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

Schema coverage is 100%, so the description adds no significant meaning beyond what the schema already provides for both parameters. The description does not enhance understanding of parameter semantics 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 generates a TXT record value for domain verification via DNS. It distinguishes itself from sibling tools like 'hibp_send_domain_verification_email' and 'hibp_verify_domain_verification_dns_token' by focusing on token generation.

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 specifies the prerequisite of an authenticated subscription with domain-verification access. It does not explicitly state when not to use it, but the workflow is implied by the sibling tool names, providing adequate context for an AI 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?

With annotations already declaring readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description is not required to repeat safety traits. It adds value by clarifying that the breach is 'public' and retrieved by 'canonical name', which informs the agent about data source and lookup method. No contradictions 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?

A single, front-loaded sentence with zero redundancy. It clearly states verb, resource, and example without unnecessary words.

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

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

Output schema exists, so return values need not be explained. The description covers the basic purpose and example well. However, it could mention error behavior (e.g., what happens if the breach name doesn't exist) or rate limits, but given the tool's simplicity and annotations, it is mostly adequate.

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

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

Schema coverage is 100%, so the baseline is 3. The description only echoes the schema's parameter description ('by its canonical breach name, such as Adobe'), adding no new semantic meaning beyond what the schema already provides.

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 the tool looks up a single public HIBP breach by its canonical name, using the specific verb 'look up' and resource 'single public HIBP breach'. It provides an example ('Adobe') and implicitly distinguishes from sibling tools like hibp_list_breaches (list) and hibp_get_breached_account (account 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?

No explicit guidance on when to use this tool vs alternatives (e.g., when to use this versus hibp_list_breaches or hibp_get_breached_account). The description does not mention exclusions or prerequisites, which is needed given the large number of 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?

The description adds the behavior of requiring an OAuth bearer token, which is not covered by the annotations (which are all about safety hints). The annotations already indicate read-only, idempotent, non-destructive, so the description supplements with an important auth requirement. No contradictions.

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

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

Two sentences, no filler, front-loaded with the core action ('Search HIBP...'). Every word earns its place. Highly concise.

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

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

For a 7-parameter tool with output schema and many siblings, the description is minimal. It conveys the core purpose and auth requirement but lacks information about filtering, pagination, or result format. However, since output schema exists and schema covers parameters, it is just barely adequate.

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

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

Schema description coverage is 100%, so the parameters are already well-documented in the schema. The tool description does not add any additional parameter semantics beyond what the schema provides.

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 specifies the verb 'Search', the resource 'HIBP breaches', and the scope 'a single email address'. This clearly defines what the tool does and distinguishes it from siblings like 'hibp_get_breached_account_range' (range-based search) and 'hibp_get_paste_account' (pastes).

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 mentions the OAuth bearer token requirement, which is a usage prerequisite, but provides no guidance on when to use this tool versus sibling tools (e.g., range versus exact email, or pastes versus breaches). No explicit when-to-use or when-not-to-use context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that the endpoint is 'authenicated' and uses 'k-anonymity', but it does not elaborate on behavioral traits such as rate limits, pagination, or the privacy protection mechanism. The description does not contradict 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 a single sentence that is front-loaded with the core action and resource. It is concise without unnecessary words, and every word contributes to understanding the tool's purpose.

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

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

The tool has an output schema, so return values are covered. The description adequately states the endpoint and input, but it lacks context about the k-anonymity model, why to use this endpoint over others, and how results are structured. Given the tool's moderate complexity, the description is minimally 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%, so baseline is 3. The description mentions the 'prefix' parameter implicitly by stating 'first 6 characters', but does not add meaning for limit, offset, or response_format beyond what the schema already provides. Thus, no significant added value.

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

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

The description specifies the verb 'Query' and identifies the resource as the 'authenticated HIBP k-anonymity breached-account range endpoint' with the first 6 characters of a SHA-1 email hash. This clearly indicates the tool's function and distinguishes it from sibling tools like `hibp_get_breached_account` that use a full hash, though it does not explicitly differentiate from `hibp_get_pwned_passwords_range` which also uses k-anonymity.

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 does not provide guidance on when to use this tool versus alternatives. For example, it does not indicate that this tool is for bulk or privacy-preserving lookups compared to `hibp_get_breached_account`. No exclusions or when-not-to-use information is given.

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 provide readOnlyHint, idempotentHint, and openWorldHint, making the safety profile clear. The description adds the authentication requirement ('authorized subscription via OAuth bearer token'), which is a useful behavioral constraint beyond the annotations. No contradictions; return format is handled by the 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 extremely concise—two short sentences that cover purpose and key requirement. No filler or redundant information; every sentence adds value.

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

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

Given the tool has full schema descriptions and an output schema, the description is mostly complete. It clearly states the purpose and a critical prerequisite. However, it could briefly mention pagination (limit/offset) or note that the response is structured, though the schema handles those details adequately.

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% across all 4 parameters, so the schema already documents their meaning. The tool description does not add any additional parameter context (e.g., formatting rules, relationships between parameters). Per guidelines, baseline is 3 when coverage is high.

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 ('return') and resource ('breached aliases') with a clear scope ('for a verified domain'), which distinguishes it from sibling tools like hibp_get_breached_account (returns individual accounts) and hibp_list_subscribed_domains (lists domains, not aliases). The purpose is immediately clear.

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 mentions the authorization requirement ('requires an authorized subscription via OAuth bearer token'), which is a prerequisite, but does not provide guidance on when to use this tool versus other domain-related siblings (e.g., verification tools, subscription status). No explicit when-not or alternatives are given.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds specificity about the return value (most recently added public breach) and that it is currently loaded, which adds value beyond 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 a single, concise sentence with no extraneous information. It efficiently conveys the purpose.

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

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

Given the tool's low complexity (no required params, output schema exists, no nested objects), the description is fully adequate. It covers what the tool does and what it 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?

The single parameter `response_format` is fully described in the schema (enum, default, description). The tool description does not add further semantic detail, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns the most recently added public breach from HIBP, with a specific verb and resource. It distinguishes itself from siblings like hibp_get_breach or hibp_list_breaches by focusing on the latest breach alone.

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 implies usage when the latest breach is needed, but does not explicitly mention alternatives or exclusion criteria. Given the tool's simplicity, the context 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destruction. The description adds an important behavioral detail: the need for an OAuth bearer token. This is a valuable security/authentication context beyond the annotations. However, it does not disclose rate limits or other potential behavior.

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

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

The description is extremely concise: two sentences, no wasted words. The first sentence states the core purpose, the second adds a critical prerequisite. It is well-structured and immediately informative.

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 fully documented output schema and 100% parameter schema coverage, the description does not need to explain return values. However, it does not provide contextual details such as what constitutes a 'paste,' result ordering, or how to interpret results. Given the existence of many sibling tools, some additional context about when pastes differ from breaches/stealer logs would improve completeness.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (account, limit, offset, response_format) with descriptions. The tool description does not provide any additional meaning or nuance beyond what is in the schema. 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?

Description explicitly states 'Search for public pastes containing an email address,' which clearly identifies the verb (search) and resource (pastes by email). This distinctly differentiates from sibling tools like hibp_get_breached_account or hibp_get_stealer_logs_by_email.

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 only notes the requirement for an OAuth bearer token, but provides no guidance on when to use this tool versus alternatives (e.g., when to use hibp_get_paste_account vs hibp_get_stealer_logs_by_email). No exclusions or context for selection are given.

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, idempotentHint, and non-destructive behavior. The description adds context about the k-anonymity model and the public API nature, which is useful beyond annotations. No contradictions.

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

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

The description is a single concise sentence that front-loads the key action and resource. Every word adds value; no redundancy or unnecessary 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?

Given the tool has 6 parameters, pagination, and response format options, the description is brief. While fairly complete for a simple read-only tool with good schema and output schema, it lacks mention of pagination, padding, and format options that agents should be aware of.

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 each parameter is already described. The description adds minimal extra meaning beyond schema (e.g., prefix length and hash types). 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 specifies the verb 'query', the resource 'public Pwned Passwords k-anonymity API', and the inputs (5-character SHA-1 or NTLM prefix) and outputs (matching suffixes with prevalence counts). It clearly distinguishes this tool from sibling tools focused on breaches, pastes, and stealer 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?

The description implies usage for password checking via k-anonymity but does not explicitly state when to use this tool versus alternatives (e.g., breach lookup tools). No guidance on when not to use or prerequisites is 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?

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint; the description only adds the subscription requirement, which is useful but minimal additional 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?

Two sentences, front-loaded purpose, no unnecessary words.

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

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

Given the complete input schema, output schema presence, and annotation coverage, the description is sufficient for an agent to understand the tool's behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema's parameter 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 verb 'return' and the specific resource 'website domains observed in stealer logs for an email address', distinguishing it from sibling tools that search by domain or for different entities.

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 notes the prerequisite 'Requires an authenticated subscription with stealer-log access', but does not provide guidance on when to use this tool versus alternatives like hibp_get_stealer_logs_by_email_domain.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the authentication requirement, which is useful but doesn't elaborate on other behaviors like pagination or rate limits. With annotations covering safety, the bar is lower, and the description adds moderate value.

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

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

Two sentences, each serving a clear purpose: one for functional definition, one for requirements. No redundant information, front-loaded with the primary action.

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

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

Given the read-only nature, full schema coverage, and presence of an output schema, the description adequately complements the structured fields. It could be slightly more detailed about usage scenarios, but overall it is complete enough.

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 does not add extra meaning beyond what the schema provides for the parameters.

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

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

The description clearly states the verb 'return' and specifies the resource ('email aliases and associated website domains') and scope ('for an email domain'). It also distinguishes from siblings like hibp_get_stealer_logs_by_email and hibp_get_stealer_logs_by_website_domain by emphasizing domain-based search.

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 mentions the required subscription access, providing clear prerequisites. However, it does not explicitly contrast with alternative stealer log tools, leaving some implicit differentiation.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds the subscription requirement, which is valuable behavioral context beyond 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 sentences, front-loading the core action. No redundant 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?

Output schema is present, so return values are documented. However, the description omits mention of pagination (limit/offset), scope of results, or any side effects. Adequate but not thorough.

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

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

Input schema covers 100% of parameters with descriptions. The tool description adds no additional parameter information, so 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 it returns email addresses from stealer logs for a website domain, and the name distinguishes it from sibling tools like hibp_get_stealer_logs_by_email or hibp_get_stealer_logs_by_email_domain.

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 mentions an authentication requirement but provides no guidance on when to use this tool versus its siblings (e.g., by email or email domain). No when-to-use or when-not-to-use context.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds no new behavioral detail beyond 'authenticated OAuth-linked', which is standard.

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

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

Single sentence, no fluff, immediately states the purpose.

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

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

For a simple read-only status tool with full schema and annotations, the description is adequate. It does not enumerate returned fields, but output schema handles that.

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

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

Schema coverage is 100% for the single parameter. The description does not add meaning beyond what the schema provides.

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 ('return') and resource ('current subscription details and feature flags'), distinguishing it from sibling tools that handle breaches, passwords, and domains.

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?

No explicit guidance on when to use this tool vs. alternatives. The description does not mention prerequisites (e.g., must have OAuth token) or context for usage.

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 (readOnlyHint, idempotentHint, destructiveHint=false) already indicate safe, non-destructive, read-only operation. The description adds context that results can be filtered and are from public HIBP data, complementing annotations without 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 a single sentence of 15 words, immediately stating the primary action and key differentiators. No redundant information, front-loaded with the core purpose.

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

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

Given strong annotations and full schema coverage, the description sufficiently covers the tool's function. It omits mention of pagination (limit/offset) but schema explains those. For a listing tool, the description is adequately complete.

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

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

Schema description coverage is 100% (all 6 parameters have descriptions). The tool's description only summarizes filters (domain, spam-list flag, verification status) without adding meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action (list), the data source (public HIBP breaches), and optional filters (domain, spam-list flag, verification status). It distinguishes itself from sibling tools like hibp_get_breach (single breach) and hibp_list_subscribed_domains.

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 implies usage for listing public breaches but does not explicitly state when to use this tool over siblings or provide exclusion criteria (e.g., 'use this to get an overview, not for specific breach details'). The guidance is minimal.

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, idempotentHint=true, destructiveHint=false. The description adds no additional behavioral context beyond 'List', which is consistent. Since annotations carry the burden, a baseline score of 3 is appropriate.

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

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

Single sentence, no waste, front-loaded with verb and resource. Perfectly concise for the tool's simplicity.

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 list tool with output schema and comprehensive annotations, the description is sufficiently complete. Could optionally mention that it returns an array of strings, but not necessary given the output schema exists.

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 one parameter (response_format) fully described via enum and description. The description does not add any parameter semantics beyond the schema, so baseline 3.

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

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

Description clearly states the verb 'List' and the resource 'data classes' with scope 'across public HIBP breach models', and provides an example. This distinguishes it from sibling tools that handle breaches, accounts, passwords, etc.

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

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

No explicit when-to-use or when-not-to-use guidance. The description implies it is for getting an enumeration of data class labels, but lacks alternatives or exclusions. Given the simplicity of the tool, this is adequate but not exemplary.

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, openWorldHint, idempotentHint, and destructiveHint, so the agent knows it's safe. The description adds only that authentication is required, but does not disclose pagination behavior, rate limits, or what exactly 'associated' means (e.g., only verified domains?). The description adds minimal extra transparency beyond the rich 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 a single, clear sentence without any unnecessary words. It is front-loaded with the verb 'List', making the purpose immediately apparent. Every word 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 simplicity of the tool (list with pagination), the presence of an output schema, and comprehensive annotations, the description is almost complete. It could mention that the list includes all subscribed domains (or specify if only verified ones) and possibly default sorting order, but overall it is adequate for effective use.

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?

All three parameters (limit, offset, response_format) are fully described in the schema. The description does not add any additional meaning or context to these parameters. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the tool lists domains associated with the authenticated HIBP subscription. The verb 'List' and resource 'domains' are specific, and it distinguishes from sibling tools like hibp_get_subscription_status or hibp_list_breaches that have 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?

No explicit guidance on when to use this tool versus alternatives, or prerequisites like authentication. The usage is implied, but a brief note about when to prefer listing over other domain operations would improve clarity.

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 indicate mutation and non-idempotency, and the description adds the subscription requirement, but it does not disclose potential side effects like email delivery failures or quota consumption.

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 front-loaded sentence with no wasted words, effectively communicating the action and a key requirement.

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?

It does not explain the overall domain verification flow (e.g., what happens after sending, whether user action is needed), and despite an output schema, it offers no details on return values.

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?

All parameters have schema descriptions with 100% coverage; the tool description adds no new meaning beyond echoing the schema's 'approved alias' for emailAlias.

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

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

The description clearly states it sends a domain verification email to an approved alias, which distinguishes it from sibling tools that generate or verify DNS tokens.

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 specifies a prerequisite (authenticated subscription with domain-verification access) and implicitly differentiates from DNS-based tools, but lacks explicit guidance on when to choose email over DNS.

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 indicate non-readOnly and non-destructive behavior. The description adds the requirement for 'authenticated subscription with domain-verification access,' which is useful context, but does not detail error conditions or 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?

Two sentences, no wasted words. The key action and prerequisite are front-loaded, making it quick 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?

Given the presence of output schema and annotations, the description is sufficient to understand the tool's purpose and requirements. However, it might benefit from mentioning that DNS propagation delays can affect results.

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

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

Schema coverage is 100% with descriptions for both 'domain' and 'response_format.' The tool description does not add additional meaning beyond the schema, so baseline score 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 action: 'Complete domain verification by checking the expected HIBP TXT record on the target domain.' It specifies a verb and resource, and distinguishes from sibling tools like generate and send email.

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 implies usage as the final verification step after generating a DNS token or sending email, but does not explicitly state when not to use it or provide alternative paths. The prerequisite of an authenticated subscription is mentioned.

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