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

Beyond the readOnly/idempotent annotations, the description discloses matching behavior, the important scope constraint that results come only from the plan's history, the ordering (most mentioned first), the returned fields (id, name, kind), and the two edge cases — empty list means no match, list length equal to limit may mean more behind it.

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 core action and the name-vs-brand rule are front-loaded, followed by return shape and edge cases in a compact block. No sentence is redundant, and the truncation and empty-list semantics are packed economically into one clause.

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 lookup with no output schema, the description covers what is searched, what comes back, result ordering, the coverage limitation (plan history), and both boundary cases. An agent can call it and interpret the response without further information.

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%, so the baseline is 3, but the description adds genuine semantic meaning: the query matches codes and registered names and should be the company's own name, and a result count equal to limit signals possible truncation. Limit's default/max stay 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?

States a specific verb ('look up the code') and resource (company, index, currency, commodity, organisation), with a concrete example ('micron' finds MU). It is clearly distinguishable from get_symbol, which takes a code rather than resolving one, and the last sentence directs the agent to pass the returned code into the other tools.

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

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

Gives real usage guidance: search by the company's registered name, not a brand (Alphabet, not Google), and query against codes or names. It also implies the resolve-then-call pattern for the sibling tools. It does not explicitly name an alternative tool or state when-not to use this one, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), yet the description still adds non-obvious behavior: the silent 3-statement drop threshold, the fact that an empty result may mean "only small ones", and that a storyline_id query silently changes the default sort. Those are the exact gotchas that would otherwise cause a wrong conclusion from an empty page.

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?

Purpose is front-loaded in the first clause, then each following clause handles one concern (sort, symbols, threshold, storyline default) with no filler or repetition. Dense but every sentence carries a distinct, actionable fact.

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, all-optional listing tool with no output schema, the description covers the traps that matter: filtering, threshold behavior, sort semantics, and storyline default ordering. Pagination is deferred entirely to the schema's `cursor`/`limit` descriptions, and the shape of a returned topic is never sketched, which is the only real 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?

Schema coverage is high (88%), so the baseline is 3, and the description earns the extra point by defining what the bare `sort` enum members actually mean (velocity = most statements in the last 24h, size = most statements, recent = latest first, oldest) — information the schema does not carry. It also reinforces the min_statements default split and the comma-OR behavior for symbol.

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 opening sentence gives a specific verb and resource ("List developments") plus the four filter axes (symbol, sector, theme, storyline), so an agent knows exactly what the tool returns. It never names a sibling like `trending` or `search_statements` to contrast against, so differentiation from the rest of the family is left to inference.

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?

There is real operational guidance — which sort mode to pick, the 3-statement default threshold, and the explicit recovery step ("retry with min_statements=1") when a list comes back empty. What is missing is tool-selection guidance: nothing says when to reach for this instead of `trending`, `search_statements`, or `storylines`.

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

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

Annotations already cover read-only, idempotent, open-world safety. The description adds meaningful behavioral context beyond that: `top_topics` appears only when the members list is cut, `more_statements` indicates truncation, and crucially the cursor is null unless `statements` is at maximum, causing `search_statements` to restart and repeat. That cursor-reset behavior is a subtle trait worth disclosing.

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 return summary, followed by dense but purposeful paging instructions. Every sentence carries information about output or continuation behavior. It is a single dense paragraph rather than clearly structured subsections, but it avoids true redundancy.

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

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

With no output schema, the description must explain the return shape, and it does: topics (oldest first), newest statements, `top_topics` fallback, `more_statements`, and `statements_cursor`. It does not describe the internal fields of a topic or statement, but for a retrieval tool that is reasonable and likely covered by 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?

Schema coverage is 100%, so baseline would be 3. The description adds value by explaining the practical consequence of parameter values: `members` at maximum versus paging via `find_topics`, and `statements` at maximum as the only way to obtain `statements_cursor`. It clarifies how parameters interact with returned fields, not just their types.

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 resource (one storyline) and what it returns (topics oldest-first and newest statements), making the detail-view nature clear against the plural `storylines` sibling. It does not explicitly name the list endpoint or `get_topic` as alternatives, so sibling differentiation is inferable rather than stated.

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

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

It gives explicit paging guidance: raise `members` to maximum if topics are truncated, use `find_topics` for longer storylines, and raise `statements` to maximum to get a cursor for `search_statements`. It never says when to choose this over `storylines` or `get_topic`, but the within-call guidance is strong.

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 read-only/idempotent annotations, the description discloses important behavior: omitted empty periods, more_statements, the conditional statements_cursor, related being empty for rarely mentioned symbols, and the cost of guessing a code. These details materially affect how an agent invokes and interprets the 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?

The description is front-loaded with purpose and then structured around returns and continuation behavior. It is fairly long, but most sentences carry necessary information because there is no output schema; the density is justified, though some return-field enumeration could be tightened.

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 complex entity-overview tool with no output schema, the description is highly complete: it explains the profile, time-window sentiment, topics, sectors, storylines, related entities, statements, empty-period behavior, and cursor semantics. An agent has enough context to call it correctly and understand the response shape.

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%, so the schema already documents code, topics, and statements. The description still adds meaningful semantics by explaining that only requesting statements at its maximum sets statements_cursor and enables exact continuation, and by reinforcing code lookup via find_symbol when unsure.

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 resource and scope: 'One company or other entity in a single call' and positions it as the first stop for 'what is going on with X'. It then enumerates exactly what is returned, making the tool's purpose unambiguous and distinguishable from lookup-oriented siblings like find_symbol.

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 to use this first for entity overview questions, warns against guessing a code and routes to find_symbol, and explains how to continue with search_statements using the returned cursor. These are concrete when-to-use and alternative-tool instructions, not implied guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds real value beyond that: it discloses the shape of the payload (counts, source_mix, storylines, newest statements) and the pagination contract, including that the cursor is null when there are no more results.

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 what is returned before the pagination instruction, and no filler. Slightly dense enumeration in the first sentence, but every clause names a distinct returned field.

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 no output schema, the description carries the return-value burden and does so adequately: it names the main payload components and the cursor semantics. It does not say how many statements come back per call or what happens with an invalid or unknown topic_id, which leaves a small gap for a single-parameter detail tool.

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

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

Schema coverage is 100% and the topic_id description already explains the id format, so the schema carries parameter meaning. The description adds one genuinely useful semantic link — that the returned statements_cursor is an input to search_statements — but says nothing new about topic_id itself; the baseline 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 opens with a concrete statement of what is returned: 'One development in full', then enumerates the substance (counts, source_mix, storylines, newest statements with outlet and headline). It also disambiguates the 'topic'/'development' terminology that the tool name leaves ambiguous, so an agent can tell this detail-fetch apart from list/search siblings.

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

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

It names a specific alternative and the exact handoff: use search_statements with topic_id and the returned statements_cursor to retrieve older statements. That is a clear, actionable routing rule. What's missing is the entry condition (e.g., 'use find_topics first if you only have a name rather than an id'), so it stops just short of full when-to-use coverage.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive behavior. The description adds that the response is a current snapshot and that one call suffices per conversation, but it does not cover auth needs, rate limits, or response format details.

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 and then lists distinct returned categories in one dense but waste-free sentence. The short usage note earns its place by preventing redundant calls.

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 zero parameters, no output schema, and annotations covering the safety profile, the description carries the remaining burden well. It enumerates the returned content categories an agent needs to know before calling it.

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 takes zero parameters, so the baseline is 4. The mention of window_days refers to a returned field, not an input, so there is no schema gap to compensate for.

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 reference resource and enumerates exactly what it returns: history window, counts, themes and accepted values. It clearly distinguishes itself from sibling tools that query actual statements, topics, storylines or symbols.

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 says 'One call per conversation is enough,' which gives useful frequency guidance, but it does not explicitly say when to use this versus sibling tools or any prerequisites. Usage is implied by the purpose rather than stated with alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds substantive behavior beyond them: the exact conditions under which `change` is null and the recommended fallback, and the caveat that without entity_kinds the list mixes companies with rates, commodities and central banks. It also enumerates what each returned row contains, which matters because there is no output schema.

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?

Purpose and the key "when" are front-loaded, and nearly every clause carries new information. Some sentences are dense run-ons, particularly the null-change enumeration, which costs one read to parse but does earn its place.

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

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

With nine parameters, no output schema and no required fields, the description does the important work: row shape, default-mixing caveat, cross-parameter scope (sector only with rank=symbols), and null semantics. Minor gaps remain around ordering of results and how `limit` interacts with min_mentions filtering, but nothing an agent needs in order to call it correctly is 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?

It adds real meaning over the schema — sort=change semantics, the null-change conditions, that sector applies only when rank=symbols, and what min_mentions filters out. But schema coverage is already 78%, so much of this (period, since/until, sector, entity_kinds) is partly redundant with the schema descriptions, and `limit` is untouched. Solid but largely reinforcing existing field docs.

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 opening sentence gives a specific verb (rank), a specific resource (symbols or GICS sectors) and the ranking axis (news attention), plus a concrete question it answers: "which tickers are suddenly in the news". That framing distinguishes it immediately from siblings like search_statements, get_symbol, or sentiment_series.

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

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

It gives clear contextual guidance: use it for sudden news attention, pick period vs since/until for the interval, and explicitly says "Use sort=mentions" when `change` is null. It also advises passing entity_kinds="equity,etf" for tradable tickers. What's missing is explicit routing against siblings — notably how it differs from `trending`, which overlaps on the 'what's hot now' use case.

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 the safe read-only, idempotent profile, so the description sensibly spends its space on behavior beyond safety: newest-first ordering, cursor-based pagination with next_cursor/cursor, and a summary of what each statement contains (source, headline, topic). It does not mention result-size limits or any auth/rate-limit context, but for a read-only search tool this is solid coverage.

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 purpose and use case are front-loaded in the first sentence, and the remaining lines are a compact parameter cheat-sheet. A few lines duplicate schema wording (source_type, importance_min) rather than adding new information, which is minor waste but not damaging.

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 12 optional parameters, no output schema, and full schema descriptions, the description covers the non-obvious behaviors an agent needs: ordering, cursor pagination with the exact handoff mechanism, return-content shape, and the subtle storyline_id/symbol interaction. The remaining filters (sector, theme_id, topic_id, sentiment, limit) are fully described in the schema, so nothing critical 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%, so the baseline is 3; the description earns extra credit by adding meaning beyond the schema: 'no spaces inside a code' for symbol, the exact interaction between storyline_id and symbol ('add symbol for only those naming its company'), and the clarification that since/until apply to the article's publication time. Several other sentences merely restate schema text (source_type, importance_min), which keeps it from a 5.

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 specific verb and resource ('Search news statements') and adds an ordering guarantee ('newest first'), then anchors the purpose in a concrete use case ('what is the news saying about X'). That use-case framing implicitly distinguishes it from siblings like sentiment_series, trending, and the topic/storyline lookup tools.

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

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

It gives a clear usage trigger and explains how specific filters change results (importance_min=high for key facts, source_type=news to exclude speculative/reddit, storyline_id combined with symbol to narrow to a company). It does not explicitly name when to use a sibling instead, so it stops short of a full when/when-not framework.

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?

Goes well beyond the read-only/idempotent annotations by documenting bucket contents, the score formula, that empty buckets are omitted, and the important caveat that the last bucket is a partial day/hour and must not be read as a drop. It also discloses the failure mode for oversized ranges (error states the maximum), which is exactly the kind of behavior an agent cannot get from structured fields.

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

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

Front-loads the purpose and the selector constraint, then the bucket shape, then the two caveats — a logical ordering with no filler sentences. Slightly dense and line-broken mid-thought, but every clause carries 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?

With no output schema, the description does the work of explaining the returned bucket fields and score formula, and it flags the partial-last-bucket pitfall. It leaves gaps on the default range when since/until are omitted and on what happens if zero or multiple selectors are supplied.

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 86%, so the baseline is 3; the description earns above that by adding the cross-parameter constraint 'exactly one of symbol, sector, theme_id or topic_id', which the zero-required-parameter schema does not encode at all. It also adds meaning to interval that the bare enum lacks (hour only for short ranges).

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 resource and shape: 'News volume and sentiment over time' for exactly one of four entity keys, which tells an agent precisely what comes back. It does not compare itself to siblings like search_statements or trending, so the agent must infer that this is the time-series aggregation rather than the raw statement search.

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

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

Gives one concrete usage rule — 'interval=hour is for short ranges: pass since/until' — plus the self-healing hint that the error message reports the maximum range. It never says when to prefer this over search_statements or how to pick among symbol/sector/theme_id/topic_id beyond 'exactly one', leaving the main routing decision implied.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial behavioral context on top: the default min_topics=2 filter and what an empty list means, the automatic grouping's unreliability, story splitting, and the framing as 'a reading aid, not a count of events'. That caveat materially changes how an agent should trust and present results.

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?

Dense but front-loaded: purpose first, then the default-filter gotcha, then return shape and caveats. The return-field enumeration is long but earns its place because there is no output 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?

With no output schema, the description supplies the return fields (name, first_seen, last_seen, topic/statement/mention counts, sources, sentiment, top_topics, related) plus the caveats an agent needs to interpret them. Nothing essential for correct invocation or result interpretation 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%, so the baseline is 3, but the description adds real meaning for min_topics (default hides single-topic storylines; pass 1 to see them), which the schema only states mechanically. Minor deduction for referencing a `topics` parameter that doesn't exist in the schema when explaining top_topics.

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+resource+scope: one company's news grouped into continuing stories (an event plus follow-ups, reactions, consequences). It also distinguishes itself from the sibling get_storyline by naming the case where that tool is needed (every topic in order, or the statements).

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

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

Gives concrete trigger phrases ('how did the X story unfold', 'what are the ongoing stories about X') and routes to get_storyline for finer detail. It doesn't explicitly exclude other siblings like search_statements or find_topics, so it stops short of a full when/when-not map.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds the non-obvious semantic that filtered counts are still whole-theme counts, which prevents a real misinterpretation; it does not mention pagination or result-size limits, keeping it short of a 5.

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

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

Front-loaded with what the tool returns, then the filtering caveat, then the id-reuse instruction. Slightly dense and run-on in the middle clause, but every sentence carries necessary information with no filler.

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

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

With no output schema, the description usefully enumerates the returned fields and explains the filter semantics and id handoff. It stops short of describing item structure or ordering guarantees for the sort options, but nothing critical to invoking the tool 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 sort enum values are already documented in the schema. The description still adds meaning the schema lacks: what symbol/sector filtering actually does and that the counts are not narrowed by it, which is the main semantic trap for these 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?

States the specific resource (standing news themes) and what each item carries — developments, statements, 24-hour volume, distinct sources, sentiment counts — so an agent knows exactly what it gets back. It is clearly distinct from sibling listing tools like find_topics or trending.

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 explicit conditional behavior for symbol/sector ('only the themes that have statements about it') and routes the agent to the correct alternative when per-symbol statements are needed: 'use search_statements with theme_id and symbol'. It also tells the agent to reuse the returned id as theme_id in other tools, which is real workflow guidance.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the description's added value is the cost/shape warning that the slot list is long and should be narrowed, plus the item content (source counts, sentiment counts, newest statement). With no output schema, disclosing the `trending` vs. `trending_labels` distinction and the `total` field is genuinely useful. It stops short of pagination or ordering edge cases.

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 purpose is front-loaded and every topic is relevant, but the body interleaves kind semantics, return-shape detail, an alternative-tool pointer, and item field definitions without clear ordering. The trailing fragment 'symbol: one code only.' reads as an orphaned patch rather than intentional structure.

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 no output schema, the description steps in to explain the returned fields and the `total` indicator, which is the main gap it needed to fill for a 4-parameter read tool. Behavior of conflicting filters (symbol plus theme_id) and how `limit` interacts with `total` are left implicit.

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%, so the baseline is 3, and the description goes beyond it by advising which parameters to use to avoid pulling the full slot list and by noting symbol accepts 'one code only'. The `kind` semantics in the description largely restate the schema's own enum descriptions, so the gain is modest rather than transformative.

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 the resource and scope precisely: 'The developments most outlets are reporting', plus a plain-language gloss ('what is moving / what is the big news right now'). It also differentiates the two modes (live list vs. top of each recent slot). The only softness is that 'developments' is a domain term never defined, so an agent must infer it from the described item fields.

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

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

Gives an explicit use case ('what is moving right now'), an explicit alternative with the condition that selects it ('For a whole day rather than right now, use find_topics with sort=velocity'), and a scoping instruction ('narrow it with symbol or theme_id rather than asking for all of it'). All three when/when-not/alternative dimensions are covered.

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