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 cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real context the annotations do not: terminal states (ready/failed/unavailable/expired), the retry_after_seconds backoff contract, and the important fact that research_prepare_cohorts does not return a job_id. It does not mention rate limits or how long results persist, 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?

Structure is strong: the precondition is front-loaded, then Selection/Presentation/Evidence sections each carry distinct guidance. A few clauses are dense and slightly awkward ('Do not imply a preparation default answers the requested comparison'), which costs it a point, but there is little true 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 one required parameter, an output schema present, and rich annotations, the description covers everything an agent needs: where the job_id comes from, when not to call, when to stop polling, and which tool to call next with the returned snapshot_id.

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 job_id property already documents the 64-hex format and the snapshot_id distinction. The description reinforces this with 'Pass that exact job_id' and sources the value ('from an earlier response'), adding marginal but useful invocation guidance rather than new syntax.

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 makes clear this tool polls/reports on an existing cohort preparation job ('Stop polling on ready, failed, unavailable or expired results') and explicitly separates it from research_prepare_cohorts, which starts one. The verb ('check status') is implied by the title and the polling language rather than stated outright, so it is slightly indirect, but the resource and scope are unambiguous.

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

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

It names the precondition (job_id already known from an earlier response), three explicit exclusions ('starting a cohort preparation, refreshing a ready comparison, or rapid/unbounded polling'), and the sibling to use for the follow-up step (research_compare_cohorts). Stop conditions and retry_after_seconds handling are also specified.

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 behavior. The description adds substantial operational context: exact snapshot_id and catalogue group IDs required, benchmark/overlap/filters must be preserved, correlation requires an explicit asset pair and supported window, facts.summary carries line points and membership counts, and API analytics are authoritative while endpoint differences are not correlations.

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?

Organized into clear sections (Use/Do not use, Selection, Presentation, Evidence) with the primary use case front-loaded. The presentation guidance is dense and slightly verbose, but it earns its place for a complex analytical tool. Minor trimming of presentation details would improve conciseness without losing critical information.

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

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

Given the output schema exists, the description needn't explain return values, yet it usefully mentions facts.summary contents and evidence sections. It covers selection constraints, correlation requirements, shared-membership treatment, and interpretation guardrails sufficiently for a tool with complex nested parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds procedural meaning beyond the schema: use the returned snapshot_id, exact catalogue group IDs, second-based bounds inside the prepared history, preserve unchanged selection fields, and request correlation with an explicit asset pair. It does not detail every nested field, but the added selection guidance is actionable.

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 specific analytical tasks (group performance, relative returns, contributions, metric relationships, qualified pair correlation) and explicitly scopes the tool to a pinned history. The do-not-use list (inventing sector membership, re-preparing history, causal claims, portfolio advice) further distinguishes it from research_prepare_cohorts and other 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?

Provides explicit when-to-use and when-not-to-use guidance, names research_prepare_cohorts/status as the source for snapshot_id, instructs to refine existing comparisons while preserving unchanged fields, and gives selection rules for time bounds and correlation pairs. Nothing critical 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, 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?

Beyond the annotations (readOnly, idempotent, non-destructive), it discloses that this performs a fresh history read rather than reciting the frozen A/B table, that findings are deterministic rather than LLM prose, and names the governing fields (range_end_exclusive, evidence_read_at, /metric_checks). These are non-obvious behavioral traits.

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 and organized under Selection/Presentation/Evidence labels, with no filler sentences. It is dense and jargon-heavy, which costs some readability, but every section carries operative 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?

With an output schema present, return values need not be described, and the description still covers selection construction, presentation style, and evidence provenance. 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 description coverage is 100% and the nested schema already documents a_time, b_time, alignment, timeframe matching, and study IDs in detail. The Selection paragraph largely restates those structured definitions rather than adding new cross-field semantics, 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 opening line states a specific verb (interpret/explain) and resource (a selected A/B chart range across its enabled metrics), which is precise. It then distinguishes itself from siblings by excluding whole-market briefings, predictions, endpoint-only narration, and replaying the prior chart read.

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

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

The description gives an explicit trigger condition ('when the user asks what a specific A/B chart selection means') and an explicit when-not list mapped to closely related capabilities. This routes the agent away from research_briefing and evidence/recitation variants without ambiguity.

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 readOnlyHint=false, idempotent=true, destructive=false; the description adds the details that actually drive agent behaviour — the call blocks briefly and re-issues the same request, no job id is surfaced, progress is not an answer, and the snapshot_id must be retained. This is consistent with idempotentHint=true and with a non-readOnly call that materialises server-side state.

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 and organised under Selection/Presentation/Evidence labels, so an agent can scan it. It is dense and slightly repetitive around progress/retry ('Progress is not an answer' followed by 'If history is still warming, retry'), but nearly every clause carries operational weight.

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 spelled out, yet the description still tells the agent what matters in the response (facts.summary, per-group return_pct/relative_pp/as_of, charted/member counts) and when not to drill into /initial/catalogue, /initial/selection or /initial/history_range. For a single-enum-parameter preparation tool with annotations and an output schema, 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?

With one parameter at 100% schema coverage and an enum already documenting 1/7/30 with a default, the description's 'days selects 1, 7 or 30 days of retained history' largely restates the schema. The added nuance — reuse a suitable snapshot instead of re-preparing on each refinement — is about behaviour rather than the parameter, and the mention of resolving group IDs from the catalogue refers to no parameter in this schema, so it does not sharpen parameter meaning.

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 action (prepare retained cohort-comparison history) and grounds it with a concrete example (DeFi vs AI tokens over seven days), which removes ambiguity about what the tool produces. It distinguishes itself functionally from siblings by rejecting taxonomy lookup and progress-handle waiting, though it never names research_discover, research_cohort_status, or research_compare_cohorts explicitly.

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 ('starting a group relationship comparison without a usable prepared snapshot'), explicit when-not (taxonomy lookup alone, waiting on a progress handle, re-preparing per filter change or replay frame), plus a retry protocol when history is still warming. The reuse instruction ('retain snapshot_id', answer from facts.summary rather than re-running) closes the loop on follow-up behaviour.

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 cover safety (readOnly/idempotent/non-destructive), and the description adds genuinely new traits: references are identity-isolated and expiring, and an expired reference is not silently refreshed. It also discloses presentation behavior (structured evidence, no widget) which 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?

Front-loaded with the trigger sentence, then clearly labeled Selection/Presentation/Evidence blocks that each earn their place. It is somewhat dense and longer than strictly necessary, with mild overlap between the intro and the Selection block, 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?

An output schema exists so return shapes need not be spelled out, yet the description still characterizes object/array/scalar evidence results and the expiry model — covering everything an agent needs to call this correctly and interpret it, including the failure mode of stale references.

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 still adds strategy-level meaning — that path targets a section rather than root enumeration, that limit/offset page already-captured arrays rather than fetching upstream history, and that next_offset should be followed. It stops short of adding format examples beyond what the schema already supplies.

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 precise verb+resource: retrieving one specific section or value from evidence already returned by another Research tool. It also names the boundary against near-siblings implicitly (refreshing data, raw API access, other widgets), so an agent can distinguish it without reading 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?

Explicit 'use this when' plus a detailed 'do not use for' list covering refresh, selection changes, enumeration, preview-of-facts, and widget opening. It also gives procedural guidance (use evidence.id + JSON-pointer, request bounded arrays, follow next_offset) instead of leaving it 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?

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 readOnlyHint, idempotentHint, and non-destructive behavior, but the description adds meaningful context beyond them: published figures are not current quotes, captured source numbers and selection are reused, and expired evidence requires an explicit new read. It does not need to explain return values because 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 front-loaded with the core action and is reasonably tight. A few clauses are dense, and the fragment 'A published edition and its chapters' is slightly awkward, but every sentence contributes useful 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 widget with full schema coverage and an output schema, the description covers the key dependency, visual-use condition, data staleness caveat, and exclusions from broader interpretation or data-fetching roles. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so both evidence_id and chapter_id are already documented in the schema. The description adds context about evidence reuse and expiry, but it does not directly elaborate on chapter selection or parameter syntax beyond what the schema provides.

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

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

The description uses a specific verb ('Display') and resource ('published market update widget') and clarifies that it shows a published edition and chapters. It also distinguishes the tool from data-fetching, calculation, navigation, and interpretation tools, so an agent can identify its role without checking 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 states the prerequisite ('after evidence from research_briefing is available') and a clear condition for use ('Use only when a visual helps answer the question'). It also lists explicit exclusions: 'Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation.'

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, non-destructive), so the bar is lower; the description nonetheless adds real behavior: one pinned comparison at a time, reuse of captured source numbers and selection, and that expired evidence forces a fresh read. It does not state what happens to a previously pinned comparison when re-invoked, which keeps it at 4.

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, then the scoping and exclusion rules. A few clauses are dense, stacked negatives ("not a data fetch, calculation, navigation hub or replacement..."), but each sentence carries a distinct constraint rather than 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 no explanation, and the description covers the critical preconditions, expiry behavior, and non-purposes for a 4-param widget tool. The only thin spot is behavior on repeat invocation with a different view for the same evidence_id.

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 enum values and x_metric/y_metric semantics are already documented in the schema; the description's view enumeration largely restates the enum. The one added nuance is that groups and selection are preserved from the source rather than re-specified, which is worth noting but doesn't exceed the baseline by much.

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 group comparison widget") and immediately scopes it to a single pinned comparison with enumerated views. Explicitly separates itself from data-fetch/calculation/navigation siblings, so an agent can distinguish it from research_compare_cohorts or research_read_evidence 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 both sides of the decision: preconditions (evidence from research_prepare_cohorts / research_compare_cohorts, or a ready preparation), an affirmative test ("Use only when a visual helps answer the question"), and explicit exclusions (not a data fetch, calculation, navigation hub, or replacement for interpretation). The expiry rule ("expired evidence requires an explicit new read") names the fallback action.

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 genuinely new state behavior: the widget reuses captured source numbers and selection, and expired evidence requires an explicit new read — a failure mode the annotations do not express. It stops short of describing any rendering error path beyond expiry.

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, then prerequisite, then misuse boundary, then lifecycle caveat — a sensible order with no filler. The negation list and the expiry sentence are both doing work, though the prose is denser than strictly necessary.

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; what remains — prerequisite, decide-when-to-use rule, anti-patterns, and stale-evidence handling — is all stated. Nothing an agent needs to invoke this single-parameter widget 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% (pattern, provenance, 'do not supply chart numbers' are all in the schema), so the baseline is 3. The description earns above that by tying the argument's provenance to research_discover and explaining the server-side reuse of original values, which clarifies why the agent cannot fabricate the id.

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 asset directory widget') and immediately scopes it as a visual companion to research_discover output rather than a data source. This distinguishes it cleanly from data-fetch siblings like research_read_evidence and from 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?

Explicit gating conditions: evidence must already exist from research_discover, and 'Use only when a visual helps answer the question.' It also names four things it is not (data fetch, calculation, navigation hub, replacement for interpretation), which is exactly the alternative-routing an agent needs to avoid substituting it for a computation 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 cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real behavior: it reuses captured source numbers and selection, reports history in the supplied units, and defines the sign convention for funding rates. The staleness rule (expired evidence needs a fresh read) is genuinely useful operational detail 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 the prerequisite, and the sign-convention sentence earns its place by preventing misreading of returns. Slightly padded by the four-item negation clause ("data fetch, calculation, navigation hub..."), which 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?

With an output schema present, the return values need no explanation, and annotations carry the safety profile. The description still supplies the prerequisite, staleness handling, unit and sign semantics, and the anti-use cases — 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?

Schema coverage is 100% and the evidence_id description already covers the pattern and sourcing, so baseline is 3. The description adds the specific originating tool (research_read_series) and restates that source numbers/selection are reused rather than supplied, which sharpens how to obtain the ID.

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 funding chart widget") plus the prerequisite evidence source (research_read_series), and explicitly negates adjacent roles ("Not a data fetch, calculation, navigation hub"). An agent can separate it from research_read_series and the other research_show_* siblings 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 an explicit gate ("Use only when a visual helps answer the question") and an explicit exclusion list ("Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation"). It also names the required prior step (evidence from research_read_series) and the recovery path when evidence expires ("requires 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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it is presentation-only, reuses captured source numbers and selection rather than re-fetching, and becomes stale once evidence expires, requiring a new read. It does not describe rendering failure modes, but the output schema covers the return shape.

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

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

Three front-loaded sentences with no filler: purpose first, then usage constraints, then staleness behavior. The negation list ('not a data fetch, calculation, navigation hub...') is dense but each item earns its place by ruling out a plausible misuse. Slightly overpacked, but well structured.

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

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

With an output schema, full annotation coverage, and a single fully described parameter, the description covers everything an agent needs to select and invoke the tool correctly, including the prerequisite evidence and the expired-evidence case. The only small gap is what the widget contains beyond direction labels, which is minor against the output schema.

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 evidence_id description already explains the hash format and that the server retrieves original values and selection. The description adds only that it 'Reuses captured source numbers and selection', which reinforces but does not extend the schema's parameter contract. Baseline 3 is appropriate when 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?

Opens with a specific verb and resource ('Display a focused liquidation chart widget') and scopes the content ('Long and short liquidation flows over the selected period, with separate direction labels'). It also distinguishes itself from the data layer by tying itself to prior evidence from research_read_series, so an agent can separate it from sibling show_* tools without reading schemas.

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

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

Explicitly states when to use it ('Use only when a visual helps answer the question') and when not to ('Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation'), and names the alternative path ('expired evidence requires an explicit new read'). That is a complete routing rule, not an implied one.

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, yet the description still adds non-obvious behavior: values are captured (not recomputed), the widget reuses the prior selection, expired evidence requires an explicit re-read, and depth vs spread are rendered on separate scales rather than a combined axis. Those are real operational facts an agent could not infer 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 purpose, then prerequisite, then exclusions. Six short sentences, nearly all load-bearing; the separate-scales remark is slightly editorial but still prevents a real misreading of the output.

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

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

Single-parameter tool with rich annotations and an output schema, so the description needn't explain return shape. It covers the prerequisite, the display semantics, the evidence-expiry edge case, and the boundary against data-fetch siblings — nothing an agent needs in order 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 evidence_id description already explains the 64-hex id source, so the baseline is 3. The description adds lifecycle meaning the schema omits: evidence expires, and supplying chart numbers is not accepted ('reuses captured source numbers and selection'). Useful, but limited to one parameter.

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 (order-book liquidity widget), then narrows it to the two things rendered: bid/ask depth or quoted spread. That distinguishes it from the other display siblings (research_show_price, research_show_open_interest, research_show_volume-style tools) without needing to open 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?

Explicit prerequisite ('after evidence from research_read_series is available'), explicit selection rule ('Use only when a visual helps answer the question'), and explicit exclusions ('Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation'). The alternative path for raw numbers is effectively named.

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 cover safety (readOnly, idempotent, non-destructive), and the description adds behavior they cannot: it reuses captured source numbers and selection rather than recalculating, expired evidence requires an explicit new read, and displayed probabilities are not calibrated confidence. Those are the details an agent needs to avoid misusing the output.

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 displays and its dependency, and every sentence carries a constraint or caveat. Slightly dense with a listy negative clause ('not a data fetch, calculation, navigation hub'), but nothing is 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?

Output schema and annotations already carry return shape and safety profile; the description supplies the remaining agent-critical context: prerequisite evidence, expiry/re-read behavior, 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 single evidence_id parameter is already documented as the exact evidence.id from the matching data tool with a 64-hex pattern. The description reinforces reuse and expiry but adds no syntax or sourcing detail 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 (Display) and resource (market regime and volatility widget) and names the sibling data tool whose evidence it depends on, research_market_context. An agent can distinguish it from the raw data tool 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 trigger ('after evidence from research_market_context is available'), an explicit conditional ('Use only when a visual helps answer the question'), and explicit exclusions ('Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation'). This is about as complete as a when/when-not statement 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 read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: it reuses captured source numbers and selection, and expired evidence requires an explicit new read, which tells the agent about failure/reuse semantics not present in 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?

The core purpose is front-loaded and the prerequisite framing is efficient, but the four-item negative list ("not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation") is a laundry list that could be compressed. For a single-parameter display widget the description is somewhat long-winded.

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 covers the prerequisite evidence read, the reuse/expiry behavior, and the interpretation caveat about Signal Book rank. The main residual gap is error behavior for an invalid or mismatched evidence_id.

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 already documents the exact-id requirement, the 64-hex pattern, and the instruction not to supply chart numbers. The description's note about reusing captured values largely restates 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?

The description states a specific verb and resource ("Display a focused market shortlist widget") and adds what the widget contains (ranked assets with current reported prices). It distinguishes itself from the data-fetch sibling research_markets, but does not differentiate itself from other show_* siblings such as research_show_price or research_show_positioning.

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 condition ("Use only when a visual helps answer the question") and explicit exclusions ("Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation"), plus the prerequisite that evidence from research_markets must exist. It stops short of naming which sibling to call instead when a visual is not warranted.

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, non-destructive), so the description earns credit for adding non-obvious traits: it reuses captured source numbers/selection rather than recomputing, and expired evidence requires an explicit new read. The 'topic mention counts are not article counts' caveat is a useful semantic warning. Slightly short of 5 because it doesn't say what the widget renders beyond the dated window.

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 in the first sentence, and every clause carries guidance. The four-item exclusion list ('data fetch, calculation, navigation hub or replacement...') is slightly verbose but each item adds a distinct boundary.

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 needn't be spelled out, and the description supplies the prerequisite, the visual-only constraint, and evidence-expiry behavior. It is complete enough to call the tool correctly; only the rendered output's shape is left implicit to the output schema.

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 fully documents evidence_id including the exact-id format and pattern. The description adds lifecycle context ('reuses captured source numbers and selection; expired evidence requires an explicit new read') but does not elaborate on the parameter itself, 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 ('Display') and resource ('a focused news timeline widget') and names the exact prerequisite sibling, research_news_context. An agent can distinguish this presentation tool from the data-fetch siblings 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?

'Use only when a visual helps answer the question' gives explicit when-to-use, while 'Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation' gives explicit when-not-to-use. It names the alternative (research_news_context) as the evidence source, routing the agent clearly.

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 a safe, idempotent, closed read, so the description correctly spends its words elsewhere: it reuses captured values and selection rather than recalculating, and it discloses the evidence-expiry behavior that forces a re-read. It does not describe what the widget returns, 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?

Front-loaded with the action and data scope, with prerequisites and exclusions after. The run of negatives ('not a data fetch, calculation, navigation hub...') is slightly listy but each clause forestalls a real misrouting.

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

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

For a one-parameter, annotated, output-schema-backed widget, the description supplies everything an agent needs: the dependency on a prior read, the visual-only trigger, the reused-selection behavior, and the expiry rule.

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's origin and 64-hex format are already documented; the description still adds real meaning by tying it to a prior research_read_series call, stating that captured numbers and selection are reused server-side, and flagging that evidence can expire.

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 concrete verb and resource ('Display a focused open interest chart widget') and pins the content precisely ('USD open interest by reported venue', separate lines, not an invented aggregate), which separates it from a data-fetch sibling. It does not name a specific alternative show_* tool, but the open-interest scope is unmistakable.

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 prerequisite ('after evidence from research_read_series is available'), an explicit use condition ('Use only when a visual helps answer the question'), and explicit exclusions ('not a data fetch, calculation, navigation hub'). It also covers the stale case: 'expired evidence requires 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?

Beyond the read-only/idempotent annotations, the description explains that the widget reuses captured source numbers and selection, does not fetch or calculate new data, and requires a new read once evidence expires. These are meaningful behavioral constraints an agent would otherwise have to discover by trial.

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 action and prerequisite, and every sentence contributes either a usage condition or a behavioral boundary. It is slightly verbose with stacked negations and could be tightened, but it is not padded.

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

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

Given the single required parameter, full schema coverage, annotations, and an output schema, the description supplies everything else the agent needs: when to use it, what it is not, prerequisite evidence, and expiry behavior. No essential context is missing 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?

With 100% schema description coverage, the schema already defines the required evidence_id precisely. The description adds useful context about the source tool and evidence expiry, but mostly reinforces what the schema states rather than adding new parameter-level syntax or format details.

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: 'Display a focused positioning chart widget', and names the content domain (long/short account ratios or tracked-position observations). It also explicitly distinguishes herself from sibling tools by stating it is 'Not a data fetch, calculation, navigation hub or replacement for the assistant's 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?

It states the exact prerequisite ('after evidence from research_read_series is available') and the selection condition ('Use only when a visual helps answer the question'). It also names exclusions and the recovery path for expired evidence ('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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: it reuses captured source numbers and the prior selection rather than re-fetching, and expired evidence forces an explicit new read. It does not explain failure behavior for a malformed or unknown evidence_id, which keeps it below 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 the primary action and precondition, then constraints. Dense but nearly every clause carries information; the 'Not a data fetch, calculation, navigation hub' enumeration is slightly listy and the '3× replay / A/B selection' terms arrive without definition.

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?

Output schema exists, so return shape needn't be described; annotations cover safety. For a single-parameter rendering tool, the description covers prerequisite, lifetime, reuse semantics, and appropriateness criterion — everything an agent needs to decide and invoke 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 property description already specifies the 64-hex evidence.id format and 'do not supply chart numbers'. The description nonetheless reinforces the semantics — the ID carries the original values and selection, and stale IDs expire — which is meaning the schema alone does not convey.

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 artifact ('Display a focused price chart widget') and immediately scopes it against siblings by declaring it is 'Not a data fetch, calculation, navigation hub' — a direct contrast with research_read_series, research_interpret_range, and the show_* family. It also names the prerequisite tool research_open_ticker, so an agent can place it precisely in a workflow.

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'), explicit when-not (not a data fetch, calculation, navigation hub, or replacement for the assistant's interpretation), and a stated precondition (evidence from research_open_ticker must exist). The expired-evidence rule tells the agent what to do when the guard fails.

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, and the description adds real behavior beyond them: the widget reuses the captured source numbers and selection rather than recomputing, expired evidence forces a fresh read, and retired regimes and pattern events are deliberately not exposed. This tells the agent both what the widget does and what it will refuse to show.

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 routing or behavioral information. The cluster of negations ("not a data fetch, calculation, navigation hub or replacement...") is slightly sprawling but each negation heads off a plausible misselection.

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

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

For a one-parameter, read-only widget with an output schema and full annotation coverage, the description supplies the prerequisite, the scope limits, the staleness rule, and the intended non-use cases. Nothing an agent needs in order 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 single parameter is fully documented, so the baseline is 3; the description adds genuine meaning by stressing that the call reuses captured values and that chart numbers must not be supplied. It does not add format details for evidence_id (the 64-hex pattern lives only in the schema), 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?

Names a specific verb and artifact (display a focused technical study widget) and narrows the scope to one requested candle-calculated indicator with exact identity/interval/period, or an explicitly native indicator. This distinguishes it clearly from data-returning siblings like research_read_series and from other show_* widgets such as research_show_price or research_show_news.

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

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

States the prerequisite ("after evidence from research_read_series is available"), the selection condition ("Use only when a visual helps answer the question"), and explicit exclusions ("Not a data fetch, calculation, navigation hub or replacement for the assistant's interpretation"). It also names the recovery path for stale state: expired evidence requires 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 declare readOnly, idempotent, non-destructive, closed-world, and the description adds real context beyond them: it reuses captured source numbers/selection and that expired evidence requires an explicit new read. It does not contradict annotations. Slightly dense negations rather than describing the rendered output, but the added state/lifetime semantics are valuable.

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

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

Front-loads purpose and precondition before the restrictions, and every sentence carries routing or lifetime information. The stacked negations ("not a data fetch, calculation, navigation hub...") are informative but slightly heavier than 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?

Output schema exists so return values needn't be explained; the single parameter is fully documented in schema and reinforced in prose. For a read-only display widget, the description covers precondition, purpose, exclusions, and evidence lifetime — 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 coverage is 100% and one required evidence_id with a hex pattern, so baseline is 3. The description adds meaning beyond the schema: the id must reference evidence from this conversation, values/selection are re-read server-side, and evidence can expire requiring 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 ("Display") and resource ("focused video timeline widget") and explicitly frames it as a presentation layer distinct from research_ticker_videos (data fetch) and from navigation/calculation tools. An agent can tell exactly what this produces versus its 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 a precondition ("after evidence from research_ticker_videos is available"), a positive condition ("Use only when a visual helps answer the question"), explicit exclusions ("Not a data fetch, calculation, navigation hub or replacement for interpretation"), and the expired-evidence rule requiring a fresh 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 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.