Hacker News Trending

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

No annotations are provided, so the description must disclose behavioral traits. It only states basic operation without mentioning rate limits, authentication needs, or return value details.

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?

A single, front-loaded sentence with no wasted words. Efficient and to the point.

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 simple fetch tool with one parameter and no output schema, the description does not hint at what the response contains (e.g., fields like title, score). It also does not differentiate from siblings, leaving gaps for an AI agent.

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 0%, yet the description only says 'by id' without explaining what 'id' represents (e.g., HN item identifier). The parameter meaning is implied but not explicitly clarified.

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 clearly states the tool fetches a single HN item by id, specifying it can be a story or comment. This distinguishes it from siblings like hn_search or hn_top.

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 guidance on when to use versus alternatives. Does not mention when not to use or compare to sibling tools.

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

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

No annotations are provided, so the description bears full burden. It mentions Algolia but fails to disclose rate limits, data freshness, pagination behavior, or auth requirements. The behavior is only superficially described.

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 a single sentence with no wasted words, efficiently conveying the core function and key filters. However, it could be restructured to separate purpose from usage notes.

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 should indicate return format or content. It does not. Additionally, it lacks behavioral context like result limits, sorting, or invocation side effects, leaving agents under-informed.

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 low (20%), yet the description adds value by naming three filter parameters (tags, min_points, days_ago). However, it does not explain the 'query' or 'limit' parameters beyond what the schema provides, and lacks format details for 'days_ago'.

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 clearly states 'Full-text search across all HN stories + comments' using a specific verb 'search' and resource. It distinguishes from siblings like hn_top or hn_item which are not search-oriented.

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 lists filtering options (tags, min_points, days_ago) but does not explicitly state when to use this tool versus alternatives like hn_top or hn_item. No usage preconditions or exclusions are mentioned.

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

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

With no annotations, the description carries the full burden. It discloses filtering by points and recency but doesn't describe the return format, pagination, or sorted behavior. While not contradictory, it lacks full transparency for a read tool.

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 two sentences with no wasted words. It front-loads the core purpose and includes a usage hint, earning 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?

Given no output schema and 3 parameters with 0% schema descriptions, the description is moderately complete. It explains key filtering but omits details about the returned data structure, sorting, or any other behavioral aspects.

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%. The description adds meaning to 'min_points' and 'days_ago' by explicitly referencing 'at least N points' and 'last K days', but it does not explain the 'limit' parameter. This partial compensation yields a score of 3.

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 clearly states the verb 'show' and resource 'Show HN launches', with specific criteria (at least N points in last K days). It distinguishes from sibling tools like hn_search and hn_top by focusing on recent product launches.

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 explicitly mentions usefulness for tracking new product launches in the indie/AI ecosystem, implying when to use it. It does not provide explicit exclusions or alternatives, but the context and sibling naming provide implicit guidance.

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

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

No annotations are provided. The description discloses the max return of 100 items (via parameter schema) and the default limit. It does not discuss rate limits, pagination, or whether this is a read-only operation. For a simple list tool, this is adequate but minimal.

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: the first defines the purpose concisely, the second details the parameters. No extraneous information. Efficient and well-structured.

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 has two optional parameters, no output schema, and no annotations, the description covers the key behaviors: what it fetches, the kinds available, and the limit range. It lacks output format details, but for a simple list tool, this is largely sufficient.

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 0% description coverage, so the description carries the full burden. It explains each kind value (e.g., 'ask' = Ask HN) beyond the raw enum, and notes the limit maximum. This adds meaningful context beyond the schema's structure.

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 clearly states it returns 'Current Hacker News front-page stories' and lists the specific kinds (top, best, new, ask, show, job). This sets it apart from sibling tools like hn_item (single item) and hn_search (search).

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 implies usage for fetching front-page stories by kind, with a limit on items. It does not explicitly state when to use this tool versus siblings like hn_search or hn_user, nor does it provide exclusion criteria. The context is clear but lacks comparative guidance.

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

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

No annotations are provided. The description discloses that it returns karma, account age, and recent submissions, but does not mention behavioral traits like data freshness, rate limits, or whether it's read-only. For a simple tool, this is adequate but not thorough.

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 a single sentence that is both concise and informative, front-loading the core purpose. Every word adds value, no redundancy.

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 simplicity (one parameter, no output schema), the description is mostly complete. It could explicitly state that 'handle' is the HN username, but the context is clear. The output fields are named well.

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 only parameter 'handle' is not described beyond its type. With 0% schema description coverage, the description adds no semantic meaning. However, 'handle' is intuitively a username, so 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?

The description explicitly states it retrieves HN user profile including karma, account age, and recent submissions. It clearly distinguishes from sibling tools like hn_item (items) and hn_search (search) by specifying it's about user profiles.

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 implies usage for getting user info but does not explicitly state when to use this tool over alternatives. No guidance on prerequisites or scenarios.

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