Pollar News

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

Annotations declare readOnlyHint=true, so the tool is safe. The description adds the return format (id, title, text, url, metadata with summary and citations), which is useful context beyond the annotation. 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?

One sentence that front-loads the action and resource, directly explains what the tool does. 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 one parameter and an output schema mentioned, the description is sufficiently complete for a single-item fetch tool. It could mention error handling but is adequate given the 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?

Input schema has 100% coverage with a description for 'id' stating it's from the search tool. The description repeats this but adds no new semantic meaning. Baseline 3 is appropriate.

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 one Pollar article by id, distinguishing it from sibling tools like search (which returns IDs) and get_entity (which likely retrieves other entities). The verb 'fetch' and resource 'Pollar article' are 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 explicitly says to use the id returned from the search tool, providing clear context for when to use this tool. It does not explicitly state when not to use it or name alternatives, but the prerequisite is well-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=true (non-destructive). Description adds that locale changes language not editorial scope, which is useful but minimal. 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, purpose first, then usage guidelines, then parameter hint. No redundant words; every sentence adds value.

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?

Simple tool with output schema present (so return values are documented). Description covers input, behavior, and usage. Complete for its complexity.

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

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

Only parameter locale is fully described with enum values and default. Description specifies its effect ('changes language, not editorial scope'), adding meaning beyond schema. 0% schema coverage but description covers all.

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 it fetches Pollar's daily brief and enumerates its components (greeting, headline, etc.), distinguishing it from siblings like search_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?

Explicitly states when to use (user asks for Pollar daily brief or curated digest) and when not to use (questions about subject/person/place/country, directing to search_news).

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 include readOnlyHint=true, confirming a safe read operation. The description adds behavioral context by stating it returns a profile and canonical URL, and that setting withTimeline includes recent events. This supplements the annotations without contradiction.

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

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

The description is two sentences long, front-loading the purpose and key parameter. Every sentence provides essential information without redundancy or unnecessary detail.

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 externally. The description explains the core behavior and the timeline option. However, it does not mention the locale parameter or the specifics of how type affects the request. Overall, it is mostly complete for a simple fetch 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 description coverage, the description should compensate but only mentions slug and withTimeline briefly. It does not explain locale, type, or the expected format of slug. The schema provides enums and defaults, but the description adds minimal value beyond that.

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 'Fetches Pollar's profile for a person or organisation by slug' which is a specific verb-resource pair. It distinguishes from siblings like get_event and get_thread by specifying entity profiles. The mention of the withTimeline parameter adds further clarity.

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

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

The description does not explicitly state when to use this tool versus alternatives like get_event or get_thread. It only says it fetches a profile, leaving the agent to infer usage from context. No exclusions or when-not-to-use guidance is provided.

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, which the description does not contradict. The description adds rich behavioral context by listing return fields: title, lead, summary, sources, people, locations, charts, and URL. This goes beyond the annotation's safety hint.

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?

Single sentence, front-loaded with the main action, and efficiently conveys purpose and return contents 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?

With an output schema present, the description need not detail return values. It lists key fields, covering the tool's main use case. Complete for the given complexity.

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

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

Schema coverage is 50%, with slug having a description and locale having an enum and default. The description adds context for slug (source from other tools) but does not detail parameter semantics beyond schema. Adequate but not exceptional.

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 full coverage of a single event by slug, distinguishing it from sibling tools like search_news and list_top_news, which provide slugs. The verb 'fetches' and resource 'full Pollar coverage' are 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 explicitly tells users to obtain slugs from search_news or list_top_news, providing clear guidance on prerequisites and related tools. It could mention when not to use this tool, but the context is well-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?

Adds significant behavioral context beyond annotations: it fetches a snapshot with ordered updates and source summary, accepts two types of IDs (moment or story), resolves story IDs to latest chapter, and includes a polling guideline. No contradiction 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?

Three sentences that are front-loaded with purpose, then add critical details. No wasted words, 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, the description adequately covers the tool's behavior and parameters. Minor gap: the 'locale' parameter is not explained, but overall it provides enough context for correct 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?

Adds meaning for the 'id' parameter by explaining it can be a moment id or story id, which is not apparent from the schema. However, the 'locale' parameter is not described, leaving its purpose and behavior unclear despite being an enum with a default.

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 'Fetches' and the resource 'breaking-news moment snapshot', and distinguishes itself from siblings by mentioning it accepts both moment id and story id, and clarifying it is a point-in-time read rather than 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?

Provides clear context for usage: point-in-time read, not a stream, with a specific refresh wait time of at least 30 seconds. However, it does not explicitly state when to use this tool over alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict this. It adds behavioral context by specifying that it returns a 'snapshot' with specific fields (title, status, chapters), which is useful 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 concise sentences that front-load the purpose and immediately provide usage guidance. No redundant or extraneous information.

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

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

Given the tool's low complexity, the presence of an output schema, and the annotations, the description is complete. It covers what the tool does, what it returns, and how it differs from related tools.

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%, meaning the description does not explain the parameters. The 'id' parameter is implied but not described; the 'locale' parameter with enum and default is not mentioned at all. The description adds no meaning 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?

The description clearly states it fetches a snapshot of a story by id, including title, status, and ordered chapters. It explicitly distinguishes from sibling tool get_live_moment, which returns a single chapter.

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 explicit guidance: 'Use this when you want the multi-chapter arc, not the latest chapter alone. For a single chapter, use get_live_moment.' This clearly indicates when to use this tool and when to use the alternative.

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 agent knows it's safe. Description adds value by explaining that calling without arguments returns a catalogue, and with symbol/range returns detail. 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?

Two sentences, no redundant words. First sentence states output, second explains usage variants. Efficient and front-loaded.

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 moderate complexity, optional parameters, and presence of output schema, the description covers main usage patterns. Lacks mention of error handling or authentication but annotations are not expected.

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 50% coverage (symbol has description, range does not). Description adds meaning: explains how to use parameters (no args for catalogue, symbol for detail, range for history) and advises calling without args first. This compensates for schema gaps.

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 returns market data with specific categories (indices, currencies, crypto, commodities, bonds). It distinguishes two usage modes (catalogue vs. detail with history), making the purpose unambiguous.

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?

No explicit guidance on when to use this tool versus sibling tools (e.g., search, fetch). The description explains parameter usage but does not provide when-to-use or when-not-to-use 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 declare readOnlyHint=true. The description adds value by specifying returned data (thesis, state-of-play, chronicle entries) and the effect of withHistory, which goes beyond the annotation's safety signal.

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 efficiently convey purpose and key parameter. Could be slightly more structured (e.g., listing parameters), but no redundancy exists.

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 only 3 parameters, the description covers core functionality and a conditional option. Missing details on errors or locales, but sufficient for a read-only 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 only 33% schema coverage, the description compensates for slug and withHistory: slug is sourced from list_threads, withHistory includes evolution. Locale is not explained beyond the enum, so some gap remains.

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 a single Pollar thread by slug, listing specific data points like thesis and chronicle entries. It distinguishes from sibling tools like list_threads by specifying it returns a single item with additional detail.

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 mentions obtaining the slug from list_threads and explains when to set withHistory=true. It provides context for use but does not explicitly exclude scenarios for alternatives like get_entity or get_event.

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, and the description adds that the tool takes no arguments and returns taxonomy with counts. This provides sufficient behavioral 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?

The description is two sentences with no unnecessary words. Purpose and usage are front-loaded, and every sentence contributes value.

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 parameterless, read-only tool with an output schema, the description provides enough context: what it returns and its integration with list_top_news. The existence of an output schema compensates for not describing the return structure in detail.

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 input schema is empty, and the description explicitly states 'Takes no arguments,' confirming the lack of parameters and adding clarity beyond the schema's implicit emptiness.

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 specifies its use case for discovering valid dot-paths before using list_top_news. This distinguishes it from sibling tools like 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?

The description provides explicit guidance: use it to discover category paths before filtering list_top_news. It implies when to use it but does not mention when not to or suggest alternatives, though 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 declare 'readOnlyHint: true', so the agent knows it's a safe read operation. The description adds behavioral context beyond annotations by noting that each moment carries story metadata and that chapters are returned in order for multi-chapter stories. This enriches the agent's understanding of the tool's 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?

The description is extremely concise: two sentences that cover purpose, usage, and relationship to another tool. Every sentence adds value, and the most important information (the tool's primary function) is front-loaded. 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?

Given that an output schema exists (presumably documenting return values), the description need not explain return format. It covers the tool's scope (live and recently ended moments), time range (24 hours), and linkage to 'get_live_moment'. It does not mention pagination or sorting, but for a list tool with a single optional parameter, this is sufficiently complete with the output schema present.

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%, meaning the description does not mention the only parameter 'locale' at all. Although the schema is self-explanatory (enum with default), the rubric requires compensation when coverage is low. The description fails to add any meaning about the parameter, leaving the agent to infer its purpose solely 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?

The description clearly states the verb 'Lists' and the resource 'Pollar's live and recently ended breaking-news moments'. It distinguishes from sibling tools like 'get_live_moment' by mentioning that passing a returned id leads to that tool, and from 'list_live_stories' by focusing on moments rather than stories. The purpose is specific and unambiguous.

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 explicitly says 'Use to discover what is breaking now or what ended within the past 24 hours', providing clear context for correct usage. It also mentions that passing a returned id to 'get_live_moment' gives the current snapshot, hinting at when to switch tools. However, it does not explicitly state when not to use this tool or compare it to other sibling tools like 'list_live_stories'.

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

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

Annotations already declare readOnlyHint=true, and description adds that it lists 'active and developing' stories, which provides behavioral context beyond safety. No destructive hint is contradicted.

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 concise sentences, front-loaded with purpose, each sentence adds value. 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?

Given the tool's simplicity and presence of an output schema, the description adequately covers the purpose and usage context. It mentions relationship to get_live_moment. Could optionally include pagination info but is not necessary for this list endpoint.

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 description does not mention the only parameter 'locale'. While the parameter's enum values are self-explanatory, the description adds no value for parameter semantics, failing to compensate for the lack of schema descriptions.

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 Pollar's active and developing breaking-news stories and distinguishes from siblings by highlighting the narrative arc structure with umbrella title and chapters. This differentiates it from list_live_moments and get_live_story.

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 explicit usage guidance: 'Use this when you want to surface the narrative arc... rather than each moment in isolation.' It also mentions how to use the returned story id with get_live_moment. It lacks explicit 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 indicate readOnlyHint=true; the description adds context about the nature of threads (evergreen storylines) and change magnitude, but does not contradict. No additional behavioral concerns are needed for a simple listing operation.

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 with no wasted words. Front-loaded with the core action and followed by use guidance.

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 a simple parameter set, the description adequately explains the tool's purpose and outcome. Could briefly note that it returns a list of thread summaries, which is implied by 'pass an id to get_thread'.

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 parameter 'locale' has an enum and default but 0% schema description coverage. The description does not mention the parameter or its purpose, failing to add meaning 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 lists active evergreen threads with details like section and change magnitude. It distinguishes from sibling tool 'get_thread' by indicating that tool is for detail after obtaining an id from this list.

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 suggests use for discovering long-running topics and implies the next step using get_thread. However, it does not explicitly state when not to use this tool, such as when a user needs a specific thread detail immediately.

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?

Description adds behavioral context beyond annotations: ranking method (freshness and editorial momentum), optional filtering by taxonomy dot-path, and prerequisite call. No contradiction with readOnlyHint.

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, each adding distinct value: purpose and ranking, usage guidance with alternative, filtering details with prerequisite. Concise and well-structured.

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 simplicity of tool, presence of output schema, and annotations, the description covers purpose, usage, filtering, and prerequisite. No gaps identified.

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?

Adds meaning for category parameter with examples and prerequisite (list_categories). Limit and locale are not explained but are self-explanatory via schema (default, min, max, enum). Partially compensates for low schema description coverage (33%).

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 explicitly states the tool lists 'current leading news events, ranked by freshness and editorial momentum', specifies scope as 'broad requests for current headlines with no named subject, place, or country', and distinguishes from sibling search_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?

Explicitly provides when to use (broad requests) and when not to use (subject/geographic requests, directing to search_news). Also advises calling list_categories when 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 already mark it read-only; description adds context about required prerequisite calls and immutability of titles/URLs, though no mention of error handling or output 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 with purpose upfront, front-loading key constraints and prerequisites, every sentence adds value.

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 basic usage for a rendering tool; missing details on output format but output schema exists to supplement.

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 description coverage, the description only indirectly mentions 'items' as results from searches and does not explain the 'heading' parameter or structure of array items.

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 renders selected stories already returned by specific search tools, distinguishing it from data-retrieval siblings like search_news 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?

Explicitly instructs to call search tools first, then pass up to 10 results without modifying titles or URLs, providing clear when-to-use and constraints.

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 mark readOnlyHint=true, so description correctly aligns with a read operation. It adds behavioral context: returns a ranked list, and locale affects response language not geography. Does not cover rate limits or pagination, but acceptable given 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 with no waste. First sentence states purpose and output format, second provides usage guidance, third links to the fetch tool. Well front-loaded.

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 a simple tool with 2 parameters and an output schema, the description covers purpose, usage, locale nuance, and return format. No gaps left.

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 query as free-text and locale as enum with default. Description adds that locale controls response language, not geographic scope, and advises to put the subject/place in query. This adds meaningful guidance 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?

The description clearly states the tool searches Pollar's published news and returns a ranked list of articles with a specific structure {id, title, url}. It distinguishes from siblings like fetch by noting that to read an article you pass an id to 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 guidance on when to use (queries about subject, person, organisation, place, or country) and explains locale's role. However, it does not explicitly mention when not to use or contrast with alternative tools like search_news or list_top_news.

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 safety is covered. Description adds behavioral context: 'semantic and keyword matching', and 'locale controls response language, not geographic scope'. No contradictions. Value beyond annotations.

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

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

Two sentences, front-loaded with the core action. No unnecessary words. Every sentence adds value.

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 (3 params, output schema exists), the description covers purpose, usage, parameter hints, sibling distinction, and an important nuance about locale. Complete for effective agent invocation.

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

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

Schema description coverage is low (33%). Description compensates by explaining query semantics: 'Put the subject or place in query' and locale semantics. Does not mention limit, but provides useful guidance for the key parameters. Adds significant meaning 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 specifies verb 'searches', resource 'Pollar's news archive', and method 'semantic and keyword matching'. It distinguishes from sibling 'list_top_news' by stating when to use that tool instead. Clear and 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?

Explicitly states when to use: 'subject-specific query including a person, organisation, place, or country'. Provides clear when-not-to-use: 'For current headlines with no subject or place, use list_top_news'. Also explains locale behavior.

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