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

Going well beyond the readOnlyHint/openWorldHint annotations, it discloses the return shape (title, URL, HN link, points, comments, author, time for stories; 400-char HTML-stripped text plus story title for comments), the 50-result ceiling, the absence of an API key, and the exact cost model: $0.002 in USDC per successful call via x402 on Base, Solana or Arc, with failed calls uncharged.

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?

One dense, front-loaded paragraph: purpose first, then output shape, then bounds, then auth, then price. Every sentence carries information an agent needs before calling, with no repetition of the title or name.

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 payment-gated, read-only search tool with five optional parameters and a declared output schema, the description covers purpose, output, limits, auth and billing. Remaining gaps are minor: interaction between mode and the other filters, and any rate-limit or error behavior beyond the no-charge-on-failure promise.

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, but the description adds real semantics the schema does not: that mode=front yields stories only, that comment bodies are truncated to 400 characters with HTML stripped, and that the result ceiling is 50. It doesn't resolve ambiguity such as whether q is ignored in front mode or that all params are typed as strings in 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?

Names the concrete source (Hacker News via the Algolia search API) and the two operating modes, keyword search and front page, so the resource and verbs are unambiguous. What holds it below a 5 is that it never distinguishes itself from the sibling tool hn_search, whose name suggests exactly the same capability.

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 explains how to invoke each mode (q for keyword search, mode=front for the current front page, since for a date cutoff), which implies when each is appropriate. It never states when to prefer this over hn_search, nor any exclusion such as the fact that mode=front returns stories only and presumably ignores q or type.

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