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

With no annotations provided, the description carries full behavioral burden. It explains that clusters are rebuilt and IDs are not permanent, which is a key behavioral trait. However, it does not explicitly state that the operation is read-only or disclose any constraints like rate limits, permissions, or how the tool handles missing/invalid IDs. The implied read nature from the purpose is insufficient for maximum transparency.

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 efficient at three sentences, but the first sentence ('Every outlet that carried one story, grouped by independent voice, with the signal that matched each into the cluster') is slightly convoluted and could be streamlined. The remaining sentences are clear and front-loaded with usage 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 tool has only one parameter, no output schema, and simple scope, the description adequately covers what the tool returns (outlets grouped by voice with signals) and provides usage context. It could be more complete by specifying if there are limits or pagination, but the current description suffices for an uncomplicated 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 schema already describes event_id with 100% coverage. The description adds critical semantic nuance: that event IDs are not permanent and must be re-resolved from get_top_events, going beyond the schema's static description. This extra context helps the agent understand the parameter's lifecycle and proper usage.

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 every outlet that carried a story, grouped by independent voice with matching signals, and explicitly defines its use case: checking corroboration and citing original reporting. The title 'Get one story cluster' aligns and distinguishes it from siblings like get_top_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?

Explicitly states when to use the tool ('to check how well-corroborated a story actually is before repeating it, and to cite the original reporting') and provides critical guidance that event ids are not permanent, advising to re-resolve from get_top_events rather than storing IDs. This effectively differentiates it from siblings.

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 no annotations, the description carries the full burden and delivers real behavioral context: the wait/polling semantics, the one-hour retention window, and the constraint that only the originating API key can read the result. It omits error behavior for expired or unknown ids, but the operational constraints disclosed are substantive.

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, front-loaded with what is returned, then the usage trigger, then the retention/auth caveat. No sentence is redundant and nothing is buried.

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 two-parameter poll tool with no output schema and no annotations, the description covers return contents, timing, retention and auth. It stops short of describing the shape of the returned data or the failure mode when an id is expired, but is otherwise sufficient to call correctly.

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

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

Schema description coverage is 100%, and the schema fully documents both `id` and `waitSeconds` (default, range, meaning). The description merely echoes the wait behavior already stated in the schema, so the baseline 3 is correct.

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

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

The description states a specific retrieval purpose — returning the sources, excerpts and analysis of a research request by id — and names the sibling `research` as the tool that starts such a request. An agent can distinguish it from the sibling without opening either schema.

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

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

"Use it when the research tool returned before the request finished" gives an explicit trigger condition tied to a named sibling. It does not state when not to use it or what happens if the request has already been collected, but the main routing decision 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?

With no annotations, the description carries the burden and adds meaningful behavioral context: it mentions the aggregate sentiment reading and that it returns recent coverage. It doesn't disclose all possible limitations or return format, but for a read-only news tool the key behaviors are covered.

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

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

Two sentences, front-loaded with the main function and immediately followed by usage guidance. 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?

Despite no output schema, the description gives a sufficient overview of the return content (news, press releases, sentiment score) and provides usage context. All parameters are documented in the schema, but it doesn't mention tier restrictions for sentiment filtering (though this is in the schema). Overall, well-rounded for a simple retrieval tool.

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

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

Schema description coverage is 100%, with all four parameters fully described (limit, symbol, sentiment, includePressReleases). The description adds no extra parameter-specific semantics beyond what the schema already provides, so 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?

The description clearly states the tool retrieves recent news and press releases for a single ticker symbol, including an aggregate sentiment reading. It explicitly distinguishes this from search_news, which handles multiple companies or free-text matching.

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 an explicit directive: 'Use this when the question is about one company; use search_news when it spans several or needs free-text matching.' This is a strong when-to-use vs. alternative-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 no annotations, the description carries the full burden. It discloses the tier requirement, performance characteristics (slower, on-demand computation), and a data-sufficiency caveat. This goes beyond a simple 'returns sentiment' statement and helps set expectations.

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 the core function front-loaded, followed by essential caveats. Every sentence adds value and there is no redundant repetition of the tool name or 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?

There is no output schema, but the description summarizes the key output components: sentiment breakdown, basis, and a data-quality note. It doesn't enumerate every field, but for a 3-param tool with a moderate output, this is adequate for selection and 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?

The input schema provides 100% coverage with descriptions for all three parameters. The tool description does not add additional meaning beyond the schema; it references the timeframe generically but doesn't elaborate on parameter syntax or constraints.

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 a specific verb ('analyse') and resource ('sentiment for one ticker'), and differentiates itself from sibling tools by mentioning the positive/negative/neutral breakdown and the basis. It is not a generic restatement of the name.

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 context: requires pro tier, slower than other tools due to on-demand article analysis, and advises checking the 'not enough data' note. It lacks explicit exclusions or named alternatives, but the caveats give practical guidance for when 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?

With no annotations provided, the description carries the full burden. It explains the ranking logic (independent voices vs. outlets, press release treatment) but omits important behavioral details: pagination behavior, default handling of hours parameter, tier requirements for symbols, and return format. The description adds value but leaves gaps.

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, no wasted words. The opening sentence immediately states the purpose, followed by usage guidance and a key behavioral nuance. 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?

Given the complexity (7 parameters, no output schema, no annotations), the description covers the core concept and usage guidance but lacks details on return structure, pagination, default behaviors (e.g., hours default), and tier restrictions. It is adequate but not fully complete for an agent to use without additional context.

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 adds conceptual context about independent-voice counting and ranking, which enriches understanding of minVoices and orderBy, but does not provide additional parameter-specific guidance beyond what the schema already states. No significant value added 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 returns 'the biggest stories right now, as clusters of coverage rather than individual articles.' It distinguishes itself from search_news for open-ended questions and explains the ranking by independent corroboration, making the purpose highly specific and actionable.

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 advises preferring this tool over search_news for open-ended questions, providing a clear alternative. However, it does not address other sibling tools like get_symbol_news or list_press_releases, nor does it specify when not to use this tool (e.g., for individual article lookups). The guidance is clear but narrowly scoped.

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 no annotations, the description carries the transparency burden. It discloses the output shape, scope, and the lack of an API key requirement, which is useful. However, it omits potential behavioral details such as rate limits, sorting order, or the exact definition of 'recent', leaving room for uncertainty.

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 front-loaded with the core purpose, followed by a practical use case and a critical auth note. Every sentence adds value, with no redundant or filler content. It is 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?

For a simple tool with one optional parameter and no output schema, the description provides enough context: it explains the result format, the use case, and the auth requirement. It could be more complete by explaining how the 'limit' parameter affects results or giving an example, but it is not seriously lacking.

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 provides 100% coverage for the single 'limit' parameter, including a description. The tool description adds nothing beyond the schema, so it meets the baseline but provides no extra semantic value.

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 specifies the resource ('trending topic clusters'), scope ('recent coverage'), and output format ('keyword groups with article counts'). It distinguishes itself from siblings by emphasizing a query-free, market-level overview, in contrast to search_news or get_symbol_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 explicitly states when to use the tool: 'without a specific query' and for answering 'what is the market talking about right now'. This implies a contrast with query-based search tools, though it does not explicitly name alternatives, which keeps it just short of a perfect score.

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 no annotations, the description carries the full burden. It implies a read-only reporting action, but does not explicitly state side-effect-free behavior, auth needs, or response format. The lack of any mutating language is a minimal indicator, but richer context would be helpful.

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: first states the primary function, second gives practical usage guidance. Every word earns its place, and it's front-loaded with the main action.

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 diagnostic tool, the description provides essential information: what it reports and when to use it. It lacks response structure details, but that's not critical for such a simple tool, and there's no output schema to fill the 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?

The tool has zero parameters, so the schema is empty. Per the rubric, 0 params warrants a baseline of 4. The description adds no param details, but none are 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 reports the API key's tier, feature entitlements, and remaining daily quota. This specific verb+resource makes it distinct from sibling tools, which are all news/sentiment related.

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 this tool to explain permission or rate-limit failures from other tools, providing a clear when-to-use scenario. It doesn't name alternatives, but siblings are clearly unrelated, so no exclusions are necessary.

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 no annotations, the description carries the burden. It discloses the wire-source nature and aggregation from multiple providers, but does not mention response format, pagination behavior, sorting, or any access limitations. This is adequate but not rich.

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 provider context, followed by a concise usage directive. Every word earns its place; no filler or repetition.

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

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

The description covers purpose, sources, filters, and use case, but with no output schema or annotations, it omits the return shape, pagination, and default ordering. For a list tool with 7 optional parameters, a bit more detail on result behavior would be valuable.

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 adds no parameter syntax or format details beyond restating that filtering is by symbol, provider, company, and date, all already captured in 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?

Description uses a specific verb ('list') and concrete resource ('company press releases straight off the wires'), naming providers and filterable dimensions. It also distinguishes itself from journalistic news content, aligning with sibling search_news/get_symbol_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: when the user wants primary-source company announcements rather than journalism. It does not name a specific alternative tool (e.g., search_news), but the 'rather than journalism' clause gives clear directional 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?

No annotations are provided, so the description carries the burden for behavioral disclosure. It mentions output includes ids but does not explicitly state read-only status, pagination limits, or which sources are included. For a simple list tool, this is adequate but lacks depth.

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, each earning its place: the first states the core purpose, the second adds critical usage guidance. No fluff or repetition.

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

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

For a simple list tool, the description covers the purpose, a key usage context (filter validation), and hints at the response (with ids). Since no output schema is provided, a bit more detail on the exact response structure would be ideal, but it is sufficiently complete for likely agent use.

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 describes both page and limit with 100% coverage, including defaults and bounds. The description adds no parameter-specific information, 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 'List the news sources GridNews indexes, with their ids,' using a specific verb and resource. It clearly distinguishes itself from sibling tools like search_news by linking its purpose to the sources filter.

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 the agent to 'Call this before using the sources filter on search_news' and explains the benefit (ensuring valid ids), providing clear when-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?

With no annotations, the description carries the full burden and largely meets it: it discloses the pro-tier requirement, the async wait/keep-running behavior with get_research as the collector, and the citation convention [n] with source URL. It does not cover failure behavior or cost, so it falls short of complete.

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

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

Front-loaded with the core verb and the primary branching decision (urls vs. search), and each subsequent sentence adds a distinct fact: depth behavior, tier requirement, wait semantics, citation format. Dense but no filler.

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

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

For an 8-parameter tool with no output schema, the description covers the operational essentials: mode selection, async collection path, tier gate, and return format guidance. Only edge cases like error handling or rate limits are absent.

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 schema already documents all 8 parameters (including enums for mode/depth and the urls example). The description adds framing for urls and depth but no syntax or constraints beyond what the schema states, 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 ('Read documents and return verbatim, cited excerpts') plus the optional comparison variant, and names sibling get_research for collection. An agent can distinguish it from search_news or get_research without opening schemas.

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

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

Explicitly routes between two modes: give `urls` to read specific documents, leave them out to search web or news, and names the trigger ('when a question needs the documents themselves rather than headlines'). Also states when deep applies and how an unfinished request is collected via get_research.

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 are provided, so the description carries full transparency burden. It discloses ordering behavior ('newest-first and reranked against the query') and implies output includes source URLs ('Cite the source URL for any claim you repeat'). It does not explicitly state read-only safety, but 'search' implies no mutation, and this is sufficient for a read tool.

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 fluff: purpose, usage scope, and behavioral notes. All sentences earn their place, and the most critical info is front-loaded in the first two sentences.

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 11 params, no output schema, and no annotations, the description provides needed context: result type (articles/press releases), ordering, and source URL expectation. It does not explain pagination or tier restrictions, but those are already in the schema, so the description is complete enough for effective tool use.

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 each parameter described, so baseline is 3. The description lists filter categories (free text, ticker, source, date range, sentiment, quality score) but adds no semantics beyond what the schema already provides; it is a helpful summary but not additional detail.

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?

Opening sentence states a specific verb+resource: 'Search GridNews for market news articles and press releases.' It clearly defines the deliverable and distinguishes itself from siblings by positioning as 'The primary tool' for any market/company/sector event question, unlike specialized tools like get_symbol_news or list_press_releases.

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 use it 'for any question about what has happened in the markets, at a company, or in a sector,' giving clear when-to-use guidance. Does not name alternative tools as exclusions, but the primary-tool framing implies it as the default choice, so not a 5.

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