Hibp breach

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

Annotations declare openWorldHint=true, which the word 'proxy' implicitly reinforces by signaling an external third-party (HIBP) call — useful context. However, the description does not explain why readOnlyHint is false for what reads as a lookup, nor does it disclose rate limits, network dependency, or whether results are cached. With annotations covering the safety profile, a 3 fits.

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 padding. It is efficient, though its terseness leaves gaps that a second clause about the external dependency or inputs could have closed.

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 four-parameter, zero-coverage tool with no output schema and no required fields, a one-line description is not enough — the agent cannot tell which parameters matter, what the response contains (breach list, count, error?), or what an external failure looks like.

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 0% across four parameters, and the description only names 'username'. The generic wrapper parameters (form, params, json_body) are completely unexplained, and even the username parameter lacks format details (email vs. account name).

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

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

States a specific verb ('proxy ... lookup') and resource ('Have I Been Pwned breach') scoped to a username, which is clearly distinguishable from the surrounding vaultwarden CRUD tools. It stops short of explaining what 'proxy' implies about the underlying request, but an agent can identify the tool's function.

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?

There is no guidance on when to use this versus other lookup tools (e.g. vaultwarden_get_user_by_mail_json, vaultwarden_email), no prerequisites, and no mention of whether the username is an email, localpart, or user ID. The agent must infer the usage context entirely.

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