Hacker News MCP by Nova (CIVAI)

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

No annotations are provided, so the description carries the full behavioral burden. 'Fetch' implies a read operation, but the description does not mention authentication, return behavior, pagination, rate limits, or what happens when the follow-up reply fails, despite the notification_message parameter gesturing at that scenario.

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 short sentences with zero waste. The purpose is front-loaded and the usage guidance follows 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?

For a simple read-only listing tool with two optional, fully documented parameters and no output schema, the description is largely complete. It could mention what the response contains, but the purpose and usage guidance are sufficient for correct invocation.

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 parameters are already documented in the input schema. The description adds no parameter-specific meaning, which is acceptable given the high schema coverage baseline.

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 states a specific verb and resource: fetching best-ranked Hacker News stories. It implicitly distinguishes this from sibling feeds like top_stories and new_stories by naming the 'best feed,' though it does not explicitly name alternatives.

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?

It gives a clear use case: when the user asks for best posts or all-time greats on the best feed. It does not state when not to use it or name alternative sibling tools such as search_stories or top_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?

With no annotations, the description carries the burden, and it does add real signal by disclosing that this scrapes an HTML feed (hence the row-parsing limit) rather than using an API. It says nothing about auth requirements, rate limiting, failure behavior, or what a parsed result looks like, which matters for a scraping 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?

A single sentence with zero padding, front-loading the verb, the resource, the host, and the valid targets. Every element 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?

There is no output schema and no annotations, so the description should clarify the return shape (parsed rows) and the effect of story_limit on results. It covers what can be browsed but leaves the response contract and selection guidance largely implicit, which is only just adequate for a 3-parameter scraping 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?

Schema coverage is 100%, so the schema already documents all three parameters, and the description's feed list merely repeats the feed_name enum values verbatim. It adds no meaning for story_limit or notification_message beyond what the schema states, so the baseline of 3 applies.

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 (browse) and resource (an HTML feed on news.ycombinator.com) and enumerates the valid feed targets, so the action is unmistakable. It does not differentiate itself from siblings like top_stories, best_stories, or new_stories, which appear to cover overlapping feed content via a different mechanism.

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?

Usage is only implied: reading HN pages. There is no statement of when to prefer this over top_stories/new_stories/best_stories, nor any exclusions or prerequisites (e.g., whether login is needed). The agent must infer the alternatives itself.

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 must carry the behavioral burden. It usefully discloses that top-level comments are included when available, but it does not state read-only safety, authentication expectations, missing-id behavior, or rate-limit characteristics.

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 well-formed sentence with the primary action front-loaded and no filler. Every clause contributes to purpose or output scope.

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 two-parameter read tool with full schema coverage, the description gives enough to select and call it, including the notable return behavior of top-level comments. It could be slightly more complete about error handling or the notification_message side effect.

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 parameters are already documented in the schema. The description only repeats that lookup is by numeric id and adds no new meaning for item_id or notification_message.

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 (get), resource (Hacker News item), lookup key (numeric id), and scope (story or comment thread plus top-level comments). This clearly distinguishes it from sibling list/search tools like best_stories, search_stories, and get_user.

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 phrase 'by numeric id' implies the tool is appropriate when an item id is already known, but it never explicitly says when to prefer this over search_stories or browse_feed. Usage is inferable rather than stated.

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 implies a read-only lookup and enumerates the returned fields, which is useful. However, it says nothing about behavior on unknown usernames, rate limits, or authentication requirements, and it is silent on the unusual notification_message parameter's purpose.

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?

One well-formed sentence with the verb and scope front-loaded and no filler. It is appropriately sized, though it uses its brevity to omit rather than to prioritize information.

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?

Without an output schema, the description helpfully lists the returned fields, which covers the happy path. It leaves out error/not-found behavior and the second parameter's semantics, so a read-only lookup tool is only adequately described.

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 100%, so the baseline is 3; the description only repeats the username concept already documented in the schema. It adds no meaning for notification_message, which is arguably the parameter most in need of explanation.

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?

Specific verb+resource: "Look up a Hacker News user profile ... by username", and it names the payload (karma, about, created date). It is clearly distinct from the story/comment siblings, but it never states that distinction explicitly, so it falls short of a 5.

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 when-to-use guidance, no exclusions, and no routing to alternatives such as login or session_status, which could plausibly be confused with user identity lookups. The agent must infer usage purely from the tool name.

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 disclosure burden and usefully states that login stores a session cookie in hn_session_cookie. However, it omits important behavior around invalid credentials, existing sessions, cookie lifetime, security implications, and failure modes.

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 definition is two compact sentences with the core action front-loaded and the cookie-storage consequence immediately following. There is no redundant or filler language.

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 three-parameter authentication tool with no output schema and no annotations, the description gives enough context to call it: credentials are required and a session cookie is stored for later authenticated actions. It could be more complete by explaining session reuse and failure behavior, but the essential invocation context is present.

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 description mentions username and password, matching the two required parameters, but adds no syntax, format, or validation details beyond the schema. Because schema description coverage is 100%, the baseline of 3 is appropriate, and the optional notification_message parameter is left entirely to the 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 states a specific verb and resource: sign in to Hacker News using username and password. It also names the resulting session-cookie behavior, making the tool distinct from browsing and content-action siblings, though it does not explicitly contrast with session_status.

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?

It gives clear usage context by saying the stored session cookie is for upvote, comment, and submit, which tells an agent when authenticated actions depend on this tool. It does not spell out exclusions, such as checking session_status first or avoiding redundant login calls.

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 carries the full behavioral burden. It never says whether the response is a list of story IDs or full story objects, whether results are paginated, or how ordering is determined beyond 'newest' — all of which matter for deciding whether follow-up get_item calls are needed.

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 short sentences, purpose first, trigger condition second. No filler and nothing buried.

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 annotations and no output schema, the description is the only place return-shape information could live, and it omits it entirely. For a list-fetching tool whose output type determines the next tool call, that is a meaningful gap.

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 parameters (story_limit, notification_message) are already documented in the schema. The description adds no meaning beyond it — notably it doesn't explain what happens if story_limit is omitted or how the notification message is surfaced.

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 ('Fetch') and resource ('newest Hacker News story submissions'), and the word 'newest' implicitly separates it from siblings like top_stories and best_stories. It does not name those siblings explicitly, so the differentiation is inferential rather than stated.

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?

'Use when the user asks for new or latest posts' gives a concrete triggering condition that an agent can match against user intent. It stops short of naming alternatives (top_stories, best_stories, search_stories) or stating when not to use it.

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 supplied, so the description carries the whole behavioral burden for a mutation tool. It discloses the auth requirement, which is real value, but says nothing about whether the comment is immediately public, whether it can be edited or removed, rate limits, or what a success response contains — despite the notification_message parameter hinting at a follow-up failure path that is left unexplained.

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 short sentences with zero filler, and the core action is front-loaded before the threading detail and the login prerequisite.

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 mutation tool with no annotations and no output schema, the description should say what happens on success and how the notification_message failure path works. It covers the action and the auth prerequisite but leaves the outcome and error behavior for an agent to guess.

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 100%, so all three parameters are already documented in the schema, and the description's note that parent_id is 'the story or comment id' merely restates the schema. Baseline 3 applies since the schema does the heavy lifting.

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 — 'Post a comment' — and clarifies it works on both stories and reply threads. This clearly separates it from sibling write tools like submit_story and upvote, though the description never names those siblings explicitly.

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 only guidance is the prerequisite 'Requires login session', which is useful but is a precondition rather than a when-to-use rule. There is no statement of when to prefer this over other tools, and no exclusions or failure conditions an agent should anticipate.

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 carries the full behavioral burden. It helpfully identifies the public Algolia API and its hn.algolia.com backend, which implies a read-only, unauthenticated search, but it does not disclose result ordering, pagination, rate limits, or what the response contains.

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 front-loaded sentence with no redundant wording. Every phrase adds either the resource, the action, or useful backend context.

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 search tool with a fully documented schema and no output schema, the description is minimally adequate. However, it omits important search behavior such as result ordering, pagination, and return shape, leaving meaningful gaps for an agent deciding how to invoke and interpret it.

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 all three parameters are already documented in the input schema. The description adds no parameter-level meaning such as query syntax, default behavior for story_limit, or the purpose of notification_message, so baseline 3 applies.

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 states a specific verb ('Search') and resource ('Hacker News stories') and identifies the backend API. It is clear what the tool does, though it does not explicitly differentiate itself from sibling list tools such as best_stories, new_stories, or top_stories.

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 word 'Search' implies keyword-based lookup and therefore contrasts implicitly with browsing top/new/best stories, but the description gives no explicit when-to-use guidance, no exclusions, and no named alternatives. Usage is inferable but not directed.

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, and it does establish the key trait: this is a non-mutating check against the HN session cookie, implicitly read-only. However it says nothing about what a positive/negative result looks like or whether the check is local vs a network round-trip.

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?

One sentence, front-loaded with the verb and the resource, with zero filler. Nothing could be removed without losing information.

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?

No annotations and no output schema, yet the description never indicates the shape of the answer (boolean, status string, expiry info), which is the single most important thing an agent needs from a status tool. Adequate on what it checks, silent on what it returns.

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 the single notification_message parameter is fully documented in the schema and the baseline of 3 applies. The description adds no meaning about when that message is surfaced or why a status check needs a failure message.

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?

A specific verb ('Check') and a well-defined resource (presence/validity of hn_session_cookie on Hacker News) make the tool's job unambiguous. It doesn't explicitly name the sibling it differs from (login), so it stops short of full sibling differentiation.

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 never states when to call this versus login, or what to do with a negative result. Usage is only implied by the concept of checking session state, leaving the agent to infer the routing.

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 must carry the behavioral load, and it does disclose the auth requirement ('Requires login') — genuinely useful pre-call context. It says nothing about what is created, what the response returns, rate limits, or what happens if both URL and text are supplied.

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 short sentences, purpose first, then prerequisite, then parameter selection — nothing redundant and no filler.

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 4-param mutation tool with no annotations and no output schema, the description covers purpose, auth, and the key parameter decision. It omits what success returns and does not mention notification_message, though the schema documents that parameter adequately.

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 100%, so the baseline is 3. The description restates the story_url/story_text split already present in the schema property descriptions, adding only a light either/or framing rather than true exclusivity semantics (e.g. whether exactly one is required).

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?

Specific verb+resource ('Submit a new story link or Ask HN text post') that clearly separates this from post_comment or upvote in the sibling list. It does not explicitly name a sibling to contrast with, but the resource noun does the disambiguation work.

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 the selection rule between the two modes ('story_url for link posts or story_text for text posts') and states the login prerequisite, which is a real gating condition. No explicit when-not or alternative-tool routing, so it stops short of a 5.

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 must carry the behavioral burden. It discloses the backing API (official Firebase) and that this is a fetch, implying a safe read, but says nothing about ordering guarantees, result freshness/caching, or what a returned story looks like.

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 short sentences, front-loaded with the action and followed by the usage trigger. Minor padding in 'via the official Firebase API', which is contextual rather than essential.

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?

There is no output schema, so the description is the only place a return-shape hint could live, yet it never indicates what a story object contains (title, score, URL, etc.). For a simple fetch tool this is adequate but leaves a gap an agent must discover by calling.

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 100%, so both parameters are already documented in the schema and the baseline is 3. The description adds no meaning to either, and notably does not explain the purpose of notification_message in a read-only fetch tool.

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 ('Fetch the current Hacker News front page (top stories)') plus the data source. It does not differentiate itself from sibling feeds like best_stories or new_stories, which an agent could plausibly confuse with 'top' stories.

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?

'Use when the user asks for top, front, or trending stories' gives a clear invocation trigger. It stops short of naming alternatives or exclusions (e.g. when to prefer best_stories or new_stories over this), so routing between sibling feed tools is left to inference.

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?

Without annotations, the description carries the full burden: it does disclose the auth requirement (session cookie from login), which is real behavioral context beyond the schema. But it omits mutation-relevant traits such as idempotency (already-upvoted items), failure modes, rate limits, and whether the action can be undone.

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 short sentences, zero waste, with the core action front-loaded and the prerequisite following. Nothing could be removed without losing information.

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 an unannotated mutation tool with no output schema, the description covers the action and auth prerequisite but says nothing about the response, idempotency, or error behavior when voting fails or the cookie is invalid. Adequate minimum, but leaves real gaps an agent would want filled.

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 parameters are already documented, establishing a baseline of 3. The description adds only that item_id may refer to either a story or a comment, a mild clarification beyond the schema text.

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 ('Upvote') and resource ('a story or comment by item id'), and the resource scope distinguishes it from read siblings like get_item and browse_feed. An agent can tell immediately what this does without opening the schema.

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 prerequisite 'Requires a valid hn_session_cookie from login' implies the login sibling must be called first, which is useful routing. However, there is no guidance on when not to use it, no mention of what happens if already voted, and no exclusions relative to other write tools.

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