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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine behavioral context: it enumerates the returned fields (total matches, unique scans, first/last seen, prevalence label, matching scripts) and explains the side effect of include_scans and the date-range scoping. Pagination/limit behavior is left unstated.

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 tight sentences with zero filler; the core lookup and its return payload are front-loaded, followed by the parameter effects and a one-line interpretive note that 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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes them usefully. Combined with annotation coverage, an agent has enough to call this correctly; only the limit parameter's behavior is left ambiguous.

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%, so the description must carry the load, and it does for three of five parameters: include_scans ('adds the scans') and from_date/to_date ('limit the period'). hash_value is self-evident from the tool name, but limit is never explained in either place.

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 and resource (look up a JavaScript file by SHA-256) plus the exact output shape (prevalence, matches, scans, first/last seen). The hash-type qualifier implicitly distinguishes it from the sibling MD5/SHA1/normalized-hash search tools.

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

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

Usage is implied: you need a SHA-256 hash to call it, and the closing sentence gives interpretation guidance ('a rare hash shared by several phishing pages usually means one kit'). However, no sibling alternative is named and there is no when-not guidance (e.g., when to prefer the fuzzy-hash or similarity tools).

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