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

Annotations only declare the safe-read profile (readOnly/openWorld/idempotent); the description goes well beyond them by disclosing that this is a paid tool, the payment rail (x402 USDC on Base), the exact price ($0.002 per successful call), and the failure mode of calling unpaid (a PaymentRequired object is returned). It also notes comments are capped and HTML-stripped to plain text, which shapes what the agent will actually receive.

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?

Front-loaded with purpose followed by return contents, then usage and alternative routing, then the payment caveat in a final sentence. Every sentence carries information, though the payment/URL detail makes it denser than strictly needed for selection alone.

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 no output schema, the description takes responsibility for describing the return shape (story fields plus threaded comments with depth/author/time/plain text), and it covers the commercial prerequisite an agent must know before calling. Nothing material for correct invocation 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?

Schema description coverage is 100%, so both 'id' and 'limit' are already documented, and the schema is the authority on the 1-300 range. The description adds only light framing — that limit caps comments returned in thread order — which does not exceed 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?

States a specific verb and resource ('read the discussion on a Hacker News post') and enumerates exactly what comes back: story fields (title, URL, points, author, time) plus comments with depth, author, time and stripped plain text. This separates it cleanly from hn_search (searching) and from the Pulse endpoint that serves HN list feeds.

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?

Gives an explicit use case ('summarising community reaction to a launch') and routes a competing need — the live front page, new, best, Ask HN, Show HN and job lists — to a named alternative with a URL. It does not, however, differentiate itself from the hn_search sibling, so the routing is clear for list feeds but incomplete against the closest HN-adjacent tool.

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