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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds real value beyond them by listing the default return fields (title, points, num_comments, author, created_at, url, objectID) and the relevance sort, which matters given there is no output schema. It stops short of disclosing pagination 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 with no padding, but the second is a run-on that bleeds purpose, sort order, and a long field list together ('by relevance Returns title...'), and the command-equivalence note is parenthetical noise for most readers.

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 search tool with no output schema, the description supplies the essential default return fields, which is the main missing piece. However, it leaves pagination parameters (page vs limit vs hitsPerPage) unexplained, an agent cannot confidently page or bound results from the description alone.

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 only 33% (only tags and fields are annotated), so four parameters (query, page, limit, hitsPerPage) are undocumented in both schema and description. The description explains none of them, including the ambiguous overlap between limit, hitsPerPage, and page. It fails to compensate for the coverage gap.

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+resource: search Hacker News stories/comments by relevance via hn.algolia.com. It is clearly distinguishable from the sibling data-lookup tools (crates, pypi, wikipedia) and even names its clify_run equivalent. Lacks explicit sibling differentiation for the clify_* tools beyond the command equivalence note.

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 explicit when-to-use or when-not guidance. The parenthetical that it equals 'clify_run site=hnsearch command=search' is a useful routing hint, but no conditions select this tool over clify_run directly, nor any exclusions.

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