Hesper Atlas Evidence

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable behavioral context: default returns only stance, target-size and actionable risk changes; material_only=false includes mark and score updates; data is completed end-of-day, not real-time; and an active subscription is required. This goes well beyond the structured 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?

Three sentences with no filler; the main purpose is front-loaded and each sentence earns its place by adding scope, options, or prerequisites.

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 and safety annotations already covering read-only/idempotent behavior, the description covers the essential call context: cursor semantics, default filtering, the toggle for broader results, one-symbol filtering, pagination, subscription prerequisite, and data freshness caveat.

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 meaning by explaining the material_only default behavior and how to widen results, and it references symbol filtering and pagination in plain language, providing value beyond the schema.

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

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

The description states a specific verb and resource: chronological before/after events after a stable forward-publication cursor. It also distinguishes itself from sibling tools by emphasizing the publication-cursor mechanism and the default material-only scope, making it clear this is not a general get_* tool.

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 clear context: use this after a stable forward-publication cursor, with an active subscription, and it supports symbol filtering and pagination. It does not explicitly name alternative tools or say when not to use it, so an agent must partly infer how it differs from siblings.

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

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

Annotations already establish read-only/idempotent/safe behavior, and the description adds meaningful non-redundant context: rows are immutable and append-only, stable signal ids are preserved, the latest publication is the default, an active subscription is required, and data is completed EOD rather than real-time or advice. No contradiction with 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?

Three sentences earn their place: the first defines the row content and stability guarantees, the second covers defaults and options, the third states prerequisites and data timing. Key qualifiers like 'exact', 'immutable', and 'not real-time or advice' are front-loaded with no redundancy.

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

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

For a read-only, idempotent list-style tool with a full output schema and fully documented parameters, the description covers row contents, default behavior, filtering, subscription requirement, and data freshness. Nothing critical 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?

The input schema covers 100% of parameters, so the baseline is 3. The description's mentions of symbol filtering, pagination, and latest-publication default align with schema fields but do not add new semantic meaning beyond what the schema already 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 names the resource precisely—exact immutable agent-facing signal rows for one append-only publication—and details what is included (stable signal ids, previous-row links, changed-field classifications). This is clearly distinct from sibling list/publication tools by emphasizing 'one append-only publication' and frozen/immutable semantics.

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

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

It gives clear context for when the tool is appropriate: defaults to the latest publication, supports symbol filtering and pagination, requires an active subscription, and returns completed end-of-day data rather than real-time or advice. It does not name sibling alternatives or state explicit when-not-to-use rules, which keeps it just below a top score.

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

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

Despite readOnlyHint and idempotentHint already covering safety, the description adds valuable behavioral context: the artifact is committed, includes a content-derived run id and SHA-256 digest, and the chronological tail was reused in later research so results are labeled validation rather than pristine test. This provenance caveat is exactly the kind of non-obvious behavior an agent needs to know.

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 dense, purposeful sentences with the trigger use case front-loaded. The long middle sentence enumerates artifact contents without fluff, and the final sentence is a useful caveat. No sentence is wasted.

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, idempotent retrieval tool with a rich output schema and fully documented parameters, the description covers the use case, response content, provenance caveat, and non-performance disclaimer. Nothing important is missing for an agent to select and invoke the tool 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%, so the schema already documents limit, offset, and symbol with defaults and constraints. The description's mention of 'paged per-symbol' rows loosely reinforces the pagination and filtering semantics, but it does not add meaningful parameter-level detail beyond what the input schema already 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 opens with a specific use case — reconstructing or challenging the 152-name static-tail validation headline — and then names the exact deliverable: the committed row-level artifact. It clearly distinguishes this from a pristine unseen test and from live performance, so an agent can tell it apart from related evidence tools such as get_walk_forward_evidence.

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

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

It explicitly says when to use the tool ('Use when a user wants to reconstruct or challenge...') and gives meaningful exclusions ('not live performance or advice'). However, it does not name sibling alternatives or state when a different evidence tool would be more appropriate, so it stops just short of full alternative routing.

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 and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context: it states the output includes per-year/per-theme cuts, extremes, open book, combined closed+open buckets, and explicitly frames the tool as signal data, not investment advice.

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, then compresses the eight available cuts into one readable, purposeful sentence. The final pointer to `section` and the 'not investment advice' caveat are both relevant and brief.

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 and the annotations cover side-effect safety, the description supplies exactly the missing decision context: what kinds of questions this tool answers, what cuts are available, and how to narrow output. Nothing an agent needs to select it correctly is absent.

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

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

Schema coverage is 100% and the single parameter already has a clear enum and default description. The description reinforces using `section` to pull one cut instead of all, but this does not go substantially beyond what the schema already 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 opens with an explicit user-intent trigger ('drawdowns, weak periods, best-versus-worst, ...') and a specific resource ('current-rule historical replay'). The list of distinct cuts makes the tool's scope concrete and separates it from sibling tools such as get_track_record or get_forward_record.

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 clearly states when to use the tool ('Use when a user asks for drawdowns, weak periods...') and advises using the `section` parameter to narrow the result. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds the meaningful access requirement (active subscription) and names the specific content categories returned, which helps the agent anticipate what the call entails. No contradictions with 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?

The description is compact and front-loaded with the market-level scope, and the subscription requirement is separated into a short second sentence. The first sentence is grammatically awkward and dense, but it conveys the core content without waste.

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

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

With zero parameters and an existing output schema, the description adequately covers what the tool returns and the key prerequisite. It could be slightly more complete about what happens when no subscription is active, but for a read-only, parameter-less context tool this is sufficient.

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

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

The tool has zero parameters, so there is nothing for the description to clarify beyond the schema. Baseline 4 applies because no parameter documentation burden exists.

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

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

The description clearly identifies the tool as returning whole-tape market context—risk regime, breadth, market heat/froth, and cycle read—and distinguishes it from per-name signal tools by saying per-name signals sit inside it. It lacks a direct verb ('get'/'returns'), 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?

The description implies this is for market-level context rather than per-name signal retrieval, and states the subscription prerequisite. However, it does not explicitly say when to use it over sibling tools like get_signal or list_signals, nor does it provide exclusions or alternative routing.

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, non-destructive, idempotent behavior. The description adds valuable context beyond annotations by disclosing that the tool exposes decision logic, claim boundaries, and known biases. This meaningful characterization helps the agent know what kind of information to expect.

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

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

Three short sentences, with the most important usage guidance front-loaded and no filler. Each sentence earns its place, and the final instruction reinforces a key scenario without being 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?

The description fully equips an agent to decide when to invoke this tool and what it will provide. With zero parameters and an output schema available, no additional invocation details are necessary, and the guidance is complete for its role among the listed siblings.

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

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

The tool has zero parameters, and the schema is fully covered with an empty properties object. No parameter explanation is needed; the baseline of 4 applies.

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

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

The description clearly states what the tool provides: an explanation of how the engine makes decisions, what the published numbers claim or do not claim, and known biases. It is distinct from the sibling tools by positioning itself as the methodology/context provider rather than a data or signal retrieval tool.

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

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

The description gives explicit when-to-use guidance: before interpreting any performance or signal claim, especially when assumptions, limitations, or bias are in question. The closing instruction to read it before quoting any statistic from other tools clearly routes agents to this tool ahead of alternatives.

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

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

Annotations already declare readOnly, idempotent, and not destructive. The description adds meaningful behavioral context: subscription requirement, blindness to user circumstances, and that it is not personalized advice. This goes beyond the annotations without contradicting them.

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 compact and front-loaded, with the core purpose in the first sentence and important constraints in the second. The main redundancy is that 'Requires an active subscription' restates the title's '(subscription)', but this is minor and reinforces an important access condition.

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 tool with one enum parameter and an output schema, the description is largely complete: it explains what the portfolio contains, the weighting approach, subscription needs, and the non-personalized nature. It does not detail the output structure, but the output schema covers that, so the description does not need to.

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

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

Schema coverage is 100%, with the only parameter n described as 'Position count. Default 10.' The description reinforces that n controls the number of names selected but adds no syntax, default, or format detail beyond the schema. Baseline 3 is appropriate when schema carries the semantic load.

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

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

Description states a specific verb and resource: returns the Hesper Atlas model portfolio, the best N names currently recommended. It clearly distinguishes what the tool is (a rules-based model book) from other tools including the named sibling get_methodology and get_signal, and explains the blend-ranked, risk-weighted construction.

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?

Description provides clear usage context: requires an active subscription and is not personalized advice. It does not explicitly name alternatives or when-not-to-use scenarios, but the context is strong enough for an agent to infer this tool is for the model portfolio rather than personalized recommendations.

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 and idempotent behavior. The description adds important non-obvious behavioral context: 'it explicitly states that no independent timestamp authority or third-party signer is configured' and clarifies what first-party hashes can and cannot prove. This goes well beyond the structured 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?

The description is front-loaded with the exact user intents it serves, followed by the concrete data returned, and ends with a key limitation. Every sentence contributes useful information without redundancy.

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

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

For a parameterless, read-only tool with a rich output schema and annotations, the description fully covers purpose, use cases, return content, and the main limitation. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters, so schema coverage is 100% and there are no parameter semantics to explain. The description focuses on return content rather than inputs, which is appropriate for a parameterless tool.

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 specific use cases: 'where a number came from, whether two results used the same code, or what first-party hashes can and cannot prove'. It names the resource (methodology and calculation provenance) and distinguishes itself from siblings like get_methodology by emphasizing hashes, calculation versions, and attestation limitations.

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 when' conditions are provided for determining number provenance and code consistency. It does not explicitly state when not to use the tool or mention sibling alternatives, but the usage context is clear enough for an agent to select it correctly.

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 mark the tool as readOnly, idempotent, and non-destructive. The description adds substantial behavior beyond that: it requires an active Hesper Atlas subscription, returns only the latest completed end-of-day state, and explains that `action` and `suggested_position` are authoritative once a trigger is crossed. It also includes the 'signal data, not investment advice' caveat.

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 dense but structured: a front-loaded usage directive, a colon-introduced list of return fields, and concise caveats. Every sentence adds information; the field list is arguably long but necessary given the tool's specificity.

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

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

For a single-parameter, read-only tool with an output schema and annotations, this description is complete. It covers when to use it, subscription requirements, what data is returned, field authority semantics, and a legal disclaimer. Nothing essential 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?

The input schema fully documents the single `symbol` parameter with a description, example, and case-insensitivity note (100% schema coverage). The tool description adds no new parameter-level detail beyond referring to 'one ticker', which matches the baseline expectation for a fully covered schema.

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

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

The description opens with a specific use case ('Use when an authorized user asks for the latest Hesper Atlas action on one ticker') and names the exact resource ('latest completed end-of-day state'). It clearly distinguishes itself from replay data and subsequent sibling tools by scoping to a single ticker and the current signal.

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 a clear when-to-use condition (authorized user, latest action, one ticker) and explicitly instructs not to substitute replay data if access is missing. It mentions the subscription prerequisite, but does not explicitly name sibling alternatives such as list_signals or get_symbol_record, so it stops just short of full alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavior context: it returns closed round trips with specific fields, may include an open position, and explicitly states the data is retrospective and not investment advice. This adds meaningful transparency 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?

Three sentences with no fluff: usage trigger, return payload, and exclusion/alternative are each front-loaded and purposeful. The structure guides the agent from when to use to what to expect in a compact format.

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

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

The tool is simple (one required parameter) and has an output schema, so return values need no elaboration. The description explains the use case, the data returned, the open-position nuance, and the correct sibling alternative. 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%, with the symbol parameter already documented as a ticker symbol, example, and case-insensitive. The description reinforces 'one ticker' but does not add new parameter-level meaning beyond the schema. A baseline of 3 is appropriate given the complete schema coverage.

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

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

The description states a specific verb and resource: it returns per-ticker historical behavior of Hesper Atlas's rules. It clearly specifies the scope (one ticker) and the output (closed round trips plus an open position), distinguishing it from forward-looking or recommendation tools.

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

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

The description explicitly says when to use this tool ('when a user asks how Hesper Atlas's current rules historically behaved on one ticker') and directs the user to get_signal for the latest end-of-day state. It also warns that this is retrospective history, not a forward record or current recommendation, giving clear routing guidance.

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

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

Beyond readOnlyHint/idempotentHint annotations, the description discloses that this is a retrospective replay rather than a live append-only record, that both winning and losing replay signals are included, that the open book is bounded and marked at last close, and that the output is signal data rather than investment advice. This adds meaningful behavioral context 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?

Four sentences, front-loaded with the use case and return contents. Each sentence earns its place: the trigger, the output summary, the inclusion of both outcome types, the replay-vs-live distinction, and the disclaimer. No filler or redundancy.

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

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

With an output schema present, return values need no further explanation. The description covers the time window, the engine being replayed, the closed-signal metrics, the open book page, the replay/live distinction, and the not-advice caveat. Nothing essential 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?

Schema description coverage is 100%, so the schema already explains open_limit and open_offset fully. The description's mention of the 'bounded page of the open book' gives some contextual framing for the paging parameters, but it does not add significant semantic value beyond the schema.

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

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

The description opens with a specific use case ('whether Hesper Atlas's headline track record is supported') and clearly states the resource: headline performance of today's trend engine replayed over up to five years of historical EOD data. It also distinguishes itself from an 'append-only live record,' which separates it from forward-looking 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?

The 'Use when...' phrasing gives explicit trigger scenarios: checking whether the headline track record is supported, or wanting winning, losing, and still-open periods. It also states what the tool is not ('not an append-only live record'), but it does not name the specific sibling tool to use instead, so the guidance is clear but not fully explicit about alternatives.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial context beyond that: the artifact is 'cache-frozen,' candidates use 'only earlier observations,' execution is 'next-open' with costs, and weak periods or underperformance are deliberately retained. This gives agents a clear model of what the operation does and does not do.

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 usage triggers and stays compact despite covering purpose, methodology, output contents, and limitations. Every sentence contributes useful selection or invocation information without fluff.

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

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

Given the optional parameters, rich annotations, and an output schema, the description covers the full context an agent needs: when to invoke, what methodology guarantees are built in, what the response contains, and what the result is not. No critical gap is apparent.

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?

Input-schema coverage is 100%, with each parameter already described including defaults, bounds, and case-insensitivity. The tool description does not add parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource: it 'Returns the committed cache-frozen annual walk-forward artifact' and ties the tool to concrete user intents like 'stricter time-ordered evidence, weak years, benchmark underperformance, or a check against look-ahead.' It also distinguishes itself from live performance or advice, which separates it from related validation or performance tools.

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

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

It explicitly opens with 'Use when a user asks for...' and gives four concrete trigger conditions. It also states an important boundary: 'Historical validation, not live performance or advice.' However, it does not name a sibling alternative or say when to prefer another evidence-related tool, so it stops short of the strongest possible routing guidance.

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

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

Annotations already convey readOnly, idempotent, and non-destructive intent. The description adds meaningful behavioral context beyond annotations: the ordering ('newest exit first'), the exhaustive inclusion ('Winners and loserrs both; nothing is excluded'), and the advisory disclaimer ('Signal data, not investment advice').

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

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

Three short sentences, each earning its place: core resource and ordering are front-loaded, filtering is stated concisely, and the disclaimer is tucked at the end. No filler or redundant restating of the name.

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 and annotations cover safety/idempotency, the description supplies the missing behavioral context: raw replay nature, ordering, filterability, and inclusion of all outcomes. An agent has enough to call the tool correctly without missing key semantics.

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?

Input schema coverage is 100%, with each parameter already described. The description only loosely maps to symbol and exit-date filtering, adding little beyond the schema. Baseline 3 is appropriate because 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?

The description identifies a specific resource ('closed-signal historical replay') and concrete behaviors: newest exit first, filterable by symbol and exit date, and inclusive of winners/losers. It is unambiguous but does not explicitly contrast a sibling tool such as list_signals, so it falls short of full sibling differentiation.

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?

No explicit when-to-use guidance or mention of alternatives is provided. The phrase 'historical replay' implies a retrospective purpose, but the description never says when to choose this tool over list_signals, get_signal, or other sibling tools.

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?

The description goes well beyond the readOnly/idempotent annotations by revealing append-only semantics, the refusal to calculate performance from commitments, the absence of fabricated historical backfill, and the boundary that paid current signal data is not exposed. These are meaningful behavioral traits an agent needs to set expectations correctly.

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 a 'Use when' trigger, then packs precise, non-redundant details about return contents and behavioral guarantees. The final disclaimer is short and earns its place by preventing misuse. No sentence is wasted.

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 two optional parameters, an output schema, and read-only annotations, the description is complete: it explains what is returned, what is intentionally not computed, the ledger's history boundary, and how to decide when to call it. Nothing critical for correct invocation or expectation-setting 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 the schema already documents 'limit' and 'since_as_of' with clear meanings. The description adds context about manifests and the ledger but does not directly elaborate on parameter usage, which matches the baseline of 3 for high schema coverage.

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 set of user intents ('what Hesper Atlas actually published, when it was committed, what changed, or whether forward history is mature enough to evaluate') and then names the exact deliverable: public append-only manifests for end-of-day signal publications. It also distinguishes itself from sibling signal/list tools by emphasizing that it proves commitments without exposing the paid current signal book.

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

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

The description explicitly says 'Use when a user asks...' and lists four concrete triggering conditions, making the appropriate invocation context clear. It does not name alternative sibling tools or state when not to use this tool, so it stops short of a full 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive; the description adds meaningful behavior: chronological scan-window history, actionable filtering ('still BUY/STRONG BUY and not critical sel-risk'), active-subscription requirement, and a not-adivce disclaimer. No contradiction with 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?

The description is compact and front-loaded: the core purpose appears first, key kind distinctions are explained, and the subscription/disclaimer caveats are one short sentence each. Every sentence earns its place.

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

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

Given an output schema exists and annotations cover safety, the description is sufficient for selection and invocation: it covers preconditions, semantic differences among kinds, and the data's status. It does not define every list kind in detail, but the enum names are self-explanatory and the schema provides additional constraints.

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

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

The input schema covers 100% of the two parameters, so the baseline is 3; the description goes beyond by explaining what recent_entries vs recent_buys mean and enumerating the remaining kind options. It does not add detail for limit, but the schema already constrains that fully.

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

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

The description clearly identifies the tool as returning the engine's current end-of-day signal lists and enumerates the eight list kinds, so an agent knows what resource it addresses. It does not explicitly distinguish from sibling tools such as get_signal or list_closed_trades, which keeps it at 4 rather than 5.

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 usage context within the tool: recent_entries is chronological history even if a name is now HOLD or risky, while recent_buys is actionable now, and it notes subscription as a prerequisitive. It does not state when to choose list_signals over sibling tools, so there are no exclusion rules or alternatives.

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