search_hackernews

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

No annotations are present, so the description fully shoulders the behavioral disclosure. It details the return type ('JSON object with a hits array'), describes each hit's fields (id, title, url, points, author, num_comments, created_at, excerpt), and explains special cases such as comment hits where title/url/points are null and excerpt contains matched text. It also notes that an empty search returns {'hits': []} rather than an error. This comprehensive disclosure compensates well for the absent annotations.

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?

The description is concise and well-structured: a two-sentence intro, bullet points for parameters, and a final paragraph about response shape and edge cases. Every sentence contributes meaningful information; there is no redundancy or fluff. The structure is easy to parse for an AI agent.

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?

Given the tool's complexity (5 parameters, no output schema), the description covers all necessary aspects: parameter details, return format, and edge-case behavior (empty search). Minor omission: it does not mention pagination or whether multiple pages can be retrieved. The limit parameter suggests a single page, but explicit clarification would improve completeness.

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?

The input schema has 100% description coverage, so the baseline is 3. The description adds value beyond the schema by providing a concrete example for 'query' (e.g., 'rust async runtime'), reiterating enums with defaults, and clarifying the limit range. While some content mirrors the schema, the examples and additional phrasing enhance understanding for an AI agent.

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?

The description begins with a clear verb+resource: 'Search Hacker News stories and comments via HN's Algolia API.' It further elaborates use cases like 'find HN discussion on a topic, surface Ask HN / Show HN posts, or pull the most recent items,' making the purpose unmistakable. No siblings exist to differentiate, but the description is fully specific.

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 provides explicit context on when to use the tool (e.g., 'find HN discussion on a topic, surface Ask HN / Show HN posts, or pull the most recent items'). It does not include exclusions or alternatives because no sibling tools exist, but the use cases are clearly stated. Slight room for improvement: could mention that this is read-only and does not mutating Hacker News.

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