News by Hottub

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered; the description adds real behavioral content by disclosing that the return includes per-entity mention counts scoped to the last 7 days, a recency constraint the annotations do not convey. It still doesn't say how ambiguous names are resolved.

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 that front-loads the action and return, then ends with the downstream routing instruction. Examples are inline and earn their 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?

No output schema exists, and the description does cover the shape of the return (Wikidata ids plus 7-day mention counts) and how to consume it. The main missing piece is disambiguation behavior when a name maps to several entities.

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 the parameter burden, and it does partially by indicating `q` is a plain name with examples ("Tesla", "Lagos"). It does not say whether matching is fuzzy, case-sensitive, or whether multiple names can be passed.

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 and resource: looking up Wikidata ids for a name, and adds that the result carries a 7-day mention count. That is more than a restatement of the name, though it distinguishes itself from siblings mainly by naming them as downstream consumers rather than by contrasting its own scope.

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 tells the agent what to do with the result: pass the returned id as the `entity` argument to search_news or list_stories. That establishes the context of use clearly, but there is no negative guidance (e.g. what to do when no match or multiple matches are returned).

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds behavior beyond that: each result carries add_url (a prefilled CRM add form) and propose (arguments for propose_relationship that an owner must approve), plus the ordering rule 'most often named first' for q results. It omits cost/latency expectations for an open-world search, keeping it short of a 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?

Three dense sentences with no pure filler, but the opening is a fragment and the nested parentheticals ('CRM by Hottub's add form, filled in; the person presses Add') make the key input-mode instruction harder to scan than it needs to be.

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 7-parameter, zero-required, no-output-schema tool, the description covers what the results contain (add_url, propose) and how to drive each mode. It leaves limit and format (md/json) unexplained, but those are self-evident from the schema and do not block 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?

With 71% schema coverage the schema already documents q, item, kind and since. The description still adds value by spelling out the id prefix conventions (n_…/s_… for item, st_… for story) and by tying kind and since to q mode, which the schema states only tersely.

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 plainly states the resource: 'The companies and people in an article or a story, ready to add to CRM', and the q-mode variant ('gather the organizations and people named across recent news on a subject'). It is a noun phrase rather than a verb+resource, and it never names the sibling find_entities, so it is clear but not sibling-differentiated.

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 does route the caller among input modes ('Give item ... or story ...; or q to gather ...'), which is genuine when-to-use guidance at the parameter level. But there is no statement of when to prefer this over find_entities, search_news, or get_story, and no exclusions or preconditions.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description's only added behavioral value is the id-prefix convention and the word 'full', which hints the record is more complete than a search hit but says nothing about field content or error behavior on unknown ids.

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 action and resource, with the id-format parenthetical placed where it is most needed. 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?

For a single-parameter read tool this covers the input adequately, but with no output schema there is nothing anywhere describing what a 'full record' contains (fields, sizing, null behavior), which leaves a real 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 0%, so the description must carry the parameter. It usefully explains the id format and the two prefix families (n_ for news, s_ for sponsored), which meaningfully constrains what value to pass; it stops short of stating whether the prefix must match the requested record type.

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 clear verb+resource: retrieve the full record for a single item id, and even disambiguates the id namespace (n_… = news, s_… = sponsored). It does not differentiate itself from the sibling get_story or from search_news, so an agent cannot tell from the text alone which retrieval tool applies to a given id.

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: fetch this when you already have an id. There is no statement of when to prefer it over search_news, find_entities, or the confusingly similar get_story, and no prerequisites or exclusions are given.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavior: results are the full cross-outlet/cross-language set for one event and are ordered newest first, plus the 'st_…' identifier convention. It omits any pagination or size 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?

A single compact sentence with the key concept front-loaded and the ID parenthetical placed where it helps most. No filler, though the parenthetical slightly interrupts the main clause.

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 exists, so the description must convey the return shape, and it does: items from all outlets/languages for one event, newest first. Missing only edge-case detail such as empty results, limits, or whether a story can span unrelated events.

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 carry parameter meaning. It explains that `story` is the story id found on items with the 'st_…' prefix, which is genuinely useful, but says nothing about `format` beyond the enum already in the schema. Partial compensation for a two-parameter 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 resource and scope: every item in a story, all outlets and languages covering the same event. An agent can distinguish it from list_stories and get_news_item by its grouping semantics. It does not, however, name or contrast with 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?

There is no when-to-use guidance, no prerequisites, and no named alternative (e.g. list_stories vs. search_news). Usage is only implied by the 'get a group' semantics and the ID-prefix hint.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful return-field context (language, country, kind, health) but says nothing about pagination, result caps, or how health is computed. With annotations carrying the behavioral burden, this is a reasonable if modest contribution.

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 filler, with the resource and its returned fields front-loaded ahead of the filtering clause. 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 a simple, no-required-parameter list tool with no output schema, the description covers what is returned and how to filter, which is most of what an agent needs. The remaining gap is parameter format specifics (lang/country code conventions), which is minor at this complexity level.

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 is the only source of parameter meaning. It correctly identifies all three parameters and clarifies that q matches by name, but gives no format guidance for lang or country (ISO codes? free text?). It partially compensates for the coverage gap without fully closing it.

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 resource (registered sources) and enumerates the attributes returned (language, country, kind, health), so it is clearly distinguishable from list_stories and the other news-oriented siblings. It is not a tautology of the title. It stops short of an explicit verb+scope statement like 'lists all sources without pagination', but the intent is unmistakable.

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?

'Filter by q (name), country or lang' implies how to narrow results, which is implicit usage guidance. There is no statement of when to reach for this tool versus find_entities or search_news, and no exclusions or prerequisites. Adequate but leaves routing 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, idempotentHint, openWorldHint, and destructiveHint=false, so safety behavior is covered. The description adds valuable behavioral context beyond annotations: the 48-hour time window, the conditional availability of briefs ('when available'), and the exact composition of returned items.

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 tight sentences with no filler. It front-loads the core purpose and follows with the filterable fields, making every clause earn 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 six parameters, zero schema descriptions, and no output schema, the description provides a useful summary of return content and time scope but leaves key parameter semantics (limit, format, value formats) unexplained. It is adequate for a high-level understanding but incomplete for precise 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 0%, so the description must compensate for all six parameters. It names four filters (lang, country, category, entity) but omits limit and format entirely, and provides no format or value guidance for any parameter, leaving much of the input semantics 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 description names a specific resource (stories) and scope (most widely covered right now, last 48h), and enumerates what each item includes: neutral brief, outlet count, languages, entities, representative report. This distinguishes it from sibling tools like get_story and search_news, which serve different retrieval patterns.

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 the content scope and the filter list, but the description never states when to choose this tool over alternatives such as search_news or get_story. It gives no explicit when-not guidance or prerequisites.

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 this a read-only, idempotent, open-world, non-destructive call, so the safety profile needs no restating. The description adds genuinely new behavior: a fixed 24-hour window, the possibility of 'too quiet to call' countries, and a labeled paid placement that may appear in a country's list — all useful for interpreting results. It does not cover rate limits or authentication, keeping it short of 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?

The core scope is front-loaded, but the description is a single dense run-on sentence that mixes scope, sort semantics, and ad disclosure into one breath, making it harder to parse than necessary. The 'like an election map' simile is evocative but consumes space without adding operational meaning.

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 does the work of explaining the return shape — per-country leading story, cross-country leaders, uncallable countries, and labeled placements. That is enough to call and interpret the tool; the only omission is what `format` controls.

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 33%, with just `country` documented, so the description must carry the rest — and it does explain the three `sort` modes concretely (popular = its own outlets, cited = stories that broke there ranked by pickup elsewhere, relevant = disproportionately covered there). Only `format` (md vs json) is left unexplained, which is the sole 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?

The description names a concrete resource and scope: the last 24 hours of news, country by country, with each country's leading story, globally leading stories, and silent countries. That is far more specific than the title alone. It stops short of 5 because it never distinguishes itself from the similarly named sibling `newsmap`, leaving the agent to guess which map tool to call.

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 rather than stated: pass `country` for one country's stories, omit it (per the schema) for the whole map. Nothing says when to prefer this over `newsmap`, `list_stories`, or `get_story`, and no exclusions or prerequisites are given.

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 cover readOnly, idempotent, non-destructive and open-world, so the bar is lower. The description still adds real behavioral context: the output is delivered as downloadable SVG/PNG map links plus ranked stories, and that past periods are final and permanent (implying current-period data may still be settling).

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, front-loaded with the output description and followed by the period grammar. Dense but every clause carries information; the long inline period list is the only mildly heavy element, and it is genuinely needed to invoke the tool.

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 does the work of explaining return values (map links and story counts), and it documents period and scope. The only gap is the format parameter's effect, which is minor since its enum values are self-explanatory. Adequate for a zero-required-parameter read 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 only 33%, so the description carries more weight. It enumerates the accepted period formats (though this largely repeats the schema's own period description) and clarifies the world-vs-region scope, but says nothing about the format parameter (md vs json) or what each region value yields.

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 resource (news coverage in a period) and spells out the two concrete outputs: publisher-country report counts rendered as SVG/PNG choropleth links, and the most widely covered stories with outlet counts. That is far more informative than the title. It does not explicitly contrast itself with siblings like news_stats or list_stories, so differentiation is implicit 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?

Usage is implied by the period/region framing – reach for this when you want a geographic/topical overview of a time window – but there is no explicit 'use this instead of X' routing against news_stats, list_stories, or search_news. The accepted period keywords are a format reference, not selection 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?

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the 24-hour measurement window and the inclusion of the current sync cursor.

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; every clause (window, dimensions, cursor) carries information an agent would otherwise lack.

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 and no parameters, the description must carry the return-value burden, and it does so adequately by naming the grouped counts and the sync cursor. It stops short of describing the shape of the counts (per-value vs total) or cursor format, but nothing essential to invoking the tool is missing.

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?

There are no input parameters, so the baseline is 4. The description's mention of kind/language/country/source refers to groupings in the output rather than inputs, which adds context without misrepresenting 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?

Names the concrete resource (item counts) and the exact dimensions aggregated over a defined window, so an agent can distinguish this stats tool from search_news, list_stories, or list_sources. The verb is implicit ('counts' rather than an explicit 'get/return'), 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?

Usage is implied by the narrow purpose (a zero-argument overview of coverage), but the description never states when to reach for this versus the sibling listing/search tools, nor any exclusions. Minimum viable guidance only.

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 readOnly/idempotent/non-destructive, and the description reinforces that with an explicit 'books and charges nothing' statement. It goes beyond the annotations by disclosing the itemization of price factors and the side effect that country targeting also places the item in that country's news-map list as one paid slot after the fourth story — real behavioral context. Auth requirements and any rate limits are still unstated.

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 dense sentences, front-loaded with the core action and closing with the read-only guarantee. Nearly every clause carries information, though the middle pricing-factor list is packed tightly enough to read as a run-on.

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 usefully says the response itemizes each factor, and it covers the mutation-free nature of the call. It leaves 'lang' undefined and does not state price currency or the units of the returned quote, which an agent pricing a placement would want.

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 only 25% schema coverage, the description compensates well: it maps 'topics' to topic tier, 'days' to duration, and 'country' to both targeting reach and the news-map placement behavior. Only 'lang' is left without any explanation in either the schema or the 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?

States a specific verb (quote/price) and resource (a labeled, paid press-release placement in News by Hottub), and no sibling tool does anything comparable. It also names the determining factors and the response shape, so an agent knows exactly what it gets back 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 'Quote ... Read-only: returns a price; books and charges nothing' framing makes clear this is the pre-purchase step and that calling it commits nothing, which resolves the key ambiguity an agent would have. It stops short of naming a companion booking tool or stating when not to call 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered structurally. The description adds the default 'newest-first' ordering and worldwide source scope, but says nothing about result-set size behavior, pagination, or rate limits — modest value beyond 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?

A single front-loaded sentence that leads with ordering and resource, then enumerates filters. No filler, no restatement of the title, and nothing that could be cut.

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 21-parameter, open-world search tool with no output schema, the description plus rich schema covers the mechanics, and annotations cover safety. What is missing is any statement of result-shaping behavior (return format selection is only in the schema) or guidance on chaining with find_entities/list_sources, so the definition is workable but thin for the tool's complexity.

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 90%, so nearly every parameter is already documented in the schema (including the important semantic/keyword matching notes and format trade-offs). The description only re-lists the filter names and adds no syntax or interaction detail beyond what the schema provides, making the baseline 3 correct.

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?

Names a clear resource (news/headlines) and enumerates the filterable dimensions (words, language, country, topic, source, kind, time), so the agent knows this is the broad search/retrieval entry point. It does not name or contrast itself against siblings like list_stories or get_news_item, so it stops short of full 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?

Implied usage only: the word 'optionally filtered' tells the agent filters are add-ons to a general query, but there is no explicit when-to-use-this-instead-of guidance versus list_stories, get_story, or find_entities, and no note about paging via 'before'/next links. Adequate but leaves routing 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds genuine behavior the annotations cannot: result ordering (oldest first) and the cursor-chaining contract. It omits whether cursors expire or how the 500-item cap interacts with polling.

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 padding, and the core contract (incremental, ordered, returns cursor, reuse cursor) is front-loaded. Nothing could be cut without losing meaning.

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 16 params, no output schema, and a rich schema, the description covers the essential sync loop and gives a workable return summary (items plus cursor). It does not explain how the many filters compose or how `limit` interacts with the cursor, but that is largely carried by the schema.

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 88%, so the schema already documents nearly all 16 parameters, including the cursor meaning of `after`. The description reinforces the cursor semantics but adds no syntax or combining rules for the many filter parameters. 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?

States a specific mechanism: an incremental feed returning items added after `after`, oldest first, plus a new cursor. 'Incremental feed' clearly separates it from search_news and list_stories, 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?

'Call again with that cursor to get only what is new' communicates the intended polling loop, which is real usage guidance. However, it never says when NOT to use it (e.g., historical/filtered lookup belongs to search_news) or how it relates to the seven sibling tools.

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