Have I Been Pwned

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

Annotations already indicate this is a non-read-only, non-destructive operation, and the description adds valuable detail by stating it creates or reuses private HIBP domain-verification records. It also discloses the authentication requirement. There is no contradiction with the annotations, and the side-effect language aligns with readOnlyHint=false.

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 with no filler. The core action and output are front-loaded, and the authentication prerequisite is placed second. Every sentence earns its place.

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

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

Given the output schema and fully documented parameters, the description provides sufficient context for safe invocation: it covers the purpose, side effect, and access requirement. It does not explicitly describe the follow-up verify step, but that is not required to correctly call this 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 description coverage is 100%, so the input schema already documents both domain and response_format. The description does not add parameter-specific meaning, but it does not need to because the schema handles it. 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 uses a specific verb ('Generate') with a concrete resource ('the TXT record value') and states the purpose: verifying domain control via DNS. It also differentiates from siblings by emphasizing 'DNS' and 'verification token', which contrasts with send_domain_verification_email and verify_domain_verification_dns_token.

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

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

The description gives clear context: this is for DNS-based domain verification and requires an authenticated subscription with domain-verification access. It does not explicitly name alternatives such as send_domain_verification_email or verify_domain_verification_dns_token, but the workflow context is clear enough for an agent to infer when this tool applies.

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 convey readOnlyHint and idempotentHint, covering the safety profile. The description adds no further behavioral detail (e.g., error handling, rate limits, or what happens for unknown breach names). It merely restates the action without adding 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?

A single concise sentence front-loads the core action and includes an example. No unnecessary words; the description is appropriately minimal.

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 is simple, and the schema and output schema cover parameters and return values. However, the description lacks any usage guidance (e.g., when to use this vs. listing breaches), which is a gap for an agent deciding among siblings. It is adequate but not fully complete.

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

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

Schema description coverage is 100%, so both parameters are documented. The description adds an example for the 'name' parameter, which is helpful but not essential. Overall, it does not add significant meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb ('Look up') and resource ('single public HIBP breach') with an example, making the purpose clear. It implies distinction from list-style tools but does not explicitly differentiate from siblings like hibp_list_breaches.

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 guidance on when to use this tool versus alternatives. The description only states what it does, not when it should be selected. Sibling tools like hibp_list_breaches or hibp_get_latest_breach are not mentioned, leaving the agent to infer 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral context by specifying that an OAuth bearer token linked to an active HIBP API subscription is required, which is critical for invocation. It also mentions the ability to refine results via filters. No contradiction with annotations.

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

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

The description is only two sentences, with the core purpose front-loaded in the first sentence. Every clause earns its place: the purpose, the auth requirement, and a refinement guideline. There is no filler or repetition of schema details, making it appropriately concise.

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

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

Given the output schema exists and annotations cover the non-destructive, idempotent behavior, the description doesn't need to repeat those. It supplies the auth requirement, which is essential for correct invocation, and parameter refinement hints. It doesn't mention rate limits or empty-result behavior, but those are not strictly necessary for tool selection and invocation. The only notable omission is explicit routing among the crowded sibling list, which is better handled in the usage guidelines dimension.

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 a slight hint about using 'domain and verification filters' to refine results, but the phrase 'verification filters' is somewhat vague and doesn't map cleanly to the includeUnverified parameter (which defaults to true, meaning unverified breaches are included rather than filtered out). Overall, the description adds minimal semantic value beyond the already-rich schema.

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

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

The description uses a specific verb and resource: 'Search HIBP for breaches affecting a single email address.' The 'single email address' qualifier clearly distinguishes it from sibling tools like hibp_get_breached_account_range and hibp_get_breached_domain. This gives the agent a precise, actionable purpose 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 context is clear: this tool is for searching breaches for one email address, so the primary use case is evident. It also provides refinement advice ('use domain and verification filters to refine the result'), but it does not explicitly name alternatives or state when not to use this tool in favor of a specific sibling. Since the intent is implied rather than exclusionary, it falls just short of a 5.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read operation. The description adds important behavioral context: it warns that a prefix alone cannot identify an account and that local comparison is required, which is beyond what annotations provide. This transparency helps the agent understand the purpose and limitations of the operation.

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 fluff. The first sentence states the action and the second provides the critical prerequisites and caveats. It is front-loaded with the essential action, then covers the necessary operational detail. 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 tool uses a non-trivial k-anonymity protocol and has a rich schema (with enums, defaults, and a custom response format), the description covers the essential usage context: authentication requirement, the local comparison step, and the endpoint nature. The output schema is present, so return values don't need explanation. The description is complete for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the security rationale for the prefix parameter and the local comparison requirement, which is not in the schema. The 'response_format' parameter is also explained in the schema (markdown vs JSON, structuredContent always returned). The description reinforces the key semantic of the prefix parameter beyond the basic pattern.

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 ('Query'), a specific resource ('HIBP k-anonymity breached-account range endpoint'), and a precise mechanism (first 6 characters of SHA-1 email hash). It clearly distinguishes from the sibling tool 'hibp_get_breached_account' by naming the k-anonymity range endpoint and the hash-prefix approach, which is a different API call.

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 a prerequisite ('Requires a subscription with k-anonymity access') and gives a critical usage instruction (compare returned suffix with remaining hash characters locally). It doesn't explicitly contrast with the sibling tools, but the purpose clarity already differentiates it from the direct account lookup. The when-to-use 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, idempotentHint, and destructiveHint, so the description does not need to repeat safety traits. It adds useful behavioral context by stating the OAuth/subscription requirement and the verified-domain prerequisite, which are not visible in the annotations.

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

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

Two sentences, no filler, with the core purpose front-loaded and the key requirement immediately after. Every sentence adds information.

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

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

Given that an output schema exists, annotations cover safety, and the four parameters are fully documented in the schema, the description supplies the missing context: what the tool returns and the access requirement. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

The input schema has 100% parameter coverage, so the baseline is 3. The description does not materially expand on parameter meaning beyond what the schema already states, such as 'verified domain to search' for the domain parameter.

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

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

The description opens with a specific verb and resource: 'Return breached aliases for a verified domain.' This clearly distinguishes the tool from sibling tools like hibp_get_breached_account and hibp_get_breached_account_range by focusing on domain-level aliases.

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 conveys clear usage context by requiring both a verified domain and an authorized subscription via OAuth bearer token. It does not explicitly name alternatives or exclusion conditions, but the prerequisites are stated directly.

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, covering the safety profile. The description adds minimal behavioral context: 'currently loaded into HIBP' indicates the result reflects the current state of HIBP's data. It does not mention rate limits, error conditions, or any other operational behavior, but given the annotations, this level is acceptable.

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 13 words, front-loaded with the verb and resource. There is zero waste and the key differentiator (latest breach) is immediately clear. It is appropriately sized 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 very simple tool with one optional parameter and a full output schema, the description is complete. The safety profile is covered by annotations, the parameter is covered by schema, and the purpose is clear. An agent has everything needed to 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 description coverage is 100%, so the single parameter 'response_format' is fully documented in the schema with its enum and default. The tool description adds no extra meaning to this parameter beyond what the schema already states. 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 verb 'Return' and a specific resource: 'the most recently added public breach currently loaded into HIBP'. It distinguishes this tool from siblings like hibp_list_breaches (which lists all) or hibp_get_breach (which fetches by name), as it focuses on the most recent addition.

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: if you need the most recently added breach, use this tool. However, it does not explicitly contrast with alternatives or provide when-not-to-use conditions. There is no mention of 'use instead of list_breaches' or 'only when the latest breach is needed'. The guidance is implicit rather than explicit.

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, so the safety profile is known. The description adds the authentication requirement (OAuth token + subscription) and the 'run separately' note, which are behavioral constraints not covered by annotations. It doesn't mention pagination or rate limits, but with annotations covering safety, this is adequate.

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 concise sentences with no filler. The primary purpose is front-loaded, followed by the critical auth requirement. Every sentence earns its place, and the structure is easy to parse.

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

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

The tool has an output schema, so return values are covered elsewhere. The description covers purpose, auth, and a key exclusion. It could also explicitly contrast with stealer-log tools (e.g., hibp_get_stealer_logs_by_email) which are siblings, but the term 'public pastes' is sufficiently distinct. Overall, it's complete for practical use, with minor room for more sibling differentiation.

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 each parameter has a clear description (account, limit, offset, response_format). The description itself adds no parameter-specific information beyond what the schema already provides. With full schema coverage, a baseline of 3 is appropriate.

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

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

The description states a specific verb ('Search for public pastes') and resource ('containing a single email address'). It also distinguishes from 'breached-account lookup' by name, which is a direct sibling in the list. This makes the tool's role clear and differentiates it from at least one key alternative.

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 says 'run this separately from breached-account lookup', providing an exclusion condition and naming the alternative. It also states a prerequisite: an OAuth bearer token and active HIBP subscription, which helps an agent decide if it can call this tool. This is clear guidance beyond mere purpose.

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, so the safety profile is covered. The description adds that this queries a 'public' API and returns 'matching suffixes with prevalence counts,' which provides some behavioral context beyond the annotations (e.g., external dependency, response shape). However, it does not discuss rate limits, error behavior, or any side effects, so it contributes only modestly beyond structured metadata.

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 core action and result. It contains no filler, redundancies, or extra clauses that dilute meaning. Every word contributes to understanding, and it is well-structured for quick parsing.

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 (6 parameters, but only 1 required) and the presence of an output schema, the description is largely sufficient. It explains the core operation and the response format (suffixes + counts) without needing to detail every parameter, since those are schema-documented. Missing context like 'check if a password is compromised' would be nice, but the description achieves functional 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?

All six parameters have descriptions in the schema, giving 100% coverage. The description repeats the prefix concept (SHA-1/NTLM) but adds no new parameter-level semantics beyond the schema. With full schema coverage, the baseline score of 3 is appropriate; the description does not need to add much, and it does not.

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 ('Query'), a clear resource ('Pwned Passwords k-anonymity API'), and the exact operation (using a 5-character prefix, returning suffixes with prevalence counts). This clearly distinguishes it from sibling tools that deal with breach lists, stealer logs, and subscription data, leaving no ambiguity about what this tool does.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, nor does it mention any conditions or exclusions. While the tool name and API reference imply it is for password-exposure checks, the description does not state this context or point to any sibling tools. An agent is left to infer the appropriate use case without explicit 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds important behavioral context: the requirement for an OAuth-linked active subscription with the stealer-log feature, and the differentiation that results are historical and do not establish current account access. This is especially valuable for avoiding misinterpretation of the data.

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 tightly written sentences with no filler. The core action and resource are front-loaded in the first sentence, and the follow-up sentence carries essential caveats about subscription requirements and data interpretation.

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 annotations, full schema coverage, and existing output schema, the description provides everything an agent needs to correctly select and invoke the tool: the resource returned, the required auth context, a key interpretation caveat, and enough scope to distinguish it from related siblings.

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 all four parameters with full coverage, so the description need not repeat parameter details. The description reinforces the semantic distinction that the primary input is an email address, not a domain, but it does not add meaning beyond the schema's existing 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 states a specific verb ('Return') and resource ('website domains historically observed in stealer logs') for a specific input ('an email address'), clearly distinguishing this tool from the sibling stealer-log tools that operate on email domains or website domains. It conveys exactly what the tool does in one sentence.

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

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

The description provides clear context that this is for lookup by a full email address, which implicitly differentiates it from the sibling tools by_email_domain and by_website_domain. It also notes a prerequisite (OAuth-linked active subscription with the stealer-log feature), but it does not explicitly name alternatives or state when to choose a sibling tool instead.

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 read-only, idempotent, non-destructive behavior, so the description's main job is to add context beyond that. It does: it discloses the subscription requirement and clarifies that results are historical and 'do not establish current account access,' which is valuable for interpreting the data's reliability. No contradiction with annotations exists.

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

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

Two sentences earn their place: the first states the core function and output, and the second adds the prerequisite and an important interpretive caveat. The information is front-loaded and there is 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 read-only tool with full parameter schema coverage, an output schema, and annotations, the description is nearly complete. It covers purpose, prerequisite, and data semantics. The only missing piece is explicit routing guidance relative to sibling stealer-log tools, but that is a minor gap given the clear resource naming.

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 four parameters (domain, limit, offset, response_format). The description adds no additional parameter-level detail; it only restates the domain-oriented purpose. This matches the baseline for full 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 uses a specific verb ('Return') and a specific resource ('stealer logs for an email domain'), and clarifies what is returned ('email aliases and associated website domains'). The phrase 'for an email domain' distinguishes it from sibling tools like hibp_get_stealer_logs_by_email and hibp_get_stealer_logs_by_website_domain, even though those are not named.

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

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

The description gives clear context: it is a domain-scoped stealer-log lookup, requires an OAuth-linked subscription, and carries a security caveat. However, it never explicitly says when to prefer this tool over the closely related email-address or website-domain variants, nor does it state any exclusions. Usage is implied by the domain-focused wording rather than made explicit.

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 signal read-only and idempotent behavior, so the description adds value by disclosing the OAuth-linked subscription requirement and importantly cautions that results do not establish current account access. This goes beyond the annotations and gives agents crucial interpretive context, though it stops short of covering other potential behaviors like rate limits or pagination quirks.

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 with no filler. The core purpose is front-loaded, and the subscription caveat is appended efficiently. 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?

The description covers the core purpose, the subscription prerequisite, and the key interpretive caveat. With an output schema present and fully documented parameters, nothing essential is missing for an agent to invoke the tool correctly. It is complete for its scope.

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

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

The input schema provides 100% coverage with descriptions for all four parameters, so the description does not need to add parameter-level detail. It adds no new semantic information about parameters, aligning with the baseline of 3 when schema 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 clearly states the verb 'Return' followed by the specific resource 'email addresses historically observed in stealer logs' and scopes it 'for a website domain.' The title and name further distinguish this from sibling tools that query by email or email domain, making the purpose unmistakable.

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

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

The description provides clear context that this tool searches by website domain and mentions the subscription requirement, which implies when it applies. However, it does not explicitly contrast with sibling tools (e.g., by email or by email domain) or state when not to use it, so it falls short of a perfect score.

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 meaningful details beyond the annotations (which already declare read-only, idempotent, non-destructive): it lists the exact data returned and mentions the authenticated OAuth connection. This gives the agent a clear picture of what the call will produce, though it doesn't discuss potential errors or rate-limit 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?

Two sentences, no wasted words. The primary purpose is stated first, followed by a practical use case. The description is well-structured and front-loaded with 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?

For a simple read-only status check with one optional parameter and an output schema, the description is complete. It specifies what data is returned, why to use it, and mentions the authentication context. No missing information that an agent would need to invoke it correctly.

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

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

The only parameter, response_format, is fully described in the schema (enum, default, description) with 100% coverage. The description adds no extra parameter semantics, which is acceptable since the schema already carries the load. 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 returns the current plan, quotas, rate limits, expiry, and feature flags for the active HIBP API subscription. This is a specific verb and resource that distinguishes it from all sibling tools, none of which appear to handle subscription status.

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 provides a use case: 'Use it to confirm access before feature-dependent lookups.' While it doesn't mention exclusions or alternatives, the tool is unique among siblings, so the context is clear. Could be improved by stating when it's not needed, but the guidance is strong.

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, so the safety profile is covered. The description adds little beyond the schema: 'public' is a mild contextual cue, but rate limits, pagination behavior, or the meaning of verification status are not disclosed. No contradiction with annotations.

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

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

A single, front-loaded sentence that communicates the core action and available filters without filler. It is appropriately compact for a tool with a well-documented 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 0 required parameters, a complete output schema, and full parameter documentation in the input schema, the description is sufficient for an agent to invoke the tool correctly. Missing sibling-differentiation guidance is a minor gap given the already-strong structured context.

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

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

Schema description coverage is 100%, so the schema carries the parameter documentation. The description names three filter dimensions (domain, spam-list flag, verification status) which loosely maps to domain, isSpamList, and includeUnverified, but it adds no new meaning 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's function: list public HIBP breaches, with optional filtering by domain, spam-list flag, and verification status. The verb 'List' and plural 'breaches' distinguish it from single-breach retrieval tools like hibp_get_breach, though it does not explicitly name or contrast siblings.

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

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

The description implies this is the tool for retrieving multiple breaches and optionally filtering them, which is a reasonable usage signal. However, it provides no explicit when-to-use guidance, alternatives, or exclusions such as when to prefer hibp_get_breach or hibp_get_latest_breach.

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, covering the safety profile. The description adds only the resource scope (public HIBP models) and example classes, but no additional behavioral details such as rate limits, pagination, or output nuances. This is consistent with annotations and meets the baseline for a read-only list tool.

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

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

The description is a single, front-loaded sentence with zero waste. It immediately states the action and subject, then gives illustrative examples. No unnecessary words or redundant restatements of the title.

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 low complexity (one optional param, output schema present, strong annotations), the description is fully sufficient. It communicates what the tool does, and the schema and output schema cover the remaining details like format options and return structure. Nothing an agent needs to invoke it correctly is missing.

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

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

The single parameter (response_format) is fully documented in the input schema with an enum, default, and description. The tool description adds no parameter-specific guidance beyond what the schema already provides, so the baseline of 3 applies 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 states a specific verb ('List') and a precise resource ('data classes used across public HIBP breach models'), and gives concrete examples ('email addresses or passwords'). This clearly distinguishes it from all sibling tools, which focus on specific breaches, accounts, or 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 clearly conveys the tool's scope and purpose ('data classes across public HIBP breach models'). While it does not explicitly name alternatives or state when *not* to use it, the unique focus on data classes makes the usage context obvious among the siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the notion of 'authenticated' subscription, indicating an authentication requirement, which is valuable context not present in annotations. However, it does not disclose other behavioral aspects like pagination behavior or rate limits, though these are partially implied by the parameters. Given the annotations cover the core safety semantics, a 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?

The description is a single sentence that front-loads the action ('List') and the target ('domains associated...'). There is zero superfluous text, and it is immediately scannable. This is a model of concise, effective tool 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?

The tool is a simple read-only listing with an output schema available, so return format is already specified. The description covers the core operation and the auth context. While it does not mention pagination defaults (limit=25, offset=0) or the behavior when no subscription exists, these are covered by the schema and the tool's simplicity. Overall, it is sufficiently complete for an agent to understand the operation.

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

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

Schema description coverage is 100%, meaning all three parameters (limit, offset, response_format) are fully documented in the schema. The description adds no parameter-specific details, but the baseline for high coverage is 3, so no penalty is incurred. The enums for response_format are already in the schema, so the description does not need to elaborate.

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 'List' and the resource 'domains associated with the authenticated HIBP subscription,' making the tool's purpose unambiguous. It is distinct from sibling tools like hibp_get_subscription_status (which likely returns subscription details) and domain verification tools, though it does not explicitly name any alternative. Overall it is specific and accurate, but lacks explicit sibling differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., having a valid subscription), nor does it contrast with domain-specific tools like hibp_verify_domain_verification_dns_token. The usage context is only implicit, so agents may not know if this is the right tool for a given task without further exploration.

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=false, idempotentHint=false, and destructiveHint=true, so the description does not need to re-state the mutation risk. It adds valuable behavioral context beyond annotations by mentioning the authentication requirement, the domain-verification access scope, and the 'approved alias' constraint. This helps the agent understand the operation's preconditions.

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 with no filler: the first states the action and resource, the second states the key prerequisite. The most important operational details are front-loaded and 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 rich input schema, output schema, and annotations, the description provides sufficient context: what the tool does, what alias it targets, and what permissions are needed. It does not mention rate limits or what happens after the email is sent, but those are not essential for correct invocation and the output schema covers the return contract.

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 input schema already documents 'domain' and 'emailAlias' fully. The description adds only minor illustrative value with 'admin or security' as alias examples, which does not materially expand meaning beyond the schema. 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 action: 'Send a domain verification email' to an approved alias, with a specific resource and a concrete example ('admin or security'). It is unambiguous about what the tool does, though it does not explicitly differentiate itself from siblings like hibp_generate_domain_verification_dns_token or hibp_verify_domain_verification_dns_token.

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 prerequisite ('Requires an authenticated subscription with domain-verification access') but gives no guidance on when to choose this tool over the DNS-token alternative or when not to use it. With siblings covering generate/verify DNS token flows, an agent is left to infer the routing logic.

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

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

The annotations already note idempotentHint=true and destructiveHint=false, and the description adds an authorization prerequisite not visible in the schema or annotations. It also clarifies that verification is performed by checking a TXT record, which is useful behavioral context beyond the structured fields.

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 tight sentences with no filler. The core action is front-loaded, and the follow-up sentence adds the essential access prerequisite.

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 output schema, high schema coverage, and annotations, the description covers the essential context needed to call this tool. It does not explicitly explain the relationship to the sibling token-generation or email-verification steps, but the tool name and sibling list make that inferable.

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 both 'domain' and 'response_format' clearly. The description adds little beyond referring to the 'target domain', so the baseline of 3 is appropriate.

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

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

The description states a specific action ('Complete domain verification') and the mechanism ('checking the expected HIBP TXT record'), making the tool's purpose clear and distinguishing it from sibling token-generation and email-verification tools. The target resource, 'the target domain', is also explicit.

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

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

The description provides clear context: this is the DNS-check step that completes domain verification, and it explicitly requires an authenticated subscription with domain-verification access. It stops short of a 5 because it does not explicitly name sibling alternatives or state when not to use this tool.

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