Pollar News

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

The readOnlyHint annotation indicates a read-only operation, consistent with fetching. The description adds value by detailing the return fields including summary and citations, beyond the annotation.

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 wasted words, front-loaded with purpose and immediately followed by return format.

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 the simple tool with one parameter and an explicit output schema via description, the definition is complete and sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameter descriptions; the description reinforces that the id is from search but does not add new details beyond 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?

The description clearly states the tool fetches the full text of a Pollar article using an id from the search tool, distinguishing it from sibling tools that fetch other types of content.

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 specifies that the id comes from the search tool, guiding the agent to use this tool after a search. It does not explicitly mention when not to use it, 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?

No annotations contradict description: readOnlyHint=true aligns with 'fetches'. Description adds behavioral context: locale changes language, not editorial scope, and lists included sections (headline, charts, etc.), all 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?

Three short sentences, each earning its place: purpose, usage guidelines, and locale clarification. No wasted words.

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?

Tool has low complexity (1 optional param, output schema present). Description covers purpose, usage constraints, and behavioral nuance. Output schema handles return values, so no further detail needed.

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?

Only one parameter, locale, with enum in schema but no description. Description adds value: 'Locale changes the brief's language, not its editorial scope.' Schema coverage is 0%, but description compensates with clear semantic guidance.

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 clearly states it fetches Pollar's daily brief with specific components (greeting, headline, executive summary, themed sections, events, charts). It distinguishes from sibling tools by emphasizing it's a curated digest, not a general search.

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 when to use: 'only when the user explicitly asks for Pollar's daily brief or curated digest.' Also tells when not to use and provides an alternative: 'Do not use it for questions about a subject... use search_news instead.'

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 indicate readOnlyHint=true, so the description's value is in clarifying the return content (profile and canonical URL) and the withTimeline option. It does not disclose any additional side effects or limitations (e.g., null profile if not found), but is consistent with 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 primary action, no filler. Every word adds value: action, resource, key parameter, return info. Highly efficient.

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 the presence of an output schema and annotations, the description covers the main functionality and optional behavior. It does not mention error handling or edge cases, but for a read-only tool with clear parameters, it is largely sufficient. Minor missing details like locale explanation could improve completeness.

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. It explains that withTimeline includes recent events, and implies slug is the identifier. Locale and type are not detailed, but type enums ('person', 'organization') are self-explanatory. Some parameters lack elaboration, but core ones are covered.

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 clearly states it fetches a profile for a person or organization by slug, with an optional timeline. It identifies the specific resource (Pollar profile) and action (fetch). However, it does not explicitly distinguish this tool from siblings like get_event or get_live_story, but the entity focus is clear.

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 description: use when you need a Pollar entity profile. No explicit guidance on when to avoid it or switch to alternatives. Sibling tools cover events, stories, etc., but the description does not contrast them.

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 declare readOnlyHint=true; description details returned fields (title, lead, summary, citations, etc.), adding rich behavioral context without contradicting 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 purpose and source of slug, no wasted words.

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 output schema present, description adequately covers input context and return content; minor omission of constraints or error cases, but sufficient given tool simplicity.

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 describes slug and locale; description adds crucial context that slugs originate from search/list tools, and lists output fields (not parameters), improving understanding beyond schema coverage.

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?

Clearly states it fetches full coverage of a single event by slug, lists returned content types, and directs to sibling tools for obtaining slugs, distinguishing its scope from search/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?

Explicitly states when to use (to get a single event's full coverage using a slug from search/list tools), providing clear context for selection among siblings, though no explicit 'when not to use' is 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 declare readOnlyHint=true, and the description adds that it is a 'point-in-time read' and not a stream, plus the refresh delay. This aligns with annotations and provides additional behavioral context beyond what annotations offer.

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 sentences, each purposeful. The first sentence states the core action and output. The second clarifies the input flexibility. The third and fourth provide essential behavioral guidance. No filler or 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?

The output schema exists, so return values are covered. The description adds what the snapshot includes (ordered updates, source summary) and explains ID resolution and refresh behavior. This is sufficient for a read-only tool with an output schema, but could mention the locale parameter briefly.

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 add meaning. It explains that the id parameter can be a moment ID or story ID, adding semantic context. However, the locale parameter is not mentioned, leaving some parameter behavior unexplained.

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

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

The description starts with a specific verb ('Fetches') and resource ('breaking-news moment snapshot'), clearly defines what is included (ordered updates, source summary), and distinguishes from siblings by mentioning it accepts moment or story IDs and is a point-in-time read versus a stream.

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 provides clear context: it is a point-in-time read, not a stream, and advises waiting 30 seconds before refreshing. It also explains that story IDs resolve to the latest chapter. However, it does not explicitly state when to use this tool vs. alternatives like get_live_story or list_live_moments.

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, so description adds value by detailing returned fields (title, status, chapters) but doesn't disclose other behavioral traits like pagination or error handling.

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 fluff, front-loaded with purpose. Every sentence 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?

Despite low param coverage, output schema exists (not shown) and description mentions key return fields. However, locale is not addressed, and for a simple tool this is a minor 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?

With 0% schema coverage, description should compensate but only mentions 'by id' without describing the locale parameter or its enum values. The schema itself provides more semantic information than the description.

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

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

The description clearly states it fetches a story snapshot with title, status, and ordered chapters, and distinguishes itself from get_live_moment for single chapters.

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 says when to use (want multi-chapter arc) and when not to (use get_live_moment for a single chapter), providing clear 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, and the description adds context about the types of data and the two modes of operation, going 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?

Two concise sentences, front-loaded with purpose, and no wasted words.

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 sufficiently covers behavior for all argument combinations and the type of data returned.

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 description clarifies that no arguments return the catalogue, a symbol provides detail, and an optional range adds history. This adds meaning beyond the schema’s 50% coverage.

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 clearly states it returns market data across multiple asset classes and distinguishes from siblings that are not market-specific.

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 explains behavior with and without arguments, and the schema hint to call with no args first. It lacks explicit when-not or alternatives but is sufficient.

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 declare readOnlyHint=true, confirming no destructive action. The description adds beyond annotations by detailing what the response includes (canonical url, chronicle entries) and how withHistory affects the data (thesis evolution). It is consistent with the read-only nature.

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: first states main purpose, second explains key parameter, third describes output. No wasted words, front-loaded with actions, and effective for fast scanning.

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 the tool's simplicity and the presence of an output schema (defined externally), the description covers all essential aspects: what is fetched, how to use it (slug), and optional behavior (withHistory). No gaps remain for agent understanding.

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 already describes slug (with example), locale (enum/default), and withHistory (default). Description adds value by connecting slug to list_threads (source), and explaining withHistory's effect ('how the thesis evolved over time'), which is not in schema. Since schema coverage is 100% in terms of descriptions, baseline is 3, but the added context elevates 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?

The description clearly states it fetches a single Pollar thread by slug and lists the components (thesis, state-of-play, chronicle entries). It distinguishes from sibling tools like list_threads by specifying 'from list_threads' and from other entity getters (e.g., get_event, get_live_moment) by targeting 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?

The description implies usage after list_threads (citing 'from list_threads') and mentions the optional withHistory parameter for evolutionary detail. Although it does not explicitly exclude other tools, the context and sibling tool names make it clear that this is for retrieving a single thread by slug.

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, so the safe read-only nature is covered. The description adds the behavioral detail that the tool returns mention counts and provides category dot-paths, which is additional useful context 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?

Two concise sentences with no redundancy. The first sentence front-loads the primary purpose and output, and the second sentence adds usage context. Every word 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?

Given the tool has no parameters and an output schema exists (implied), the description is complete. It covers what the tool returns, how to use it in context, and that it requires no arguments. No gaps remain.

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 parameters, so the description's statement 'Takes no arguments.' is sufficient. With 0 parameters and 100% schema coverage (trivially), the baseline is 4, and no extra parameter info is needed.

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 clearly states the tool returns Pollar's category taxonomy with mention counts, and explicitly ties its usage to a specific sibling tool (list_top_news) by saying 'Use it to discover valid category dot-paths before filtering list_top_news.' This makes the purpose unambiguous and distinguishes it from other 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?

The description gives explicit usage guidance: 'Use it to discover valid category dot-paths before filtering list_top_news.' It also notes the tool takes no arguments. Although there is no explicit when-not-to-use statement, the context is clear enough for an agent to decide.

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?

Beyond readOnlyHint annotation, description adds temporal scope (past 24 hours), chapter ordering, and relationship to get_live_moment. No contradictions.

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 main action. Every sentence adds necessary context without fluff.

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?

Tool is simple (1 optional param, read-only). Description covers return content (story metadata, chapter order) and references further action. Complete for this 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 has 1 param (locale) with 0% description coverage. Description does not mention locale at all, missing opportunity to explain filtering or default behavior. Parameter is simple but description should compensate.

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?

Clearly states it lists live and recently ended breaking-news moments. Distinguishes by specifying temporal scope (within 24 hours) and mentions story metadata and chapter ordering, differentiating from siblings like get_live_moment or list_live_stories.

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 says to use for discovering breaking news now or recently ended. Recommends passing id to get_live_moment for detail. Does not explicitly contrast with siblings like list_live_stories, but 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, so description need not repeat. Description adds useful behavioral context: stories are 'active and developing' and have 'chapters ordered by chapter index.' No contradiction or missing 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?

Three sentences: purpose, structure, usage guidance. Front-loaded, no unnecessary words. Each sentence 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?

The tool is simple (one optional parameter, output schema exists) and the description covers purpose and usage context well. Could mention if there are any limitations like pagination, but not critical for this straightforward list 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?

The only parameter (locale) is optional with enum and default, but the description does not mention it or explain its effect. With 0% schema description coverage, the description should compensate; it fails to add any value for parameter understanding.

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 clearly states it lists active and developing breaking-news stories with chapters, distinguishing it from sibling tools like list_live_moments (which lists individual moments) and get_live_story (which retrieves a specific story). The verb 'list' and resource are explicit.

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 says when to use: 'when you want to surface the narrative arc... rather than each moment in isolation.' Also provides guidance on next steps: 'Pass a returned story id to get_live_moment for the current snapshot.' This helps the agent choose between tools and chain them.

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, so the description adds behavioral context by describing the nature of returned data (threads grouped by section with latest change magnitude). Does not contradict 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 concise sentences with no fluff. First sentence defines behavior, second gives usage advice. Front-loaded with the verb and resource.

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 are covered. The description includes sufficient context about the list content and how to use results. However, the missing locale explanation reduces completeness for parameter usage.

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 only parameter 'locale' has no description in schema (0% coverage), and the tool description does not mention it. The agent cannot infer that locale filters by language despite enum values. This is a significant gap.

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

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

The description clearly states the verb 'Lists' and the resource 'Pollar's active evergreen threads', explaining that they are ongoing storylines grouped by section with change magnitude. It distinguishes from the sibling tool get_thread by suggesting chaining.

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 explicit usage guidance: 'Use to discover long-running topics' and recommends passing a returned id to get_thread for detail. Lacks explicit exclusion of alternatives when not to use, 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?

Annotations already provide readOnlyHint=true, and the description adds that results are ranked by freshness and editorial momentum. No mention of other behaviors like pagination, but the output schema likely covers return structure.

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 sentences, no wasted words. Front-loaded with purpose and ranking, then usage guidance, alternative, and optional filter info. Highly efficient.

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?

Covers purpose, usage, and category filtering. Does not explicitly mention limit or locale, but standard defaults are in schema. Output schema exists so return values are documented. Slight gap in not explaining how to handle large result sets.

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 description adds meaning for the category parameter (taxonomy dot-path and hint to call list_categories), but does not address limit or locale beyond what the schema provides. Schema coverage is only 33%, so partial compensation.

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 clearly states it lists current leading news events ranked by freshness and editorial momentum, and explicitly distinguishes from search_news for requests with a named subject, place, or country.

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 specifies when to use (broad headline requests) and when not (named subject/place/country) with a direct sibling alternative (search_news). Also advises to call list_categories when the category is unknown.

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 indicate readOnlyHint=true, and the description adds constraints on not modifying titles/URLs, though it does not detail rendering behavior (e.g., format).

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 concise sentences, front-loaded with purpose, no unnecessary words.

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?

Covers prerequisites, constraints, and input requirements; presence of output schema reduces need to explain returns; complete for a rendering 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?

With 0% schema coverage, the description partially compensates by explaining that items must be from prior searches and unmodified, but does not elaborate on 'lead' or 'publishedAt'.

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 clearly states the tool renders stories previously returned by specific search tools, distinguishing it from siblings that perform searches.

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 instructs to call search tools first and pass up to 10 results without modifying titles or URLs, providing clear when-to-use and how-to-use 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 provide readOnlyHint:true. Description adds that results are ranked, and that locale controls response language. It also discloses that passing an id allows fetching with a sibling tool. No contradictions with 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?

Four sentences, front-loaded with purpose, then usage guidelines. Every sentence adds value with no redundancy or fluff.

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 the low complexity (2 params) and presence of output schema, the description covers return format, usage scenarios, locale semantics, and interaction with sibling tools. Sufficiently complete.

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 50% schema description coverage, description adds meaning: 'put that subject or place in query' guides query parameter usage, and 'Locale controls response language, not geographic scope' adds context beyond the enum.

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

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

The description clearly states the tool searches Pollar's published news and returns a ranked list of articles with id, title, url. It distinguishes from siblings like fetch (by noting to pass id to fetch to read) and search_news (by specifying use for subject/person/organisation queries).

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 explains when to use (queries about subject, person, organisation, place, country) and clarifies locale semantics (language only, not geographic). Does not explicitly state when not to use, but provides clear context.

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 provide readOnlyHint=true, confirming it's non-destructive. The description adds valuable behavioral context: it uses semantic and keyword matching, and locale controls response language not geographic scope. No contradictions with 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?

Description is concise and front-loaded. First sentence states the core purpose. Each subsequent sentence adds value: usage guidance, locale clarification, and sibling distinction. No unnecessary words.

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 the tool has 3 parameters (1 required) and an output schema exists, the description covers key aspects: subject-specific query usage, language vs geography scope, and when to use an alternative. The return format is covered by the output schema. No significant gaps.

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% (only 'query' has a description). The description compensates by adding context: 'Put the subject or place in query' for the query parameter, and 'Locale controls response language, not geographic scope' for locale. No additional guidance for limit, but overall adds meaningful semantics beyond 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?

Description clearly states the tool searches Pollar's news archive using semantic and keyword matching. It distinguishes itself from siblings by explicitly mentioning to use list_top_news for headlines without a specific subject or place, and clarifies that locale controls language, not geography.

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 explicit guidance on when to use: for any subject-specific query (person, organization, place, country). Specifies what to put in the query and clarifies locale's role. Explicitly names alternative tool 'list_top_news' for current headlines without a subject.

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