hn-mcp-server

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

Annotations declare readOnlyHint=true, confirming safe read operations. The description adds valuable context beyond annotations by specifying the return payload structure ('enriched story objects with title, URL, score, author, and comment count'), which helps the agent understand what data to expect even before examining the output schema.

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 consists of two efficient sentences with zero waste. The first front-loads the core action and resource, while the second immediately clarifies return value structure. Every word earns its place; no filler or redundant explanation.

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 complete parameter schema coverage, readOnly annotations, and an output schema exists, the description provides appropriate completeness. It summarizes the return values and feed options adequately. Could be improved by mentioning rate limits or error behaviors, but this is sufficient for a straightforward feed-fetching tool.

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?

With 100% schema description coverage, the baseline is appropriately 3. The description lists the feed enum values but doesn't add semantic meaning beyond what's in the schema (e.g., it doesn't explain pagination strategy beyond the schema's offset/count descriptions or expand on the performance implications mentioned in the count parameter description).

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 'Fetch' and resource 'stories from an HN feed', explicitly listing all six feed types (top, new, best, ask, show, jobs). It clearly distinguishes from siblings: hn_get_thread (comments), hn_get_user (profiles), and hn_search_content (keyword search) by specifying this is for feed retrieval.

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?

While the description doesn't explicitly name siblings or state 'use this when...' rules, it implies usage by enumerating the specific feed types available. The schema description for the 'feed' parameter adds context about 'top' including jobs and 'ask/show' being specific post types, which helps guide selection, but lacks explicit comparison to search or thread retrieval alternatives.

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?

Annotations declare readOnlyHint=true indicating safe reads. The description adds valuable behavioral context: 'Recursively resolves child comments' explains the tree traversal behavior, and 'With depth 0, returns just the item' discloses the parameter-dependent behavior mode. It does not contradict 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?

Three sentences with zero waste: first defines core operation, second discloses recursion behavior, third explains the depth=0 edge case and secondary purpose. Information is front-loaded with the primary action 'Get an item' appearing immediately.

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 rich schema (100% coverage), presence of output schema, and readOnly annotation, the description appropriately covers the tool's purpose and key behavioral quirks (recursion, dual-use as lookup) without needing to duplicate parameter documentation or return value specifications.

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%, establishing a baseline of 3. The description mentions 'depth 0' specifically, adding minor semantic context linking the parameter to the 'item lookup' use case, but does not significantly expand on the well-documented schema parameters (depth, maxComments, itemId).

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 uses specific verb 'Get' with clear resource 'item and its comment tree as a threaded discussion.' It implicitly distinguishes from siblings hn_get_stories (list operation) and hn_get_user (profile focus) by emphasizing the threaded/comment tree aspect, and explicitly notes it 'doubles as an item lookup' distinguishing from 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 provides implied usage guidance by noting the tool 'doubles as an item lookup' when depth is 0, suggesting when to use it for simple item retrieval. However, it lacks explicit when-to-use comparisons against siblings like hn_search_content or guidance on choosing between this and hn_get_stories.

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?

Annotations declare readOnlyHint=true. Description adds that submissions are 'resolved into full items' (valuable behavioral detail), but omits rate limits, caching behavior, or error conditions.

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?

Single dense sentence of 19 words front-loads the core action ('Get an HN user profile') with zero redundancy; every clause earns 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?

Adequately complete given the output schema exists; covers primary return values and optional behavior, though could explicitly acknowledge the username parameter as the lookup key.

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?

With 100% schema coverage, description appropriately adds semantic value beyond the schema by clarifying that submissions are 'resolved into full items'—explaining the data transformation performed by the includeSubmissions flag.

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?

Uses specific verb 'Get' with clear resource 'HN user profile' and lists distinguishing data fields (karma, about, submissions) that clearly differentiate it from sibling tools focused on stories, threads, or 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?

Provides implied usage guidance by explaining the optional submissions resolution behavior, but does not explicitly state when to use this tool versus sibling tools like hn_search_content or hn_get_stories.

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?

Annotations already establish readOnlyHint=true, so the description is not burdened with safety disclosures. It adds context by identifying 'Algolia' as the search backend, which hints at query behavior, but it does not disclose rate limits, indexing delays, or pagination mechanics beyond what the schema provides.

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, zero redundancy. The first establishes the core operation and platform; the second summarizes filtering capabilities. Every word earns its place and the most critical information is front-loaded.

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 rich input schema (100% coverage), presence of an output schema, and readOnly annotations, the description successfully establishes the tool's domain without needing to replicate parameter or return value documentation. It could be improved by mentioning result pagination behavior or result set characteristics (e.g., 'returns ranked hits').

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?

With 100% schema description coverage, the baseline is 3. The description maps high-level concepts ('content type, author, date range, minimum points') to specific parameters, providing a useful summary, but does not add syntax details or semantic constraints beyond the already comprehensive 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?

The description opens with a specific verb ('Search') and clear resource ('Hacker News stories and comments'), and specifies the backend ('via Algolia'). This clearly distinguishes it from sibling 'get_' tools which retrieve specific items by ID rather than performing full-text 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 lists capabilities ('Supports filtering by...') which implies when to use the tool (when filtering is needed), but it does not explicitly state when to use this versus siblings like 'hn_get_user' or 'hn_get_stories'. The explicit contrast found in the 'author' parameter description is not reflected in the main description text.

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