The Coin Daily Research

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

Annotations already declare readOnly/openWorld/idempotent/destructive hints, and the description adds substantial value beyond them: it discloses that no arguments select the latest actually-published edition which may not be dated today, instructs using the actual publication time, warns not to claim video is playing/embedded without host confirmation, and clarifies that show figures belong to that edition rather than current markets. These are non-obvious behavioral constraints an agent could not derive from the 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-loaded with the trigger condition, then organized into labeled sections (Selection, Presentation, Evidence). Every sentence conveys a distinct constraint or caveat with no filler, appropriate to the tool's non-trivial behavioral rules.

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

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

Given a zero-parameter tool with an output schema (so return values need not be described), the description is complete: it covers selection logic, presentation caveats, and the evidence/edition scoping. An agent has everything needed to invoke it and interpret its results 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?

The tool takes zero parameters, so the baseline is 4. The description does explain the semantics of the empty-argument call (it selects the latest published edition rather than requiring input), which adds useful meaning, but there are no parameters to document beyond that.

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

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

States a specific verb and resource: reading the published Market Update show, its desk briefing or chapters, and gives a concrete user-facing trigger ('What did today's show cover?'). It explicitly distinguishes itself from research_markets, Daily News, arbitrary historical shows, and full archive search, so an agent can tell it apart from siblings 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?

Provides explicit when-to-use (latest Market Update show/briefing/chapters) and when-not-to-use, naming the alternatives by tool name (research_markets) and content type (Daily News, arbitrary historical show, full archive search). Nothing is left to inference.

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, closed-world, non-destructive behavior, so the description's job is to add context, which it does: it discloses that no Research API read occurs, that cases are versioned descriptions of implemented workflows rather than observed market evidence, and that output is structured help. It does not, however, discuss error or rate-limit 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 front-loaded with the primary use case and then segmented into labeled Selection, Presentation, and Evidence blocks, so an agent can scan it. It is dense but nearly every sentence carries operational content; only the 'Presentation' guidance edges toward advisory rather than instructional.

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

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

With an output schema present, return values need not be re-explained, and the description instead covers usage, selection behavior, and the nature of the returned cases. That is close to complete for a five-parameter discovery tool among 27 siblings, though it never routes to specific sibling tools for the follow-up actions it describes.

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 baseline is 3, but the description adds real semantics beyond the schema: all query words must match, an empty query lists the whole area, and keywords should be broadened if a result set is empty. This meaningfully clarifies how 'area', 'query', and 'use_case_id' interact.

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 function: resolving which workflow, metric, widget or control serves a question, and serving users who ask what can be investigated. It distinguishes itself from the many research_show_* siblings by declaring it returns 'structured help, not a market result' and by excluding rendering another widget.

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 when-to-use conditions ('user asks what can be investigated', resolving which workflow serves a question) and an explicit when-NOT-to-use list ('live data availability, mandatory preflight before familiar tools, general financial definitions already understood, or rendering another widget'). It also gives selection guidance for choosing between filtering modes.

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 non-destructive behavior, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: terminal states (ready, failed, unavailable, expired), the retry_after_seconds backoff signal, and the instruction to reuse snapshot_id rather than assume a default.

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 trigger condition, then organized into Selection/Presentation/Evidence groups so an agent can scan the operational rules quickly. It is denser than strictly necessary for a single-parameter status check, but each section carries actionable content without 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 an output schema present, the description need not enumerate return values, and it doesn't. Combined with annotations covering safety and the schema documenting the single parameter, the description covers start condition, allowed stop states, polling discipline, and next-step routing, leaving no gap an agent would need filled.

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 itself explains that job_id is the exact value from a preparing cohort request, not the snapshot_id. The description reinforces this ('Pass that exact returned job_id') but adds no format or syntax detail beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: it checks the status of a prior research_prepare_cohorts job identified by a job_id. It distinguishes itself from siblings by scoping to an in-flight preparation rather than starting work, and names the downstream tool (research_compare_cohorts) used once ready.

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?

Explicit when/when-not guidance: use only when a prior result is preparing and supplies a job_id; do not use for starting an unrelated job, refreshing a ready comparison, or rapid/unbounded polling. It also gives stop conditions and lists the alternative (research_compare_cohorts) for the next step.

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, closed-world. The description adds real behavioral context beyond that: snapshot_id must be exact and not synthesized or silently refreshed, unchanged selection fields must be preserved on follow-ups, and evidence endpoints (/lines, /members, /correlation) are authoritative. Return-format detail is legitimately omitted since an output schema exists.

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 long but organized into Selection/Presentation/Evidence sections and front-loads the when-to-use clause. A few presentation sentences ('explain why the observed difference matters') lean editorial, but every section carries actionable guidance rather than 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 a deeply nested, single-request tool with 100% parameter coverage and an output schema, the description covers selection, refinement preservation, and evidence usage adequately. Nothing an agent needs to invoke it correctly appears to be missing, though it depends on sibling tools being consulted for catalogue IDs.

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

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

With 100% schema coverage the baseline is 3, but the description adds cross-parameter semantics the schema does not: the exact snapshot_id must come from prepare/status, bounds must be second-based and inside the history, overlap/benchmark/filters must be preserved on refinement, and correlation requires an explicit pair plus a supported window. This goes beyond per-field schema text.

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 lists concrete use cases (group performance, relative returns, contributions, metric relationships, qualified pair correlation) over a pinned history, which tells an agent what the tool is for. It is slightly use-case-led rather than a crisp 'compare two groups' verb+resource statement, but scope and subject matter are clear and it is distinguishable from siblings like research_prepare_cohorts and research_show_cohorts.

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 states when to use ('measuring group performance... including refinements of an existing comparison') and when not ('Do not use for inventing sector membership, re-preparing history unnecessarily, causal claims or portfolio advice'). It also names related tools implicitly (research_prepare_cohorts/status for the snapshot_id, research_discover for ticker resolution), giving the agent routing 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, non-destructive, closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: paging filters assets rather than group labels, group_id must be an exact returned scope_id, and evidence should be read via research_read_evidence since counts alone don't identify members. It lacks return-format detail, but an output schema exists.

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 routing statement and exclusion are front-loaded, and the Selection/Presentation/Evidence labels keep the dense text navigable. It is longer than strictly necessary, but nearly every sentence carries actionable content.

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 4-param discovery tool with an output schema and full annotation coverage, the description supplies the routing, ID-resolution, paging, and evidence workflow an agent needs. Return-value explanation is rightly omitted given the output schema; only minor gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real nuance beyond the schema: 'Paging filters assets, not group labels', the requirement to reuse exact returned scope_ids, and the offset/query coupling ('use returned next_offset with the same query/group filter'). This meaningfully clarifies otherwise easy-to-misuse 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 states a specific verb+resource (resolving asset names/symbols and checking governed taxonomy membership) and names the exact sibling tools it is not (research_markets, research_compare_cohorts). An agent can distinguish this from the many research_show_* and cohort tools without opening any 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?

It gives explicit when-to-use ('resolving an asset name/symbol or checking governed taxonomy membership'), when-not-to-use with named alternatives, and a concrete example ('Which assets belong to DeFi?'). Routing is unambiguous.

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, and the description goes well beyond them: hourly-close granularity regardless of chart interval, the 31-day ceiling, percentile comparison against prior observations of the same market, the 4h/1d/7d separation rule, and the caveat that null ranks can mean building history. The USDC/USD proxy note is precisely the kind of hidden behavior an agent could not infer.

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?

It is front-loaded with the use-case trigger and then cleanly partitioned into Selection/Presentation/Evidence blocks, so each section is scannable. It is denser than necessary for a two-parameter tool, with some sentences carrying multiple instructions, but little is pure 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 an output schema present, annotations covering the safety profile, and full schema description coverage, the description only needs to add interpretation guidance. It does so: which evidence fields to read first, what null ranks imply, and how to preserve USD/USDC identity.

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 ticker format and the inclusive-start/exclusive-end window semantics in detail. The description only echoes the resolved-ticker and timezone-qualified-window guidance and adds no format or edge-case detail the schema lacks, so 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 states a specific verb and resource ('Read hourly market regime and volatility') and scopes it to a user intent ('changing volatility or how unusual its volatility is within its own history'). It distinguishes itself from non-tools via exclusions, but never differentiates from the near-identically-named sibling research_show_market_context, leaving that potential confusion unresolved.

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 an explicit 'Use this when...' trigger plus a strong 'Do not use for...' list covering price predictions, trading decisions, calibrated confidence, annualised volatility and the retired regime archive. The one gap is that exclusions are stated as task categories rather than routing to a named alternative sibling tool.

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/openWorld=false, and the description goes well beyond them: it clarifies that query only filters tickers, that offset/limit page the published order rather than re-sorting it, and that a page is not the full market population. It also warns how Signal Book rank should be interpreted (attention, not expected return) and points at /items and /metric_metadata for exact rows and clocks.

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?

Use case and exclusions are front-loaded, followed by clearly labelled Selection, Presentation, and Evidence blocks. Every sentence carries an actionable constraint; there is 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 an output schema present, return values need no explanation, and the description still covers usage, exclusions, parameter behavior, result interpretation, and where to fetch exact rows/metadata. An agent has everything needed to call and correctly interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns a bump by consolidating the interaction between query and pagination: query filters symbols and offset/limit walk the existing published order without sorting, plus a shortlist-length preference. Much of this restates the schema, so it is helpful but not fully additive.

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 ('the prepared market board or assets ranked for analytical attention') and gives a concrete user phrasing example, so the agent knows it returns an attention ranking rather than raw market data. It explicitly excludes research_briefing, gainers rankings, and buy/sell advice. It does not, however, differentiate from the very close sibling research_show_markets, which is a real gap in sibling distinction.

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?

Explicit when-to-use ('when the user wants the prepared market board...'), explicit when-not ('Do not use for published show content, a biggest-gainers ranking, or buy/sell recommendations'), and it names the alternative (research_briefing) that handles the excluded case. It also gives a selection preference ('prefer a small requested shortlist'), leaving nothing to inference.

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 establish read-only, idempotent, non-destructive behavior, so the description correctly spends its words elsewhere: the API chooses the lookback window and arbitrary A/B ranges cannot be requested, mention volume is not article counts, and publication timing must not be framed causally. That is substantive behavioral context an agent could not infer from the 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?

Front-loaded usage trigger followed by labeled Selection, Presentation, and Evidence blocks, so an agent can skim to what it needs. Sentences are dense but each carries distinct instruction; no filler. Slightly long for two parameters, but the content is non-redundant.

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 described. Given that, the description covers the remaining gaps: when to invoke, what it cannot do (arbitrary ranges, exhaustive search), and how to present and evidence the results. Nothing an agent needs to call this 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?

With 100% schema coverage the baseline is 3, and the description adds value on top: it tells the agent to use the resolved ticker identifier and an explicit anchor day, and reinforces that the anchor does not give control over the returned news range. That clarifies the intent behind both parameters rather than restating 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 opening clause states the resource and scope clearly: what was reported about an asset around a given day, plus daily topic attention. It distinguishes itself from video-chapter and web-search siblings via explicit exclusions. It never clarifies its relationship to the close sibling research_show_news, which is the one comparison an agent most needs.

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?

Explicit 'Use this when...' trigger plus a 'Do not use for...' exclusion list naming video chapters and exhaustive web search. It also tells the agent to resolve the ticker first and use an explicit anchor date. The only gap is that it does not route the agent between this tool and research_show_news.

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

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint and openWorldHint, but the description adds substantial behavior beyond them: 'Data result first', the presentation behavior of research_show_price with local replay and A/B selection, the rule not to add every metric by default, and the note that raw rows are widget-only until retrieved. This discloses the output/consumption model that annotations do not.

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 'Use this when' line and organized under clear labels (Selection, Presentation, Evidence). It is somewhat long and the dense Evidence paths paragraph (/candles/rows, /catalogue/datasets, /indicators/items) is more procedural than essential, keeping it below a 5.

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 values need no explanation, and annotations carry the safety profile; the description still covers routing, selection constraints, and presentation behavior comprehensively. Remaining density in the Evidence section prevents a top score but 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 all three parameters (including the nested window and the timeframe enum) are already documented in the schema. The Selection paragraph largely restates what the schema says ('end is exclusive', 'Reuse the requested candle interval', 'Resolve ambiguous dates first'), adding emphasis but little new semantic meaning. 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+resource ('opening an asset's native price chart and historical replay') with the scope of the action ('for a specified interval') and an example. It explicitly names the sibling it is not (research_read_series), so an agent can distinguish it 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?

Opens with 'Use this when...' and immediately provides exclusions: 'Do not use for adding a metric to an already-selected chart (research_read_series), automatic interpretation, or a live execution quote.' This gives explicit when-to-use, when-not-to-use, and the alternative tool by name.

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 non-read-only, idempotent, non-destructive; the description adds the async lifecycle (job_id polling via research_cohort_status, retry guidance), what must be retained (snapshot_id), and which catalogue paths to inspect. That is substantive behavioral context beyond the structured fields, and nothing contradicts the annotations.

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

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

Front-loads the trigger, then organizes the rest under Selection/Presentation/Evidence labels, so scanning is easy. The crypto-token example is illustrative but slightly padded; overall dense yet not bloated.

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 values need no explanation, and the description still supplies the preparation workflow, group-ID resolution rule, and evidence paths. Nothing needed to invoke 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 already 100% and the single enum parameter is fully documented there. The description restates the 1/7/30-day semantics and adds a reuse hint ('reuse an existing suitable snapshot rather than preparing on every refinement'), but the baseline for fully-covered schema is 3.

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 ('preparing cohort comparison history' / 'starting a group relationship comparison') and explicitly distinguishes its role from the sibling that consumes the result ('call research_compare_cohorts ... once ready'). An agent can tell it apart from research_cohort_status and research_compare_cohorts without opening a 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?

Gives explicit when-to-use ('starting a group relationship comparison without a usable prepared snapshot') and when-not ('not for taxonomy lookup alone or re-preparing a suitable snapshot for every filter change or replay frame'), and names the downstream alternative. This is textbook routing 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/non-destructive/openWorld=false, but the description adds substantial context beyond them: references are identity-isolated and expiring, an expired reference is NOT silently refreshed, no widget is produced, and arrays are bounded with next_offset. These traits materially affect how an agent should call and retry 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?

Front-loaded with the use case followed by clearly labeled paragraphs (Selection, Presentation, Evidence), so an agent can scan to the relevant section. Slightly long; the Presentation and Evidence paragraphs overlap mildly on the 'structured, no widget / not raw JSON' point, costing a bit of tightness.

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 return values, yet it still summarises object/array/scalar shapes to guide selection and paging. Usage, selection, presentation, expiration behavior and non-goals are all covered, leaving no material gap for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a usage pattern not spelled out per-field: inspect the root to discover child names when path is unknown, and page arrays via offset/limit following next_offset. That connective guidance exceeds a restatement of the schema fields.

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 states a specific action (retrieve exact values, catalogue IDs, source detail) on a specific resource (evidence already captured by another Research tool). It implicitly distinguishes itself from sibling operations by scoping to data 'already returned', which separates it from tools that fetch fresh series or market data. An agent can tell what this does without opening the 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?

The second sentence is an explicit negative boundary: 'Do not use for refreshing data, changing the selection, raw API access or opening another widget.' Combined with the positive trigger in the first sentence, this gives a clear when/when-not split. The Selection paragraph further tells the agent how to obtain the required evidence_id and path.

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 annotations covering the safety profile, the description still adds substantial behavioral context beyond them: null readings are not zero, partial flow subtotals are not complete totals, next_cursor signals incomplete upstream history, and OI lines must use nested matching-cycle venues rather than local sums. These directly affect how an agent interprets and trusts returned data.

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 usage trigger, then organized under Selection/Presentation/Evidence headers, so it is scannable despite its length. A few lines (e.g., 'Pattern events have no widget') are niche, but overall the sentences carry information rather than 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 an output schema present, the description need not explain return shape; instead it covers selection defaults, evidence reading, cursor semantics, and data caveats. An agent has everything needed to invoke and correctly interpret this tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter defaulting rules not obvious from the schema alone (indicators default to calculation=candles at 1h/4h/1d with exact variant ID; numeric snapshot/flow families default to alignment=candles; native is never a fallback). Some of this duplicates the schema text, capping it below 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 states a specific action (read one metric/study/source rows as a paginated series) and explicitly carves out what it is not for (research_interpret_range, invented indicators, replay frames). It is clear but does not differentiate itself from the many display siblings (research_show_funding, research_show_price), leaving the agent to infer the raw-series vs widget distinction.

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 an explicit 'use when' trigger, an explicit 'do not use' list naming a sibling alternative, and concrete routing rules ('Use facts.display_tool for its focused widget'). Follow-up preservation and cursor-following guidance make the conditions of use unambiguous.

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, and closed-world, so the safety profile is covered. The description adds meaningful context beyond that: it reuses captured source numbers and selection, published figures are not live quotes, and expired evidence requires an explicit new read. That last point is a real behavioral constraint not visible in annotations.

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

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

Front-loaded with the core action, then prerequisites, caveats, and exclusions in short clauses. Dense but nearly every sentence carries a distinct constraint; only the fragment 'A published edition and its chapters' reads as slightly 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?

An output schema exists so return values need not be explained, and the prerequisite chain, freshness caveat, and usage gating are all covered. Minor gap: no explicit statement of what happens if evidence_id is stale beyond 'requires an explicit new read', but the agent has enough 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 both parameters carry their own descriptions (chapter_id optionality/fallback, evidence_id format), so the schema does the heavy lifting. The description mentions 'selection' and 'captured source numbers' but adds no parameter-level syntax or format detail 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?

States a specific verb (display) and resource (published market update widget), and pins its role relative to research_briefing which supplies the evidence. The negation list ('not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation') clearly separates it from the many research_show_* 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?

Gives an explicit precondition (after research_briefing has returned the requested evidence), an explicit selection rule ('Use only when a visual helps answer the question'), and explicit exclusions of what this is not. This is about as complete as when-to-use guidance gets.

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, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavioral context: it reuses captured source numbers and selection, and expired evidence requires an explicit new read. It does not describe output format, but the output schema covers that.

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 prerequisite are front-loaded, and each sentence carries functional weight. The somewhat long negative list ("data fetch, calculation, navigation hub...") is the only slightly padded element, but it earns its place as exclusion 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?

For a render-a-widget tool with a full output schema, the description supplies the prerequisite chain, evidence lifecycle, and preserve-selection behavior an agent needs. Return values are covered by the output 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, but the description maps the otherwise opaque view enum values to human concepts (performance, benchmark-relative performance, contributions, relationships, qualified correlation) and notes data is reused. It still leaves x_metric/y_metric semantics to the schema, which already documents them.

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 (Display) and resource (focused group comparison widget), names the prerequisite tool that produces its input (research_compare_cohorts), and enumerates the five comparison views. This clearly distinguishes it from the read/compare siblings and the other research_show_* widgets.

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 when-to-use ("Use only when a visual helps answer the question") and when-not ("Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation"), plus the dependency on research_compare_cohorts. Nothing about routing is left to inference.

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 and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: it reuses captured source numbers and selection, and expired evidence requires an explicit new read, which tells the agent about state staleness and reuse semantics.

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 what it does and the precondition, then trims with the 'Not a...' clause. Four compact sentences, each earning space. Slightly 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?

With an output schema present, return values need no explanation, and annotations cover safety. The description supplies purpose, gating condition, reuse/staleness behavior and exclusions, making it complete enough to invoke correctly for this single-parameter widget.

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 evidence_id and its 64-hex format and 'do not supply chart numbers' note are already fully documented in the schema. The description's 'reuses captured source numbers and selection' reinforces this but adds no syntax or meaning beyond the schema, 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?

Names a specific verb (Display) and resource (asset directory widget) and states its scope: a compact list of resolved assets and their named category memberships. It also distinguishes itself from siblings by tying activation to research_discover having returned evidence, and clarifies what it is not (data fetch, calculation, navigation hub).

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 gates usage: 'after research_discover has returned the requested evidence' and 'Use only when a visual helps answer the question.' It states the prerequisite and an exclusion (not a data fetch or replacement for interpretation), though it does not name a specific alternative show_* sibling to route to instead.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavior beyond that: it reuses captured source numbers and selection, and expired evidence requires an explicit new read, which is a lifecycle constraint the annotations do not convey.

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 in the first clause, and each sentence carries distinct information (semantics, when-to-use, exclusions, lifecycle). The list of negatives is slightly dense but still bounded and useful.

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 values need no explanation. Between the purpose, prerequisite, domain semantics (positive/negative rate meaning), exclusions, and evidence-expiry behavior, an agent has everything required to invoke this 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 coverage is 100% and the single evidence_id parameter is fully documented in the schema, including its format and provenance. The description only echoes the reuse-of-captured-values idea without adding syntax or format detail, 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?

The description gives a specific verb and resource ('Display a focused funding chart widget') scoped to funding history, and it explicitly distinguishes itself from data-fetch/calculation/navigation siblings. An agent can immediately tell this is a rendering-only tool versus research_read_series or research_read_evidence.

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 states the prerequisite ('after research_read_series has returned the requested evidence'), the condition for use ('Use only when a visual helps answer the question'), and negative guidance ('Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation'). It also flags the expiry case requiring an explicit new read.

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/non-destructive/closed-world, so the description is free to add the genuinely useful behavior: it reuses captured source numbers and selection rather than recomputing, and expired evidence requires an explicit new read. That lifecycle detail is not derivable from the annotations or 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 is front-loaded in the first clause, followed by content scope, usage gate, exclusions, and lifecycle. Slightly clause-dense in the middle, but every sentence carries routing or behavioral information and none is 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 an output schema present, return values need no explanation. The description supplies the prerequisite chain, the usage gate, the exclusions, and the evidence-expiry rule, which is essentially everything an agent needs. Only the distinction from adjacent show_* siblings is 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?

There is a single parameter with 100% schema description coverage, which itself explains that evidence_id is the exact evidence.id and that the server retrieves original values. The description reinforces re-use ('do not supply chart numbers') but adds no new syntax or format information, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Display a focused liquidation chart widget' with long/short liquidation flows and separate direction labels. It is clearly a render tool, but it does not explicitly distinguish itself from close siblings like research_show_liquidity or research_show_funding, leaving the agent to infer the difference.

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 precondition ('after research_read_series has returned the requested evidence'), an explicit gating condition ('Use only when a visual helps answer the question'), and negative routing ('Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation'). This is as complete as usage guidance gets.

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 non-destructive behavior, so the safety profile is covered. The description adds real context beyond them: it reuses "captured source numbers and selection" rather than recomputing, expired evidence requires an explicit new read, and depth/spread use separate scales to avoid a misleading combined axis.

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 core purpose and prerequisite before the caveats, and every sentence contributes routing, lifetime, or rendering information. The "Not a data fetch, calculation, navigation hub..." enumeration is a touch list-like, but it earns its place as exclusion 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?

For a read-only display tool with a full output schema and 100% parameter coverage, this is complete: prerequisite, trigger condition, exclusions, render semantics, and evidence-lifetime behavior are all present. Nothing an agent needs to invoke 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 coverage is 100% and the single evidence_id parameter is fully documented in the schema, so baseline is 3. The description adds lifespan semantics ("expired evidence requires an explicit new read" and reuse of the captured selection), but does not extend the format or sourcing detail beyond what the schema already states.

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 ("Display a focused order-book liquidity widget") and pins it to a concrete payload ("bid/ask depth or quoted spread"). It clearly distinguishes itself from sibling show_* tools and ties itself to research_read_series, so an agent can place it precisely without opening the 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?

Gives an explicit precondition ("after research_read_series has returned the requested evidence"), a positive trigger ("only when a visual helps answer the question"), and negative exclusions ("Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation"). This is unusually complete routing 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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: it reuses captured source numbers and selection rather than recomputing, expired evidence requires an explicit new read, and probabilities are not calibrated confidence. It does not describe output structure, but an output schema exists.

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 action and its precondition, and every sentence carries a distinct constraint (what it shows, what it is not, when to use, evidence reuse/expiry). Dense but not padded; a slightly tighter grouping of the negative clauses would read better.

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 single-parameter visualization tool with full schema coverage, an output schema and complete safety annotations, the description covers sequencing, preconditions, evidence lifecycle and interpretation caveats. Nothing needed 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 coverage is 100% and the schema already explains evidence_id, its hash pattern and the 'do not supply chart numbers' rule, so baseline is 3. The description adds lifecycle semantics the schema lacks — the id resolves against reused captured values, and an expired id forces a new read.

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 ('Display a focused market regime and volatility widget') and precisely places it relative to the sibling that produces its input ('after research_market_context has returned the requested evidence'). An agent can distinguish it from research_market_context, research_show_markets and the other show_* tools without opening a 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?

Explicit when-to-use ('Use only when a visual helps answer the question') and explicit when-not ('Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation'), plus the precondition that market_context evidence already exists. This is the strongest form of routing 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 cover the safe-read profile (readOnly, idempotent, non-destructive, closed-world), so the description adds genuinely non-obvious behavior: it reuses captured source numbers and selection rather than re-fetching, and expired evidence forces a new read. The note that Signal Book rank measures analytical attention rather than expected returns guards against a likely output misreading. It stops short of describing widget interaction, which keeps it out of the top band.

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 precondition are front-loaded, and each sentence carries a distinct constraint (trigger, exclusions, rank caveat, expiration). It is dense with short clauses rather than wasted words, though the run-on exclusion list slightly hurts scannability.

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

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

With an output schema present, return-value description is unnecessary, and the annotations plus the reuse/expiration notes leave nothing an agent needs in order to invoke this correctly. The prerequisite data step and the mental model of the widget are both covered.

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 single evidence_id parameter, its hash pattern, and its 'do not supply chart numbers' constraint are all documented in the schema. The description reinforces the reuse semantics but adds no new syntax or format detail beyond what the schema provides, which is the expected baseline here.

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 ('Display a focused market shortlist widget') and anchors it to the data-producing sibling ('after research_markets has returned the requested evidence'). This distinguishes it from research_markets (a data fetch) and from the other research_show_* widgets, which render different content types.

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 precondition (evidence must already exist), a conditional trigger ('Use only when a visual helps answer the question'), explicit exclusions ('Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation'), and an edge case ('expired evidence requires an explicit new read'). This is close to ideal routing 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, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful beyond-schema context: it reuses captured source numbers/selection, expired evidence requires an explicit new read, and topic mention counts differ from article counts.

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 purpose before constraints, and every sentence carries useful information. The negative-list sentence ('Not a data fetch, calculation, navigation hub or...') is a touch dense but still earns its place by preventing misuse.

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

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

With an output schema present, return values need not be described, and the definition covers prerequisites, usage gating, evidence lifetime, and behavioral reuse semantics. Nothing an agent needs to invoke 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 coverage is 100%, so the schema already documents evidence_id thoroughly (pattern, origin). The description adds a bit of meaning by tying the id to research_news_context output and clarifying that source numbers/selection are reused rather than supplied, which slightly exceeds the 3 baseline.

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 ('Display a focused news timeline widget') and explicitly frames it as a display layer that acts after research_news_context returns evidence. An agent can distinguish it from the sibling data-fetch tool 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?

Provides an explicit precondition ('after research_news_context has returned the requested evidence') and a clear gating rule ('Use only when a visual helps answer the question'). It also names anti-patterns (not a data fetch, calculation, navigation hub, or replacement for interpretation), which is strong when/when-not 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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: it reuses captured source numbers and selection rather than fetching data, and expired evidence forces a fresh read. That reuse/idempotency nuance goes beyond the structured hints.

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 prerequisite are front-loaded in the first sentence, and the exclusion list helps routing. The negative enumeration ('not a data fetch, calculation, navigation hub or replacement...') is slightly verbose but earns its place as disambiguation among many show_* siblings.

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 format need not be explained. The description covers the prerequisite, the reuse semantics, the freshness constraint, and the routing boundary against siblings and the assistant's own interpretation, which is complete for a single-param render tool.

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

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

With a single parameter at 100% schema coverage, the schema already defines evidence_id, its pattern, and the instruction not to supply chart numbers. The description's 'reuses captured source numbers and selection' largely restates that, so baseline 3 is appropriate given the schema does the heavy lifting.

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 ('Display a focused open interest chart widget') and distinguishes itself from siblings by explicitly ruling out data fetch, calculation, and navigation roles. The scope ('USD open interest by reported venue... not a locally invented aggregate') further sharpens what the tool renders versus what it computes.

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?

Names the prerequisite sibling ('after research_read_series has returned the requested evidence') and the condition that gates use ('Use only when a visual helps answer the question'). It also handles the stale-evidence case ('expired evidence requires an explicit new read'), leaving little to inference.

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, destructiveHint=false), but the description adds meaningful behavior beyond them: it reuses captured source numbers and selection, does not treat account ratios as capital flows, and requires an explicit new read when evidence has expired.

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 the description is appropriately sized for a focused display tool. A few clauses, especially the list of things it is not, could be tightened, but each sentence contributes relevant 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 a single required parameter, full schema description coverage, an output schema, and annotations covering safety, the description provides all the missing context: when to use the tool, its dependency on prior evidence, visual-only behavior, and evidence-expiry handling.

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 input schema already defines the single evidence_id parameter, its format, and that the server retrieves original values and selection. The description adds useful contextual semantics: the evidence comes from a prior research_read_series call, and expired evidence requires a new read.

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: display a focused positioning chart widget. It also scopes what the widget shows (long/short account ratios or tracked-position observations) and explicitly distinguishes the tool from data-fetching, calculation, navigation, and interpretation 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 prerequisite (after research_read_series has returned evidence), a positive usage condition (use only when a visual helps answer the question), and explicit exclusions (not a data fetch, calculation, navigation hub, or replacement for interpretation). It also states when re-reading is required for expired evidence.

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/non-destructive safety, but the description adds genuinely useful behavior: it consumes captured source numbers and selection rather than chart values, and expired evidence requires an explicit new read. This goes beyond the structured fields, though it doesn't describe widget interaction or failure 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?

Front-loaded with the core action and dependency, then conditions and exclusions. Dense but each clause earns its place; slightly long with several short fragments but no padding.

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

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

With an output schema present, return values need not be explained, and the prerequisite, reuse semantics and expiry rule are all covered. An agent has enough to call it correctly; only minor interaction details 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 coverage is 100% so baseline is 3, but the description adds provenance semantics not in the schema: the widget reuses captured source numbers and selection, and 'do not supply chart numbers' clarifies what must NOT be passed. This meaningfully complements the evidence_id pattern constraint.

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: 'Display a focused price chart widget' with candlestick history, 3x replay and A/B selection. It also names its prerequisite (research_open_ticker) and contrasts itself against the show_* siblings via the explicit exclusions, though it never names an alternative tool directly.

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 only when a visual helps answer the question' gives a positive condition, and 'Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation' gives explicit when-not boundaries. The prerequisite sequencing from research_open_ticker is stated.

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

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

Annotations already establish the safe read-only, idempotent, closed-world profile, so the bar is lower. The description still adds non-obvious behavior: it reuses captured source numbers and selection, and expired evidence requires an explicit new read, which is genuinely useful state/lifetime information beyond the annotations.

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

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

Front-loaded with the action and prerequisite, then scope, exclusions, and usage caveats in a compact block. Dense but each sentence carries a distinct constraint; minor overlap with the schema on the 'do not supply chart numbers' point.

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 values need not be described, and annotations carry the safety profile. The description supplies the missing pieces an agent needs: the upstream prerequisite, the single-indicator scope, the exclusion of retired regimes/pattern events, and evidence-expiry behavior.

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

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

With one parameter at 100% schema coverage, the schema already documents that evidence_id is the exact evidence.id and that the server retrieves values. The description reinforces the same constraints ('reuses captured source numbers', 'expired evidence requires an explicit new read') but adds little syntax or format meaning beyond the schema, 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?

States a specific verb and resource ('Display a focused technical study widget') and pins the prerequisite action ('after research_read_series has returned the requested evidence'). It explicitly distinguishes itself from sibling behaviors by declaring what it is not: a data fetch, calculation, navigation hub, or replacement for interpretation.

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 when-to-use condition ('Use only when a visual helps answer the question') plus multiple when-not-to-use exclusions ('Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation'). The dependency on research_read_series as the upstream alternative is spelled out.

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 and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: it reuses captured source numbers/selection rather than fresh input, and expired evidence requires an explicit new read. That expiry/reuse rule is not derivable from the annotations.

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

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

Front-loaded with the action and its precondition, and every sentence carries load. The negative list ('data fetch, calculation, navigation hub...') is slightly enumerative but earns its place by preventing misuse of a render-only tool.

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

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

With an output schema present, return values need not be described, and annotations cover safety. A single required parameter at 100% coverage plus explicit precondition and expiry handling make the definition complete; minor gap is no note on what happens if the widget cannot render.

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 schema already explains that evidence_id is the exact evidence.id from the matching data tool with a 64-hex pattern. The description reinforces this by telling the agent not to supply chart numbers and that values are reused, adding modest meaning beyond the schema. Baseline would be 3; the reinforcement earns a 4.

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 ('Display a focused video timeline widget') and pins the scope to ticker-matched published chapters with watch links and dates. It distinguishes itself from the fetch sibling by positioning it as the render step after research_ticker_videos returns evidence.

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 the trigger condition ('after research_ticker_videos has returned the requested evidence') and the judgment call ('Use only when a visual helps answer the question'), plus negative routing ('Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation'). Nothing is left to inference.

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 establish read-only, idempotent, non-destructive, closed-world behavior, so the description needn't restate safety. It adds genuinely new behavioral context: 'end is exclusive', publication time must be kept distinct from the market period discussed, and returned sections must be inspected for titles/basis/timestamps before describing an item. That is real disclosure beyond the annotation layer.

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 triggering condition, then organized under Selection/Presentation/Evidence labels so each block is scannable. The Presentation and Evidence lines are somewhat prescriptive but each carries a distinct instruction, so little is wasted; slightly longer than the minimum needed.

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 values need no explanation, and the description instead covers the tricky parts: exclusive end, ticker resolution via research_discover, and not inferring relevance from publication date alone. Combined with full schema coverage and rich annotations, an agent has enough to call it 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 both parameters are fully documented in the schema, including the exclusive-end and timezone-qualified ISO format. The description reinforces end-exclusivity and the publication-time vs market-period distinction, but adds no syntax or format detail the schema lacks, so it sits at the baseline.

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 ('a ticker's published video chapters on a selected timeline'), and the negative clauses carve out the scope from market-wide or general web video search. It does not name the closest sibling (research_show_videos) directly, so an agent must infer the division of labor from scope language rather than an explicit pointer.

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 when-to-use ('the user wants a ticker's published video chapters') plus explicit when-not conditions (market-wide videos, web video search, causal proof). It also prescribes preserving ticker/date context on follow-ups. It stops short of routing the agent to a named alternative tool, which is what a 5 would require.

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