Pure Report — Neutral News

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

With annotations declaring readOnlyHint=true, the bar is lower, and the description adds useful context about the tool's informational content. However, it does not mention the potential write side effect when report_subject and report_body are provided (which files feedback), nor any other limitations. It provides moderate transparency beyond the annotation but not 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?

The description is two sentences, front-loaded with a clear list of content, and ends with a practical usage directive. Every word earns its place 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?

The tool is an informational resource, and the description covers its full scope and purpose. Since an output schema exists, return format details are not required. The presence of optional parameters is not explained in the description, but they are well-documented in the schema, so the overall context is complete enough.

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 100%, so the baseline is 3. The description does not add any meaning to the parameters, but the schema descriptions are already detailed, especially for report_subject. No additional compensation is needed or provided.

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 what the tool does: it explains how Pure Report works, listing specific content areas (bias scale, neutralization method, verification, labeling, coverage, support contact) and explicitly says when to call it ('to cite the source or explain its methodology'). This distinguishes it from sibling tools like get_article or 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?

The description provides direct usage guidance ('Call this to cite the source or explain its methodology to a user'), making the intended use clear. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to disambiguate from siblings. The schema additionally provides fallback guidance for report_subject, but that is outside the description.

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 the readOnlyHint annotation, the description reveals that replies are human-written and delayed, that the reply appears only 'once one exists,' and that status can be open/answered/closed. This adds meaningful behavioral context, though it does not cover failure or not-found 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 exactly two sentences: the first front-loads the purpose and input source, the second adds return fields and critical timing guidance. Every word contributes, with no filler or unnecessary 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?

For a simple one-parameter read-only tool with an output schema, the description adequately covers prerequisite (ref from submit_feedback), return values (status and reply), and usage cadence. The only omission is error handling, which is minor for this scope and not required given the output schema exists.

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 already covers the single parameter 'ref' with a description that includes the same example format as the tool description. The description adds no new meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: 'Look up feedback you filed with submit_feedback.' It clearly distinguishes itself from the sibling submit_feedback tool by referencing the ref returned by that tool, and from other read tools by its focus on feedback status and replies.

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 explicitly says when to use the tool: after filing feedback via submit_feedback, using the returned ref. It also provides clear exclusion guidance with 'poll sparingly, on the order of hours or days, not seconds,' and explains why (replies are human-written and not immediate).

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 set readOnlyHint=true, so the description's mention of output details (bias-score spectrum, quotes) adds useful context without contradicting. It doesn't add behavioral traits beyond what annotations provide, but the output description is valuable.

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 deliver the purpose and usage efficiently. No fluff, front-loaded with key action and output.

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 description fully covers the tool's complexity: it explains the output (spectrum, framing quotes grouped by bias) and its role as the core comparison view. With an output schema present, return values need no extra explanation.

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 100% with a clear description of the slug parameter. The description adds context that the slug comes from trending_events or search_news, providing extra 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 shows how outlets framed an event with a bias-score spectrum and verbatim framing quotes grouped by ideology. It distinguishes itself from siblings like get_article (single article) and trending_events (list of events).

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 tells agents to use it to detect slant and consensus, and mentions the slug comes from trending_events or search_news. However, it could explicitly state when not to use it or list alternatives (e.g., use get_article for a single article).

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 safety profile is covered, and the description adds real behavioral context: summary may be null for older articles, and bias_score applies to the ORIGINAL source rather than the summary. That null-handling and field-scoping detail is genuinely useful and not derivable from structured fields. It stops short of noting any pagination/rate/error 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?

A single front-loaded sentence: the core action comes first, followed by a compact enumeration of returned fields. Dense but every clause carries information; only the parenthetical about the id source borders on redundancy with the schema.

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 one-parameter read tool with an output schema, the definition is nearly complete: it covers the fetch action, the id source, and noteworthy payload quirks (null summaries, bias_score scope). The only gap is the absence of explicit routing guidance relative to sibling 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents article_id and its provenance ('from search_news results'). The description restates the id-based lookup without adding format or edge-case guidance, making the baseline 3 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?

States a specific verb and resource ('Fetch one article by id') and then enumerates the concrete payload (title, summary, source_url, bias_score, source, entities, events), so an agent knows exactly what it gets back. That distinguishes it from search_news (list/search) and get_event (event lookup) 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?

Usage is only implied: 'by id' plus the schema note '(from search_news results)' hints at the search-then-fetch workflow, but the description never says when to call this instead of get_event or search_news. No exclusions or prerequisites 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 only declare readOnlyHint=true, so safety is covered, and the description does usefully disclose that story/account may be null while the census is always returned. However, an output schema already exists to carry return-value detail, and there is no mention of auth, rate limits, or freshness/latency 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?

One long semicolon-delimited sentence, but the core action is front-loaded before the component breakdown. Dense jargon ('gates', 'receipts') adds weight without much payback, yet nothing is wasted enough to undermine it.

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 structure, and it sensibly summarizes the three payload parts and their nullability. Coverage is nearly complete for a single-parameter read tool; only the sibling-selection guidance 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?

Only one parameter and schema description coverage is 100%, with the schema already supplying format guidance and a concrete example slug. The description adds nothing beyond 'by slug', so the baseline 3 applies.

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

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

States a specific verb and resource — 'Get the full neutral writeup of one news event by slug' — and enumerates the three returned components (story, account, census). It implies differentiation from get_article by stressing the writeup is 'Pure Report's own', but never names a sibling, so an agent still has to infer which of get_event/get_article/compare_coverage applies.

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

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

Usage is only implied: pass an event slug, receive a writeup. There is no explicit when-to-use versus get_article or compare_coverage, and no stated prerequisites or exclusions. The null-handling note ('either writeup may be null') is the closest thing to operational 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?

Beyond readOnlyHint=true, the description discloses behavior an agent could easily get wrong: bias_score rates the ORIGINAL source reporting (0=wire-neutral, 100=advocacy), NOT the neutral returned summary. It also discloses the ranking function (relevance and recency), which annotations do not cover.

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 dense, front-loaded sentences with no filler; the core purpose leads and the disambiguation follows. The bias_score sentence is long but earns its place because it prevents a costly misinterpretation. Slightly heavy for a search tool, but no wasted clauses.

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 re-explained, yet the description supplies the interpretive context the schema cannot (what bias_score means, that results carry event links). For a 6-parameter, read-only search tool, nothing an agent needs to call it correctly 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?

Schema description coverage is 100%, so every parameter (limit, query, topic, offset, dates) is already fully documented, and this is the baseline case per the rubric. The description adds no parameter-level detail (e.g. query syntax, topic slug format) beyond the schema; its narrative content is about return values, not 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?

Opens with a specific verb+resource ('Search Pure Report's neutral, bias-scored news') and immediately distinguishes what is returned ('articles with neutral summaries in our own words'). It also names the downstream siblings (get_event, compare_coverage) that consume an event slug, so an agent can place it in the workflow without opening other schemas.

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

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

Gives clear context for when the tool is appropriate ('ranked by relevance and recency', event-linked results) and explicitly routes the agent onward: 'pass an event slug to get_event ... or compare_coverage'. It does not state when NOT to use it (e.g. browsing trending_events for undirected discovery), so it falls short of full alternative/exclusion 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 provide only negative hints (not read-only, not idempotent, not destructive), so the description carries the burden. It adds crucial behavioral context: a human reads the feedback, replies take time and are not guaranteed, and a tracking ref is returned. This goes well beyond the schema and manages expectations appropriately.

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 a single focused paragraph that front-loads the main purpose and outcome. Every sentence earns its place: use cases, required context, human caveat, and follow-up action. There is no fluff or repetition of schema 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 complexity and the presence of an output schema, the description covers everything needed: what it does, when to use it, what context to provide, and what to expect. It even describes the returned tracking ref and how to use it, making the feedback loop fully transparent.

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 100% with detailed descriptions, so the baseline is 3. The description adds value by explicitly instructing to include article_id or event_slug and explaining why ('that context is what makes a report actionable'). It does not repeat schema details for each field, but it highlights the most behaviorally important parameters.

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 opens with a clear verb+resource: 'Report a problem or request to Pure Report's operator and get a tracking ref back.' It distinguishes itself from sibling tools by naming check_feedback as the follow-up for reading replies, and by enumerating concrete feedback types (wrong bias, miscategorised events, missing writeup). This leaves no ambiguity about what the tool does.

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 'Use this when...' scenarios, including data errors, methodology questions, and capability requests. It also tells the user what to include (article_id/event_slug) and points to check_feedback as the alternative for reading the reply, effectively providing both when-to-use and next-step 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?

With only readOnlyHint=true in annotations, the description carries extra weight and does so: it explains that events aggregate many outlets' articles, decodes the headline fallback logic, and states what the has_story and has_account flags promise about get_event's response. It does not discuss pagination or result-volume behavior, but the chaining semantics are genuinely useful context 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?

Three sentences, front-loaded with the core purpose, then field semantics, then the chaining target. Every clause conveys information an agent needs; nothing is padding or restated from the title.

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 re-explained, yet the description still adds the flag semantics an agent needs to decide whether to follow up with get_event. For a single-optional-parameter, read-only list tool, nothing needed 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?

Schema coverage is 100% and the single limit parameter is fully described in the schema (range 1-25, default 10). The description adds no parameter-level detail, so the baseline 3 applies rather than a bonus.

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 ('List the news events with the most current coverage activity') and immediately qualifies the ranking criterion, which is what separates it from a plain search. The added definition of an event as a cluster of many outlets' articles about one story removes any ambiguity about what is being listed.

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 frames the usage context (surfacing stories with the most current coverage activity) and gives explicit workflow guidance by naming the downstream tools get_event and compare_coverage for the returned slugs. It stops short of an explicit when-not or a direct comparison against the sibling search_news, so it is clear but not fully routing.

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