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

With no annotations, the description carries the full burden. It usefully discloses non-obvious aggregation behavior — that subdomains are rolled into the parent domain, with a concrete 'github.com'/'gist.github.com' example — but says nothing about result limits, ordering, or how the 'best stories' are ranked.

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, front-loaded with what the tool returns, followed by the subdomain caveat and the use case. Nothing is wasted and nothing important is 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?

No output schema and no annotations mean the description is the only source of truth, and it does describe the returned metrics at a high level. However, the undocumented `top` parameter and the absence of any ordering or result-size guidance leave a real gap for a two-parameter analytical 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 description coverage is 0%, so the description must compensate, and it only partly does: the 'github.com' example clarifies the format expected for `domain`. The `top` parameter is never mentioned, leaving the agent to guess that it controls how many best stories are returned.

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 resource and the outputs it produces: per-year volume, score stats, and best stories for a domain on HN. This is clearly distinguishable from siblings like search_stories or topic_trend, though no sibling is named 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?

'Useful to judge a source, blog, product or competitor' gives an implied use case but never states when to pick this over search_stories or topic_trend, nor any exclusions or prerequisites. Usage is inferable rather than 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 usefully discloses live fetching, HN ranking order, comment depth/author/reply count/plain text, and max_chars truncation. However, it omits operational behavior such as rate limits, authentication needs, error handling, or pagination limits.

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 short, front-loaded with the core action, and uses the remaining text efficiently to explain return structure and intended use. No sentence is wasted.

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 moderate-complexity read tool with no output schema and no annotations, the description does explain the return shape and ordering. It remains incomplete because it lacks parameter definitions for max_depth and max_comments and operational details such as rate limits or failure modes.

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%, so the description must explain all four parameters. It partially does: max_chars is explained via text truncation and depth semantics are mentioned, but max_depth as a limiting parameter, max_comments, and story_id are not explained.

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: fetch a story and its comment tree live from HN. It is clearly distinct from search-oriented siblings, but it does not explicitly name or differentiate against any sibling tool.

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: summarize a discussion or find the strongest arguments on each side. It does not mention when not to use it or which sibling tool to choose instead, so it falls short of full alternative 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?

With no annotations, the description must carry the full behavioral burden, and it partly does by disclosing the returned fields (story count, time span, data folder). It never states that the operation is read-only, that it requires no parameters, or that the output is a snapshot with no side effects, so important context is left for inference.

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?

It is a single compact sentence with the key information front-loaded and no filler. The phrasing is a noun fragment rather than a complete statement, which slightly reduces clarity but not brevity.

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 zero-parameter status tool with no output schema, the description lists the main fields returned and is just about sufficient. A little more on output format (for example, whether the times are ISO strings or when the index was last refreshed) would complete 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?

The tool takes zero parameters, so the schema does all the work and no parameter explanation is needed. Baseline 4 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 names the resource (the local index) and enumerates its coverage: story count, first and last story time, and data folder. That is specific enough to distinguish it from siblings like search_stories or run_sql, though it lacks an explicit verb such as 'report' or 'return'.

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 never states when to call this tool or which sibling to prefer — for example, checking index coverage before running a search — and gives no exclusions. The use case is only weakly implied by the list of fields.

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 provided, the description carries the full burden. It does disclose that results are 'top stories' ranked per year, that the date defaults to today in UTC, and that per_year controls volume, but it omits any statement about ordering, maximum volume, or the effect of min_score, so behavior is only partially characterized.

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 lines, front-loaded with the purpose and followed by the per-parameter hints; every sentence contributes. Slightly terse rather than padded, which is the right failure mode here.

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?

An output schema exists, so return values need not be explained, and the core framing is present. Still missing is any description of min_score, expected result volume across many years, and how this differs from sibling search tools for a zero-required-parameter, history-spanning query.

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% and three parameters exist, so the description must compensate. It adds genuine meaning for date ('MM-DD' format, UTC default) and per_year (count per year), but says nothing at all about min_score, leaving one parameter wholly undocumented.

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 first sentence states a specific retrieval action with a clear scope: top stories on a given calendar day across every year of HN history. It is distinguishable in concept from search_stories or search_recent, though it doesn't explicitly name those siblings to reinforce the contrast.

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 line 'Handy for "10 years ago today" content' implies a use case but gives no explicit when-to-use vs. when-not guidance and never names an alternative among the seven sibling tools. An agent can infer the context but must decide between this and search_recent on its own.

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 does disclose the important traits: read-only, exactly one SELECT, and only the `stories` table is queryable. It does not cover what happens on a rejected non-SELECT, query timeouts, or whether the result set is capped beyond the limit parameter.

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 capability and constraint are front-loaded, then a dense but fully earned column reference, then a one-line routing note. No filler and the most decision-relevant facts come first.

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?

An output schema exists, so return values need not be explained, and the schema of the queryable table is fully described. The remaining gap is the unexplained `limit` parameter and the absence of any note on error behavior for malformed SQL.

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%, so the description must compensate. It does valuable work by enumerating every column with type and semantics (UTC time, domain without 'www.', comments = descendants, text only for Ask/Show HN), which is exactly what the `sql` parameter requires. However, the `limit` parameter (default 200) is never mentioned in the description, leaving its effect undocumented anywhere.

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 ('Run one read-only DuckDB SELECT over the `stories` table') plus the intent ('for custom analysis'), which immediately distinguishes it from the curated siblings like search_stories and domain_report. It also names the boundary (comments require get_thread).

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?

Explicitly routes the agent to get_thread when comment data is needed and frames this tool as the escape hatch for 'custom analysis'. It does not say when to prefer the simpler siblings (search_stories, domain_report) over raw SQL, which is the one obvious routing decision left unstated.

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 burden alone. It does disclose something meaningful — that results come live from an external Algolia HN Search API, implying network latency and possible rate limits — but it says nothing about cost, throttling, error behavior, or ranking (though 'sort' default of points hints at ranking). For a zero-annotation tool this is thinner than ideal.

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 no filler, and the scope definition is front-loaded before the routing note. It is arguably over-terse given how little it says about the five parameters, but nothing present is wasted.

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?

An output schema exists, so return values need not be explained, and the freshness/routing guidance covers the main decision an agent faces. However, with 0% schema description coverage on five parameters (including the sort enum and min_points filter), the description does not close the remaining gap for a live external-search 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 description coverage is 0% across 5 parameters. The description only glosses 'days' via 'last N days'; query, sort (points/comments/new), limit, and min_points are left entirely to bare schema titles and defaults. The one enum and the min_points filter in particular deserve a sentence of meaning.

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 (search) and resource (stories) plus a clear scope: the last N days, executed live via Algolia HN Search. It implicitly distinguishes itself from the local-index sibling by saying 'newer than the local index', though it never names that sibling (search_stories) explicitly, which matters given the near-identical name.

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 for anything newer than the local index (see index_status)' gives an explicit selection condition and routes the agent to the sibling that tells it how stale the index is. It never states the inverse (use search_stories for older content) or when-not to use this, so it is clear context without full exclusion 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, so the description carries the full behavioral burden. It does well on matching semantics (AND-of-words, case-insensitivity, phrase quoting, prefix wildcard, inclusive date bounds, body vs title scope), but is silent on sort ordering, result limits, domain filtering, and pagination 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?

Front-loaded one-line purpose followed by per-parameter notes with concrete examples ('rust "memory safety"', 'agent*'). Every sentence adds information; nothing is redundant.

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?

The output schema exists, so return values need no explanation, and the query/date semantics are well documented. Still, four filter parameters (sort, limit, domain, min_score) are undocumented end-to-end, leaving an agent guessing about result volume and filtering.

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%, so the description must compensate — and it covers 4 of 8 parameters well: query syntax, since/until accepted formats, and include_text's effect. However, sort, limit, domain, and min_score receive no explanation in either the schema or the description, which is a meaningful gap for a filter-heavy 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 plus matching semantics: 'Search archived HN stories by title words (all must match, case-insensitive).' The word 'archived' implicitly contrasts with the search_recent sibling, but that contrast is never made explicit, so the agent must infer it.

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: 'Empty query lists top stories for the period' gives one useful fallback behavior, and 'archived' hints at recency scope. There is no explicit statement of when to pick this over search_recent, get_thread, or run_sql for text/topic research.

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 load and does well: it discloses matching behavior (whole-word, trailing * for prefix), the returned structure (per-term summary plus one row per period), and the normalization per 1,000 stories that makes periods comparable. It omits operational details like default time range when since/until are null and how granularity affects bucketing.

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?

Front-loaded with the core definition, then return shape, then a use case — every line is relevant. Slight verbosity in the return-shape sentence ('compact table: one row per period...') but 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?

The absence of an output schema is offset by a solid description of the return format, and the absence of annotations is partly offset by disclosed matching behavior. However, the missing time-range and granularity semantics leave an agent unable to call it precisely for anything but the default case.

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%, so the description must compensate. It adds real meaning for `terms` (whole-word vs prefix matching, example values) but says nothing about `since`, `until` (both untyped strings — format unknown), or `granularity` (the year/month enum and its effect on row bucketing), leaving three of four parameters undocumented.

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 computation over a specific resource: per-term occurrence counts within story titles over time, with explicit matching semantics. It is clearly distinct from retrieval siblings like search_stories and get_thread because it returns aggregates rather than stories, though no sibling is named directly.

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 via 'Good for "rise and fall" charts' with an example query. There is no explicit statement of when to prefer this over search_stories or run_sql, and no exclusions or prerequisites.

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