Worldwide news for agents: search, sync and story clusters across outlets and languages. No key.
Scored across 9 tools
Most tools have clearly distinct roles: find_entities, list_sources, news_stats, and quote_placement are unambiguous. However, search_news, sync_news, get_story, and list_stories have overlapping surface area (all return news items/stories), which could cause occasional misselection despite the descriptions clarifying search vs. incremental sync and single-story vs. story-list.
Seven of nine tools follow a clean verb_noun pattern (find_entities, get_news_item, get_story, list_sources, list_stories, search_news, sync_news). The two exceptions, news_stats and quote_placement, are noun phrases rather than verb_noun, a minor deviation but still readable and predictable.
Nine tools is well-scoped for a news aggregation service, with each tool covering a distinct capability (entity lookup, search, item detail, story detail, source listing, stats, sync, quoting). No redundancy or padding.
The surface covers the core news lifecycle well: discovery (search_news, list_stories), retrieval (get_news_item, get_story), sources (list_sources), monitoring (news_stats, sync_news), and entity/metric lookup. Minor gaps include no direct category/topic enumeration tool and no way to fetch a single source by id, but agents can work around these via filters.
Look up Wikidata ids for a name (e.g. "Tesla", "Lagos") with how many items mention each in the last 7 days; pass the id as entity to search_news or list_stories.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes |
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.
Full record for one item id (n_… for news, s_… for sponsored).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
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.
Every item in a story (the story id on items, st_…): all outlets and languages covering the same event, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| story | Yes | ||
| format | No | md |
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.
Registered sources with their language, country, kind and health. Filter by q (name), country or lang.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| lang | No | ||
| country | No |
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.
The most widely covered stories right now (last 48h), each with a neutral multi-source brief when available, outlet count, languages, entities and a representative report. Filter by lang, country, category, entity.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | ||
| limit | No | ||
| entity | No | ||
| format | No | md | |
| country | No | ||
| category | No |
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.
Item counts over the last 24 hours by kind, language, country and source, plus the current sync cursor.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Quote for placing a labeled, paid press release in the Hottub News mix via Hottub Business. Price varies by topic tier, current topic interest, demand, targeting reach and duration; the response itemizes each factor. Read-only: returns a price; books and charges nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| lang | No | ||
| topics | No | Comma-separated topics to target, e.g. "ai,business"; omit for run of network | |
| country | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value by disambiguating 'placement' (which sounds like a write) as quote-only and by noting the response itemizes price factors — a helpful disclosure about output shape given there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and immediately followed by pricing behavior and the read-only guarantee. 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?
With no output schema, the description reasonably notes the response itemizes factors, and it clarifies the non-booking semantics. However, for a 4-parameter tool where three parameters are undocumented, an agent still lacks enough guidance on inputs (especially lang and country) to call it confidently.
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 25%: 'topics' is documented in the schema, but 'days' (range 1-31), 'lang', and 'country' have no descriptions. The description vaguely alludes to factors like duration and targeting reach but never maps them to these parameters or explains expected formats, so it 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 (quote/price) and resource (placing a labeled, paid press release in the Hottub News mix), which no sibling tool covers — all siblings are plain news-reading tools. An agent can distinguish this pricing tool from search_news or get_story without opening schemas.
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 makes clear this is a non-binding price quote ('books and charges nothing'), which implicitly bounds when to call it, but it never states when to use this versus other tools or any prerequisites. With no true alternative sibling, usage is only implied rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Newest-first headlines from worldwide sources, optionally filtered by words, language, country, topic, source, kind and time.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | What you're looking for, in any language. Matches by meaning and by keyword (hybrid) over the last 7 days unless since is given; results carry a relevance score. | |
| kind | No | Comma-separated: article, press_release, official, community, research, sponsored | |
| lang | No | Comma-separated ISO 639-1 codes, e.g. "en,es" | |
| sort | No | hot: most widely covered stories of the last 48h, one per story; positive/negative: most positive/negative tone first (last 24h unless since is given) | newest |
| limit | No | ||
| match | No | keyword: exact words only; semantic: meaning only (cross-language) | hybrid |
| since | No | Only items published at/after this: RFC 3339, a date, or an age like "6h", "2d" | |
| topic | No | Comma-separated topics, e.g. "space,science" | |
| until | No | Only items published at/before this | |
| before | No | Paging cursor from a previous result's next link | |
| entity | No | Comma-separated Wikidata ids (from find_entities), e.g. "Q312" | |
| format | No | md: readable with summaries; lines: tab-separated, fewest tokens; ndjson/json: full records | md |
| source | No | Comma-separated source ids (see list_sources) or publisher domains | |
| country | No | Comma-separated ISO 3166-1 alpha-2 codes of the publisher's country, e.g. "US,GB" | |
| category | No | Comma-separated IPTC top-level categories: arts-culture-entertainment, conflict-war, crime-law, disaster-accident, economy-business, education, environment, health, human-interest, labour, lifestyle-leisure, politics, religion, science-technology, society, sport, weather | |
| collapse | No | One item per story (best representative); related = other reports of it | |
| tone_max | No | ||
| tone_min | No | Only items with tone ≥ this (-1 most negative … 1 most positive) | |
| political | No | true: political stories only (political score ≥ 0.5); false: non-political only | |
| sentiment | No | Comma-separated: negative, neutral, positive | |
| sponsored | No | Paid press releases are labeled; exclude to omit them | include |
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.
Incremental feed: returns items added after after, oldest first, plus a new cursor. Call again with that cursor to get only what is new.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Comma-separated: article, press_release, official, community, research, sponsored | |
| lang | No | Comma-separated ISO 639-1 codes, e.g. "en,es" | |
| after | Yes | The cursor returned by your previous sync_news call; 0 to start from the oldest retained item | |
| limit | No | ||
| since | No | Only items published at/after this: RFC 3339, a date, or an age like "6h", "2d" | |
| topic | No | Comma-separated topics, e.g. "space,science" | |
| until | No | Only items published at/before this | |
| format | No | md: readable with summaries; lines: tab-separated, fewest tokens; ndjson/json: full records | md |
| source | No | Comma-separated source ids (see list_sources) or publisher domains | |
| country | No | Comma-separated ISO 3166-1 alpha-2 codes of the publisher's country, e.g. "US,GB" | |
| category | No | Comma-separated IPTC top-level categories: arts-culture-entertainment, conflict-war, crime-law, disaster-accident, economy-business, education, environment, health, human-interest, labour, lifestyle-leisure, politics, religion, science-technology, society, sport, weather | |
| tone_max | No | ||
| tone_min | No | Only items with tone ≥ this (-1 most negative … 1 most positive) | |
| political | No | true: political stories only (political score ≥ 0.5); false: non-political only | |
| sentiment | No | Comma-separated: negative, neutral, positive | |
| sponsored | No | Paid press releases are labeled; exclude to omit them | include |
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
find_entitiesget_news_itemget_storylist_sourceslist_storiesnews_statsquote_placementsearch_newssync_newsNews search for AI agents: recent news on any topic from outlets worldwide, by country and language.
News for agents: 100k+ articles/day deduplicated into situations with timelines. Free, no key.
Live global news signals: ranked wire, story timelines, coverage volume/tone/surges. Free, no auth.
Free cross-lingual news briefings for AI agents across 89 languages. Read-only, hosted.
Add one secure layer between your agents and this server.
