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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a genuine behavioral trait beyond that: the no-query default behavior and the default category (cs.AI), which an agent needs to predict results. It still omits pagination and return-format details, keeping it below 5.

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 tight sentences, front-loaded with the core purpose followed by the no-query behavior and category reference. Every clause carries information; nothing is 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 read-only search tool with no output schema, the description covers purpose, default behavior, and the category domain an agent needs to call it correctly. The unexplained 'sort' enum is a minor residual gap, not a blocker.

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 only 60%, so the description must carry weight, and it does: it supplies the concrete category vocabulary (cs.AI, cs.LG, cs.CL/NLP, cs.CV, cs.RO, cs.SE, stat.ML) and the default category, which the schema only gestures at with an example. It does not explain the 'sort' enum or 'limit' bounds, so it doesn't fully compensate for the gap.

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 ('Search arXiv papers'), so the agent immediately knows this retrieves academic preprints rather than news (hackernews_*) or repos (github_trending). Sibling differentiation is implicit via the resource domain rather than by naming an alternative, which keeps it just 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?

The description does describe one important usage mode: with no query it returns the latest submissions, defaulting to cs.AI. However, it gives no guidance on when to pick this over the sibling tools (tech_trends_digest, hackernews_search) or on which sort mode to choose, leaving usage largely implied.

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 declare readOnlyHint=true and openWorldHint=true, so safety and external-data nature are covered. The description adds nothing behavioral beyond that: no mention of the 25-item cap, the daily/weekly/monthly windows, rate limits, or how results are ordered. With annotations carrying the safety profile the bar is lower, but this description contributes no additional behavioral context.

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 and the core resource stated first. It is terse, though whether that brevity reflects conciseness or under-specification is arguable.

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 4-parameter read-only tool with no output schema, the description is minimally adequate. It omits the limit cap of 25, the daily/weekly/monthly time windows, and the spoken_language filter, leaving the agent to read the schema for the tool's actual scope.

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 50%: language and spoken_language are documented in the schema, while limit and since are not. The description only restates the language filter, which the schema already explains, so it adds no meaning for the undocumented limit ceiling or the since enum.

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 ("Get trending GitHub repositories") and names the filtering dimension, so an agent immediately knows what it returns. It is implicitly distinct from the news/paper siblings, but the description never explicitly contrasts itself with tech_trends_digest or the other trend sources.

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?

"optionally filtered by programming language" hints at one usage mode but gives no when-to-use context, no prerequisites, and no routing versus siblings like tech_trends_digest. An agent gets no guidance on when GitHub trending is the right source over the 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful detail that results come from Algolia full-text search, but says nothing about result ordering defaults, the 50-result cap, pagination, or how the filters interact - gaps an agent would hit in practice.

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 purpose and the backing data source. Nothing is padded or repeated from the title.

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 carries the burden of describing what comes back, and it does not - no indication that results are stories with points, comment counts, URLs, or timestamps. Combined with 20% parameter coverage and silent filtering semantics, an agent lacks what it needs to interpret results.

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 only 20% (just days_back is documented), yet the description names no parameters at all - not sort, limit, min_points, or days_back. With four of five parameters undocumented in both places, the description fails to compensate for the coverage gap.

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 - full-text search of Hacker News stories - and even cites the backing engine (Algolia). It does not, however, differentiate itself from the sibling hackernews_stories or hackernews_thread tools, so an agent must infer which entry point fits a given query.

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 to find discussion about a topic, product or paper" gives an implied use case, but there is no when-not guidance and no mention of the sibling search/listing tools to route between. The agent gets a nudge, not a decision rule.

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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description only adds 'current', implying live/fresh data rather than historical archives, but says nothing about pagination, result ordering, or how the limit interacts with the feed.

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 filler; the resource and the feed variants are stated immediately. Slightly awkward parenthetical aside, but nothing that wastes the agent's attention.

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 feed lister this is close to adequate: annotations cover safety and the enum covers valid feed values. Missing pieces are the default limit behavior and what a returned story contains, and with no output schema the description could have said more about the return shape.

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 carry parameter meaning. It does enumerate the five feed values for the 'feed' parameter (matching the enum), but the 'limit' parameter (default 20, max 50) is never mentioned, leaving half the parameters unexplained.

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 a specific verb ('Get'), resource ('Hacker News ... stories'), and scope (five feed variants: top, new, best, ask, show). It clearly distinguishes a feed-browsing tool from a keyword search, but never names the siblings (hackernews_search, hackernews_thread) it should be chosen over or alongside.

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 implied by enumerating the feeds ('front page (top), newest, best, Ask HN or Show HN'), so an agent can infer this is for browsing ranked story lists rather than searching. However, there is no explicit when-to-use guidance and no mention of hackernews_search as the alternative for keyword queries, leaving the routing decision 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-fetch behavior are covered. The description usefully confirms the scope is a thread plus its top comments, but says nothing about rate limits, failure modes for bad IDs, or how the comment tree is shaped.

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 compact sentence with the core action front-loaded and no filler. There is little structure to speak of, but nothing 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?

With no output schema, the description could say more about what the returned thread looks like (nested comments, truncation behavior). Annotations cover the safety profile and the schema covers every parameter, so it is adequate but not fully self-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?

Schema description coverage is 100% and all three parameters carry their own descriptions and bounds, so the schema does the heavy lifting. The tool description adds nothing about the meaning of 'depth' or 'max_comments' beyond what is already documented.

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 concrete verb ('Read') and resource ('a Hacker News story or Ask HN post with its top comments'), so the agent knows exactly what it returns. It does not distinguish itself from siblings like hackernews_search or hackernews_stories, leaving the agent to infer the boundary.

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 trailing clause 'to summarise what people are saying' implies a use case, but there is no explicit when-to-use guidance, no exclusion rules, and no named alternative for fetching a single item vs. searching or listing 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the live/recency dimension ('right now') and that it is a single combined call, but says nothing about freshness guarantees, per-source failure behavior, latency, or the shape of the merged result. Useful but thin against a lower annotation bar.

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 tight sentences with the deliverable front-loaded and the use case as a second beat. No redundant restatement of the title, no filler; every clause adds 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?

There is no output schema, so the description should convey something about what the digest returns (per-source sections? counts? links?), and it does not. Combined with 3 undocumented parameters, an agent knows the intent but not the inputs' accepted values or the response structure.

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 3 parameters, so the description carries the burden. Naming 'arXiv papers' and 'GitHub Trending' loosely maps to arxiv_categories and github_language, but per_source is never explained, and no defaults (cs.AI/cs.LG/cs.CL, 10) or the max of 25 are surfaced. Partial compensation only.

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 deliverable ('one-shot digest of what's trending right now') and enumerates the exact three sources it aggregates: HN front page, arXiv, and GitHub Trending. Because those are the very resources the sibling tools (hackernews_stories, arxiv_search, github_trending) target individually, the aggregation framing implicitly distinguishes this tool from all of them.

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 a clear use-case trigger: 'Good starting point for "what's new in tech/AI today?"'. That tells the agent when this tool is the right first call. It stops short of explicit exclusions or naming siblings (e.g., 'use arxiv_search for targeted queries instead'), so it is context without routing.

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