Pollar News

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the returned field set and notes that the payload carries the article summary and source citations, which is useful behavioral context beyond the 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?

Two sentences, front-loaded with the action and scope, with no filler. The second sentence restates return fields that an output schema already covers, so it is slightly redundant rather than 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?

Given an output schema exists and annotations cover the safety profile, the description needs only to state purpose and input provenance, both of which it does. Minor gaps remain (behavior on an invalid/unknown id, any text-length or paywall limits), but nothing essential for correct invocation 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?

With a single parameter at 100% schema coverage, the schema already documents the id; the description adds provenance by specifying the id must come from the search tool, which constrains how the value is obtained. This is meaningful added meaning over the bare schema 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 (fetches) and resource (full text of one Pollar article) and scopes it to a single item by id, which separates it from the list_*/search siblings that return collections or ids. It also anchors the resource as an 'article', distinguishing it from the get_explainer/get_film/get_event siblings that target other content types.

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 usage context by tying the input to the search workflow ('the id returned from the search tool'), implying fetch is the follow-up step after search. It stops short of explicitly naming alternatives or stating when not to use it (e.g., for bulk retrieval), so it is clear context without exclusions.

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 (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the bar is lower. The description still adds real context beyond them: the brief is 'fixed' and 'curated' rather than queryable or personalized, and locale affects language only, not editorial scope. It stops short of describing freshness/update cadence or caching.

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 sentences, front-loaded with what the tool returns, then the routing rule, then the one parameter caveat. No filler and nothing repeated from the annotations.

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 structure need not be documented, yet the description still summarizes the payload sections. With a single optional param explained and the sibling boundary drawn, an agent has everything needed to call this correctly.

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?

One optional parameter with 0% schema description coverage, so the description must carry the meaning — and it does, clarifying that locale changes the brief's language but not its editorial scope, which is exactly the ambiguity an agent would have. The enum values themselves (en/pl/de/fr) come from 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?

States a specific verb (fetches) plus a precisely scoped resource (today's fixed, curated Pollar daily brief) and even enumerates its contents — greeting, headline, executive summary, themed sections, related events, charts. It is immediately distinguishable from siblings like get_explainer or list_top_news.

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 an explicit use condition ('only for explicit requests for Pollar's daily brief or curated digest') and an explicit exclusion with the correct alternative named ('questions about a subject, person, place, or country belong to search_news'). This is the routing information an agent needs.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context by disclosing that withTimeline expands the response to include recent mentioning events, and that a canonical Pollar URL is returned.

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 zero filler. The primary purpose and the location of the required slug are front-loaded, with the optional withTimeline behavior trailing.

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-value detail is not required, and the tool is a simple flat-keyed read. The remaining gap is the undocumented locale parameter, which affects which language variant of the profile is fetched.

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 burden. It explains slug provenance and the withTimeline flag's effect, but leaves the required 'type' enum (person/organization) and the locale default of 'en' entirely unaddressed.

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 specific verb and resource ('Fetches Pollar's profile for a person or organisation') and scopes it by slug. This clearly distinguishes it from siblings like get_event, get_explainer, and get_thread, which target different content types.

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 states where the slug argument comes from ('slugs come from list_trending_entities'), giving the agent a concrete routing dependency to another tool. It stops short of stating when not to use it or naming a real alternative for entity lookup.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully enumerates the payload (title, lead, summary, citations, people, locations, charts, language variants, canonical URL), but much of that duplicates the output schema rather than adding new behavioral context such as caching, rate limits, or errors on bad slugs.

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 action and slug source, then the payload, then related-tool routing. The long return-value enumeration is slightly list-heavy but every clause maps to a real field group.

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 an output schema and safety annotations already present, the description supplies exactly what those lack: how to obtain the required slug, what the payload conceptually contains, and which sibling handles explainer/film variants. Only the undefined locale parameter remains unaddressed.

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%: slug is documented, but locale (enum, default 'en') carries no description in either schema or description. The description adds the useful hint that slugs are per-locale only indirectly, and never explains the locale parameter's effect. Marginal value over 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?

States a specific verb and resource ('Fetches the full Pollar coverage of a single event by its slug') and immediately distinguishes itself from list/search siblings by naming where slugs come from. An agent can tell what this returns 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?

Explicitly routes the agent: slugs come from search_news or list_top_news, and it names the conditional alternatives get_explainer and get_film when the event carries those forms. No explicit 'when not to use', but the context is clear and actionable.

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 disclose the safety profile (readOnlyHint=true, destructiveHint=false), so the description is freed to describe output shape: the question, beat-by-beat narration, and per-beat visual types (map, timeline, key figure, bar chart, quote). It also notes the return of a canonical pollar.news URL and the semantics of the 'next' timeline marker. No auth or rate-limit details, but output behavior is well covered.

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 action and identifier, then enumerates return content efficiently in one long sentence. Slightly dense—the visual-type list could be trimmed—but no sentence is pure waste and the important routing info comes early.

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?

Despite an output schema being present (so return values needn't be re-explained), the description still usefully summarizes the payload structure and the meaning of the 'next' timeline marker. With annotations covering safety and the schema covering types, the only unpaid bill is the absent locale semantics beyond the enum, which is minor.

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 50%—the slug parameter is documented as 'Event slug (per-locale)' and locale is an enum with a default—but the description adds the critical detail that the slug is event-scoped and comes from specific sibling tools. That provenance and per-locale implication go beyond the terse schema, lifting it above the baseline 3.

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 (Fetches) and resource (the explainer for one news event) keyed by a uniquely-identifying parameter (event slug). It distinguishes itself from siblings by noting the slug comes from list_explainers or get_event, and by defining explainer content (question, narration beats, visual data) that separates it from get_event or 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?

Gives clear context—'Suited to questions about why a story matters'—and names upstream tools that supply the required slug (list_explainers, get_event). It does not explicitly state when NOT to use it (e.g., to use get_event for raw event data), so it stops short of full routing 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 readOnlyHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the transcript comes from 'reviewed captions' (a data-quality caveat) and the response includes a canonical pollar.news url.

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 dense sentence that front-loads the action, the key, and the payload, then appends the return detail. No filler, though the run-on structure packs several separate facts together.

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 an output schema present, the description needn't explain return structure, yet it still flags the url. It covers slug sourcing and language selection adequately; only the locale enumeration is a residual gap for a 2-parameter 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 carry the load. It explains the meaning and origin of slug well, and 'in the requested language' implies the locale parameter, but it never enumerates the supported locales (en/pl/de/fr) or mentions the default of 'en' that the schema declares.

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 (fetches) and resource (one Pollar film) and enumerates what is returned: full transcript in the requested language plus a canonical pollar.news url. This clearly distinguishes it from the list_films sibling and from generic 'fetch' tools.

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 where the required slug comes from — list_films, or the film field of get_event — which is the key routing information for a single-item lookup. It stops short of naming when NOT to use it, but the sourcing guidance is concrete.

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?

The annotations already establish read-only, non-destructive, closed-world behavior, so the bar is lower, and the description adds genuinely useful context: it is a point-in-time snapshot rather than a stream, story ids are transparently resolved to the latest chapter, and the response bundles ordered updates plus a source summary. It does not describe auth, rate limits, or freshness/staleness guarantees for a breaking-news 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?

Three tight sentences front-loaded with the core action, then parameter behavior, then the read-vs-stream caveat. No filler or repetition.

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-value detail is not required, and the description still usefully characterizes the payload. Combined with the safety annotations and clear id semantics, the definition is nearly complete; only freshness/pagination behavior for a live-news snapshot is unaddressed.

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 load for the id parameter, and it does: the id may be either a moment id or a story id, with defined resolution behavior. The locale enum is left unexplained, but its values (en/pl/de/fr) and default are self-evident.

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 (fetches) and resource (breaking-news moment snapshot) plus what the payload contains (ordered updates, source summary). It partially differentiates from the get_live_story sibling by explaining that a story id resolves to the latest chapter, but it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The line 'The result is a point-in-time read, not a stream' gives an implicit when/when-not signal, steering agents away from polling/streaming expectations. However, no alternative tool is named and no conditions for choosing get_live_story vs get_live_moment are stated.

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

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

Annotations already declare readOnlyHint, destructiveHint false and openWorld false, so the description adds value by disclosing the returned content (title, ordered chapters) and enumerating the status lifecycle values. It does not mention permissions, pagination or freshness/refresh behavior, which is a minor gap given the tool returns a 'snapshot'.

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 tightly packed sentences with no filler; the core behavior and the sibling routing are front-loaded, and every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't explain return values, yet it usefully summarizes them anyway. Annotations cover the safety profile. The only real omission is any meaning for the undocumented 'locale' parameter.

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 there are two parameters. The description only implies the required 'id' parameter and says nothing about the 'locale' enum (en/pl/de/fr) or its default. It fails to compensate for the schema's complete lack of parameter documentation.

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 ('fetches the current snapshot of a story by id') and immediately distinguishes scope from the sibling get_live_moment by contrast (whole arc vs. single chapter). An agent can differentiate it from the surrounding live_* tools without opening any 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?

Explicitly routes the agent: use get_live_story for the whole multi-chapter arc, get_live_moment for a single chapter. Clear context, but no negative guidance about when not to use it (e.g., for concluded archival stories or listing).

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context by disclosing that the response shape changes with the arguments (catalogue vs. detail vs. history), which the annotations do not convey.

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 no filler, and the coverage scope is front-loaded before the argument-dependent behaviors. Every clause carries information the agent needs.

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 spelled out, and the mode logic is well covered. The only gaps are edge cases such as combining symbol and range or passing an invalid symbol, which are left unaddressed.

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 50%: 'symbol' is documented in the schema but 'range' has an enum with no description. The description compensates by explaining that 'range' produces price history and that 'symbol' must be an exact catalogue symbol, adding meaning beyond the raw enum list.

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 (market data tracked by Pollar) and enumerates the asset classes covered (indices, currencies, crypto, commodities, bonds). It also distinguishes its three response modes, which lets an agent tell it apart from the news-oriented siblings at a glance.

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 explicit invocation guidance: no arguments yields the quote catalogue, an exact catalogue symbol yields that quote's detail, and a range yields price history. This is clear mode-selection context, though it stops short of naming when-not-to-use conditions or 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 cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds genuinely non-obvious behavior: members-only episodes return without a transcript, and the response includes a canonical pollar.news URL. It doesn't say what happens for an invalid slug or unknown locale.

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 verb and the slug source. The list of returned fields is dense but earns its place. 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?

Output schema exists so return-value structure needn't be restated. The description still conveys the key conditional (members-only strips transcript) and provenance of the slug. For a 3-param read tool this is close to complete, minor gaps on error behavior and withTranscript semantics.

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 parameters are documented only by name/type/enum. The description says the transcript is 'in the requested language', implicitly tying locale to transcript language, but doesn't explain what withTranscript=false does versus the members-only case. Baseline for low coverage would be lower, but the description partially compensates.

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 (Fetches) and resource (one Pollar Sounds episode), and crucially disambiguates from likely sibling list_sounds by noting the slug comes 'from list_sounds'. Distinguishes itself clearly from get_entity, get_explainer and other get_* siblings.

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 parenthetical '(from list_sounds)' tells the agent where the slug originates, which is real routing guidance. No explicit when-not-to-use or alternative named for transcript-free fetches, but the context is clear.

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?

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?

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?

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?

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 (Fetches), resource (a single Pollar thread), and identifier (slug), plus what the payload contains (thesis, state-of-play, chronicle entries with citations). It also names the sibling list_threads as the source of the slug, so it is distinguishable from get_entity/get_event/list_threads.

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?

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the result carries mention counts, which is genuine behavioral context, but it omits anything about size, caching, or stability of the taxonomy.

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 clauses, front-loaded with the return value and purpose; no filler, and the no-argument statement is the right place at the end.

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 an output schema present, an empty input schema, and full annotation coverage, the description supplies everything an agent needs: what it returns, why (filtering list_top_news), and that it takes no input.

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?

Zero parameters, so the baseline is 4; the explicit 'Takes no arguments' correctly matches the empty schema and removes any doubt about required inputs.

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 ('Returns Pollar's category taxonomy with mention counts') and immediately qualifies the resource as the valid dot-paths for filtering list_top_news, which distinguishes it from the many sibling list_* tools.

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 clearly ties usage to list_top_news filtering, telling the agent when this taxonomy is needed, but it names no alternative and states no exclusions (e.g., that it should be called once and cached rather than per-query).

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavioral value beyond that by disclosing the sort order ('newest first'), which the annotations and schema do not convey, though pagination or locale-influence behavior is not addressed.

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 front-loaded sentences; the first two carry the essential purpose and ordering, the third the chaining hint. The explainer definition sentence is longer but earns its place by clarifying the resource, leaving little waste.

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-structure explanation is unnecessary, and the chaining to get_explainer is covered. However, with 0% schema coverage on limit and locale and no mention of them, the definition is incomplete for a listing tool whose filtering behavior an agent needs to know.

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% for two parameters (limit, locale), and the description never mentions either. It gives no meaning for limit bounds/default or for what the locale enum changes about the returned explainers, so the description fails to compensate for the schema 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 ('Lists Pollar's latest explainers') plus the ordering ('newest first'), and then defines what an explainer is so an agent understands the resource type. It also routes to the sibling 'get_explainer' via the returned eventSlug, cleanly separating list from fetch.

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?

Provides clear context for the list-then-fetch workflow by naming get_explainer and the eventSlug handoff. It does not state when to prefer this over other discovery siblings such as search_news or list_top_news, so exclusions are implicit rather than explicit.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: the ordering guarantee (newest first) and the linkage behavior (each film links its event when attached), which the agent cannot get from 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?

Three tight sentences with zero filler; the ordering and resource definition are front-loaded, and the get_film hand-off comes last where it belongs.

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-shape explanation is unnecessary, and the description covers resource nature, ordering, and entity linkage. The only meaningful gap is the total silence on the limit and locale parameters for a tool that serves four locales.

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 neither of the two parameters (limit, locale) is mentioned anywhere in the description. The locale parameter in particular has no explanation despite the tool clearly serving multi-locale content, so the description does not 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 ('Lists Pollar films'), defines what the resource is ('short videos in which a Pollar journalist answers one question about a news story'), and specifies the ordering ('newest first'). It also distinguishes itself from the sibling get_film by naming it 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?

Gives clear context for use — browse the film collection, then call get_film with a returned slug for the transcript — which routes the agent to the right follow-up sibling. It does not state when-not-to-use it or contrast it with list_explainers/list_sounds, so it stops short of full 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: the 24-hour lifecycle window, that story moments carry storyId and chapterIndex, and that chapters arrive in chapter order. It omits result limits/pagination, which keeps it from 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 tight sentences, front-loaded with the resource and its time window before the structural details. Every sentence carries information an agent can act on, with 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?

An output schema exists, so return values need not be explained, and the description still usefully flags the storyId/chapterIndex shape and chapter ordering. The one gap is the locale parameter's effect, left entirely to the schema for a listing tool that defaults silently to English.

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 the sole parameter (locale, enum en/pl/de/fr, default en) is never mentioned in the description. The enum values are somewhat self-explanatory, but what locale actually governs — content language, fallback behavior — is undocumented in both places.

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 (Lists) and resource (Pollar's breaking-news moments) and pins the scope precisely: what is live now plus what ended within the past 24 hours. This distinguishes it from list_live_stories (stories, not moments) and get_live_moment (single item) without opening any 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 24-hour window and mention that get_live_moment takes a returned id imply a list-then-detail flow, which is useful context. But there is no explicit statement of when to choose this over list_live_stories, list_top_news, or search_news, 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the composite return shape (an umbrella story containing ordered chapters) and by describing a cross-tool workflow: get_live_moment accepts a story id from this result. It omits pagination/volume or freshness characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: what it returns and its structure first, then the scenario it suits, then the follow-up tool. Every sentence carries new information and nothing is padded.

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 not be restated, and annotations cover safety; the description supplies the story/chapter model and the chaining guidance an agent needs. The only remaining gap is the unmentioned locale parameter, which is minor relative to the rest.

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 single locale parameter's meaning rests entirely on the enum (en/pl/de/fr) and default. The description never mentions language selection at all, so it does not compensate; an agent gets no signal from the text that results are locale-filtered. The enum is self-explanatory enough to keep this at a baseline 3 rather than lower.

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 (lists Pollar's active/developing breaking-news stories) and adds structural detail: each story has an umbrella title plus ordered chapters. It implicitly separates itself from moment-level tools by contrasting with 'single moments', but never distinguishes itself from the close sibling get_live_story (singular story retrieval).

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 concrete use case ('showing how a story has unfolded... a strike with three chapters over 48 hours') and contrasts it with single moments, which steers the agent toward the right granularity. It stops short of naming the explicit alternative tool for single moments (list_live_moments) or when not to use it at all.

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 safe read-only profile (readOnlyHint, destructiveHint=false, openWorldHint=false). The description adds value beyond that: result ordering (newest first) and the membership-gated 'early' access tier with publicAt, which an agent cannot infer from the 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?

Two sentences, front-loaded with the core listing behavior, followed by the access-tier caveat and the sibling cross-reference. No filler; tight and purposeful.

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 an output schema present, return values needn't be described. The description covers ordering, the access-gating nuance, and the follow-up detail tool. Only the locale parameter is left unexplained.

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 single locale parameter has 0% schema description coverage and the description never mentions it. The enum values (en, pl, de, fr) are largely self-explanatory, but the description does nothing to clarify locale behavior, so it only meets the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists episodes of Pollar Sounds'), names the series genre ('narrative audio series'), and specifies ordering ('newest first'). The mention of get_sound_episode distinguishes it from the sibling detail 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?

Explicitly routes the agent: use get_sound_episode with a returned slug for transcripts and sources. It also surfaces the 'early' access rule governing when episodes are publicly available. No explicit when-not condition, but the workflow context is clear.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaning beyond that: only *active* threads are returned, they are grouped by section, and each carries a 'latest change magnitude' — useful output-shape context. It omits auth, rate limits, and pagination behavior, keeping it out of the 5 band.

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 waste: the first defines what is listed and its shape, the second routes to the sibling. The primary purpose is front-loaded before the alternative is mentioned.

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 the description needn't explain return values, and annotations cover safety. Purpose, sibling routing, and return characteristics are all present; only the locale parameter's effect on output language and any pagination/count limits are unaddressed.

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 would need to compensate for the single locale parameter — and it says nothing about locale. However, the parameter is a self-evident language enum with a default, so ambiguity is low and the schema still conveys the constraint. Baseline 3 reflects an undocumented but low-risk parameter.

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 (Lists) and resource (Pollar's active evergreen threads), and defines the concept as 'ongoing storylines tracked over time and grouped by section, with the latest change magnitude.' It also distinguishes itself from the sibling get_thread, so an agent can tell the two apart without opening either 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?

'Suited to discovering long-running topics; get_thread takes a returned id for the detail' gives clear context for when to use this tool and names the alternative for detail retrieval. It stops short of explicit when-not conditions (e.g., inactive or historical threads), but the routing is unambiguous.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: results are ranked by freshness and editorial momentum, and category values must be drawn from list_categories. It does not cover pagination or the shape of the ranking, but the output schema carries return values.

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 zero filler: scope/ranking first, then the routing rule to the sibling tool, then the category constraint. Every clause carries information an agent needs.

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 an output schema present, the description needn't explain return values, and it covers the key routing decision plus the category sourcing constraint. The only gap is that 'limit' and 'locale' are never addressed, though their schema defaults, bounds and enum make them largely self-explanatory.

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% (only 'category' is documented), so the description must compensate. It does clarify the category parameter by explaining the dot-path format and that valid paths come from list_categories, but it says nothing about 'limit' or 'locale', leaving two of three parameters reliant on schema types alone.

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 ('Lists Pollar's current leading news events') plus the ranking logic ('freshness and editorial momentum'), and explicitly distinguishes itself from search_news for subject/geographic requests. An agent can route correctly without opening either 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?

Gives an explicit positive condition ('broad requests for current headlines with no named subject, place, or country') and names the alternative that owns the excluded cases ('subject and geographic requests belong to search_news'). It also points to list_categories as the source of valid category paths.

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/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are ranked by recent mentions within Pollar's coverage, and returned slugs feed get_entity. It omits pagination and how locale/limit shape results, but the added ranking and interoperability details exceed the annotation baseline.

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 no filler: the ranking behavior and scope are front-loaded, and the get_entity hand-off is appended as the actionable next step.

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 list tool with an output schema present, the description needn't explain return values, and the purpose and follow-up path are covered. The main shortfall is the unaddressed locale/limit parameters that affect the result set.

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 carries the load, but it only implicitly conveys the 'type' parameter via 'people, organisations or places'. Ranking hints at the limit concept, but locale and the 1-50 limit bound/default are entirely 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 verb (lists) and resource (people, organisations or places most present in recent coverage), plus the ranking criteria ('ranked by recent mentions'). It distinguishes itself from siblings by describing the trending-entity role and naming get_entity as the follow-up for profiles.

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 concrete triggering scenario ('who is in the news this week') and points to get_entity as the natural next step with a returned slug. It stops short of stating when not to use it (e.g., versus list_top_news or search), so it is clear context without explicit exclusions.

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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description goes beyond that by disclosing result ordering (nearest first), the distance unit (km), and that place names are accepted in four languages. It does not mention result-count limits or paging, so it falls just short of full behavioral disclosure.

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 filler, with the core purpose, ordering, and input constraints front-loaded before the sibling routing. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and annotations cover the safety profile, so return-format details are not needed. The description is nearly complete for correct invocation, with only the radius semantics left to the schema's defaults and constraints.

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 40%, so the description must carry weight: it explains the multi-language 'place' input, the supported locales, and that 'country' exists solely to disambiguate ambiguous names. However, 'radiusKm' (the parameter that actually defines 'around') and 'limit' get no explanation beyond the vague word 'around'.

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 ('Lists recent Pollar events'), the geographic scope ('in or around a named city or town'), and the ordering ('nearest first, with the distance in km'). An agent can distinguish this from the broad search_news sibling without opening either 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?

Explicitly routes the wrong case elsewhere: 'A whole country, a region or a topic is a job for search_news.' Combined with the stated valid input ('a named city or town'), the when-to-use condition is unambiguous.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds modest value by stating the 10-item cap and that titles/URLs are shown 'exactly as given' (no rewriting), but says nothing about output format or rendering behavior beyond that.

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, no padding, and the core purpose and item limit are front-loaded before the display detail. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only render tool with an output schema and full annotations, the description covers purpose, data source, and item limit adequately. The main gap is that the optional 'heading' parameter is undocumented anywhere.

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 partially does: it explains what 'items' are (stories with titles and canonical URLs, capped at 10), but the 'heading' parameter and item fields like 'lead' and 'publishedAt' are never mentioned.

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 ('Shows up to 10 stories ... as a compact linked list') and identifies where the data comes from (search_news, list_top_news, search results), which separates this presentation tool from the retrieval siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'from earlier search_news, list_top_news or search results' makes the intended workflow clear: call it after you already have result items. It gives clear context but no explicit when-not-to-use or alternative comparison.

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 (readOnlyHint true, destructiveHint false, openWorldHint false), so the bar is lower, yet the description still adds the ranked-list return semantics and the important locale-behaviour rule. It does not describe result limits, ranking criteria, or empty-result behaviour, but it adds genuine context beyond the structured fields.

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?

Four short sentences, purpose and return shape front-loaded, followed by query guidance, locale semantics, and the handoff to fetch. The return-shape sentence partially duplicates the output schema, which is the only wasted content.

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 enumerated, and the description still covers purpose, query construction, locale semantics, and the follow-up tool. The one meaningful omission is sibling disambiguation against search_news and news_near.

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 50% because locale has an enum but no description; the description fills that gap by explaining locale controls response language rather than geographic scope. It also steers how query should be formed (subject, person, organisation, place, country), adding meaning beyond the schema's bare "Free-text search query".

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 ("Searches Pollar's published news") and names the return shape, so the operation is unambiguous. It implicitly separates itself from news_near by noting locale is language, not geography, but it never distinguishes itself from the near-identical sibling search_news, leaving one key identity question open.

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 useful positive guidance (queries about a subject, person, organisation, place, or country, with that subject as the query) and points to fetch as the follow-up step. However, it never states when to prefer this tool over search_news, list_top_news, or news_near, which is exactly the choice an agent faces with this sibling set.

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/openWorld/destructive hints, so the safety profile is covered. The description adds genuine behavioral context that annotations cannot: the matching strategy (semantic + keyword) and the non-obvious fact that locale governs response language rather than geographic scope. It stops short of mentioning result ordering or the limit cap, but that is a minor gap.

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 tight sentences, each doing distinct work: capability, usage scope with example, and sibling disambiguation. The routing constraint is front-loaded with 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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. The description supplies the usage criteria and the critical locale/query semantics; the only omissions are pagination behavior and result ordering, which are minor for a 3-param 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 coverage is only 33%, so the description must compensate, and it does for the two most ambiguous params: query is defined as where the subject or place goes, and locale is explicitly disambiguated as response language, not geographic scope (a common trap given the enum of en/pl/de/fr). Only limit is left to the schema's default/max/min.

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 (Searches) and resource (Pollar's news archive) plus the retrieval method (semantic and keyword matching). It explicitly carves out the boundary with the sibling list_top_news, so an agent can choose between them without opening either 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?

Gives concrete when-to-use criteria (any question about a subject, person, organisation, place, or country) with an example, and states the when-not case (current headlines with no subject or place) along with the named alternative list_top_news.

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