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

Annotations already declare readOnly/idempotent/openWorld safety, so the bar is lower, and the description still adds a real behavioral constraint: a hard cap of up to 1,500 candles per call, which tells the agent results may be truncated. It stops short of describing pagination/truncation mechanics or the interaction with the download-size guard.

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?

A single front-loaded sentence with the per-call cap placed where it will be seen first. Nothing wasted, nothing buried.

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

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

The output schema and rich parameter descriptions carry most of the load, and the source/cap is stated, but for a tool with a cost-related parameter and a 1,500-candle ceiling the description says nothing about truncation behavior, expected return shape, or when to widen the interval versus paginate.

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 every parameter including the interval enum and the max_download_mb cost warning is already fully documented in the schema. The description adds no syntax or format detail beyond what is structured, so the baseline 3 applies.

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

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

States a specific output (OHLCV candles) at any interval, derived from a specific source (Reservoir's 1-second candles). An agent can distinguish this from reservoir_query (raw data) or reservoir_download (files) without inspecting 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?

Usage is implied by 'rolled up from 1-second candles' — this is the aggregation tool — but the description never explicitly says when to prefer it over reservoir_query or how it interacts with reservoir_coverage. No exclusions or prerequisites are stated.

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

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

Annotations already establish readOnly, idempotent, open-world behavior, so the safety bar is low. The description adds meaningful non-obvious content: it discloses the specific fields returned (venue first/newest day, update schedule, AWS cost) and the fallback behavior of pointing to an alternate API endpoint when a topic is absent.

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

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

Two compact sentences with no filler, and the coverage scope is front-loaded before the topic-routing behavior. The noun-pile style is dense but readable and every clause conveys 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 defining return values and annotations covering safety and idempotency, the description only needed to convey scope and topic routing, which it does. It could be slightly stronger by noting the no-argument default (full catalog), but 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?

Schema description coverage is 100%, including the venue enum list and a full explanation of `topic`, so the schema carries the parameter burden. The description restates the topic behavior without adding syntax, defaults, or format detail beyond the schema, making baseline 3 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 the specific resource it reports on (datasets, bucket paths, market naming, venue date ranges, update schedule, AWS cost), which clearly distinguishes it from sibling data-retrieval tools like reservoir_query or reservoir_candles. It is a telegraphic noun list rather than an explicit verb+object, but the intent (report Reservoir's coverage/catalog) is 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 explains the conditional behavior of the `topic` argument ('says whether Reservoir holds it and, if not, which Hydromancer API endpoint does'), which is a form of routing guidance. However, it never states when an agent should call this tool versus the sibling data tools (e.g., before querying, to discover venues), and gives no exclusions.

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 idempotentHint=true and destructiveHint=false, but the description adds the concrete mechanism: files land in a specific local folder, keep the bucket's layout, and existing files are skipped, which explains the idempotency rather than restating it. It does not mention network/credential requirements or what happens on partial failure, so it stops 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?

Three short sentences, front-loaded with the analogy and the destination path, then idempotency, then the use case. Nothing is redundant and every sentence carries information.

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

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

With an output schema present and full parameter documentation, the description only needs to convey the side effects and the intent, which it does. The remaining gap is the absence of any explicit comparison to the sibling query tools for an agent deciding between downloading and querying in place.

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 dataset, start/end, venue, market, and max_download_mb are all documented in the schema, including cost warnings and defaults. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description gives a concrete verb+resource ('save whole Parquet files') plus the exact destination (RESERVOIR_DATA_DIR, default ~/reservoir-data) and layout behavior (bucket folder structure preserved). The `aws s3 cp` analogy and 'whole Parquet files' phrasing implicitly separate it from query-style siblings like reservoir_query, but no sibling is named outright.

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 for repeated analysis' is the only usage cue, and it implies when this beats querying remotely without stating the alternative or any exclusion. There is no guidance on when not to download (e.g., one-off lookups) or how it relates to reservoir_query / reservoir_orderbook.

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 openWorldHint, so safety is covered. The description adds little behavioral context of its own — the cost warnings, day-level scanning, and small-file hints all live in the schema, not the description. It does not contradict 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?

A single front-loaded sentence that leads with scope and then lists outputs; no filler. The metrics list is dense but each clause carries information an agent needs to know the tool exists.

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 100% schema description coverage, the description only needs to convey the analytical surface, which it does by naming the aggregates and optional breakdowns/raw fills. What's missing is guidance on volume/time-range cost tradeoffs, which is relevant given a per-day file scan of possibly large downloads.

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 every one of the 11 parameters is already documented with format, defaults and constraints (relative dates, max_download_mb cost guard, group_by enums). The description adds no parameter-level meaning beyond the schema, which is the expected baseline at full 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?

Names a concrete resource (fills/trades) and enumerates the aggregates it returns: taker volume, buy/sell split, net flow, liquidations, VWAP, high/low, wallets, raw fills. Scope is stated as market/venue/wallet over any past window. It does not distinguish itself from siblings such as reservoir_query or reservoir_candles, so it stops short of a 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?

Usage is only implied — an agent can infer this is the fills/volume aggregation tool, but the description never says when to prefer it over reservoir_query, reservoir_candles, or reservoir_download, nor any exclusions or prerequisites. No explicit when/when-not guidance is present.

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 annotations already declare read-only, idempotent, open-world behavior, but the description adds concrete context: the tool returns file listings with sizes and download cost and performs no download. It does not mention auth or rate limits, which is a minor gap for a read-only listing tool.

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

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

Two sentences, front-loaded with a useful analogy and immediately scoped by dataset/date range. Every phrase adds information, and the non-download behavior is stated without clutter.

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 and the annotations cover safety semantics, while the input schema fully documents all parameters. The description supplies enough context for an agent to understand the tool's role and 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%, including detailed start/end formats and venue/market meanings. The description only maps loosely to dataset and date range and adds no parameter syntax or constraints beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb and resource: it lists exact Parquet files for a dataset and date range, with sizes, cost, and a query snippet. The phrase 'Lists only; downloads nothing' clearly distinguishes it from download/query 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 establishes a clear use case via the `aws s3 ls` analogy and points to `reservoir_query` as the consumer of the returned snippet. 'Lists only; downloads nothing' rules out download behavior, but it does not explicitly name `reservoir_download` or other siblings as alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description adds real behavioral context on top: top-20 depth cap, a 31-day maximum window, and that windowed results are medians rather than raw samples. It omits rate limits, pagination, and empty-result behavior, 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?

A single dense sentence that front-loads the resource and enumerates outputs in the order an agent would care about them. No filler, though the run-on enumeration takes a second pass to parse.

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 100%-covered input schema handles parameter detail. The description supplies the key constraints (top-20, 31-day cap, median aggregation) an agent needs before calling; only sibling differentiation is left thin.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including formats for start/end and the enum for every. The description adds only marginal meaning, mainly that 'N bps' maps to depth bands and 'order size' to notional_usd, plus the medians-over-window aggregation semantics.

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 specific resource and payload precisely: top-20 L2 books with mid, spread, USD depth by bps, slippage, window medians, and full-book snapshots. That is enough for an agent to tell it apart from reservoir_candles or reservoir_fills, though it never names those siblings 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?

Usage is implied rather than stated: the 'medians over the window' vs 'full book at a given minute' phrasing hints at two modes of call, and '(max 31 days)' bounds the window. There is no explicit when-to-use, when-not-to-use, or routing to alternative 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description usefully adds the key temporal behavior: data comes from the daily snapshot rather than live state, which is important 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?

The definition is a single front-loaded sentence that scopes the tool before enumerating the data it returns. It is dense but not padded, though part of the return-value enumeration is partly redundant given the presence of an output schema.

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

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

For a read-only, annotated tool with a full input schema and output schema, the description is largely sufficient for invocation. However, it says 'perp market' while the market parameter schema explicitly includes spot markets, creating a scope mismatch that could cause the agent to skip valid use cases.

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 market, date, and top semantics. The description does not add parameter-level detail beyond indirectly implying snapshot date and largest-position limiting, so the baseline score 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 resource and scope: open positions in a market from the daily snapshot, with long/short aggregates, entries, leverage, largest positions, and liquidation clusters. This clearly separates it from siblings like reservoir_orderbook, reservoir_fills, and reservoir_candles, though it uses no explicit verb like 'list' or 'get'.

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?

Usage is implied by the resource: use this for position/holder data from a daily snapshot. However, it offers no explicit when-to-use or when-not-to-use guidance and does not route the agent to alternatives such as reservoir_query for custom analysis or reservoir_orderbook for live book data.

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 the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description adds non-obvious behavior the annotations cannot express: an automatic download-size estimate derived from the columns read, a hard refusal above max_download_mb, and a read restriction to the Reservoir bucket and local copies. These are the failure modes an agent needs to anticipate before calling.

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 tight sentences with the core action, guardrail and alternative routing front-loaded in that order. The reference to "exactly like the exploring-reservoir blog" is a mild external pointer that costs a clause without full standalone value, but nothing else 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 an output schema exists and annotations declare the safety profile, the description supplies everything else an agent needs: access scope, cost guardrail, alternatives, and the read-only SELECT constraint (reinforced in the schema). Nothing material 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 coverage is 100%, so baseline is 3, but the description meaningfully explains max_download_mb's mechanism (estimate based on columns read, refusal above threshold) rather than just restating it. The sql parameter's syntax and path conventions are left entirely to the schema, so it does not fully supersede the structured data.

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 ("Run DuckDB SQL directly on the Reservoir bucket") plus the exact access scope, and explicitly bounds itself against sibling tools for fills, candles, books and positions. An agent can classify this as the escape-hatch SQL tool without opening a schema.

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

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

Explicit when-to-use (ad-hoc DuckDB SELECTs over the bucket), explicit when-not (“Prefer the dedicated tools for fills, candles, books and positions”), and the named domains map cleanly onto reservoir_fills, reservoir_candles, reservoir_orderbook and reservoir_positions. It also flags the cost precondition for raising the download ceiling.

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 openWorldHint, so the safety profile is covered. The description adds useful context beyond that by listing the specific environmental checks performed, which tells the agent what this diagnostic verifies without redundant safety restatement.

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

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

Two tight sentences: the first enumerates the checks, the second front-loads the usage trigger. Every clause 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?

An output schema exists to describe return values, and annotations cover safety and idempotency. The description supplies the remaining context an agent needs: what is checked and when to invoke it.

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

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

The tool has zero parameters, so there is nothing for the description to clarify; the schema is trivially complete. Baseline 4 applies, with no evidence of missing parameter guidance.

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+resource ('Check Reservoir access') and then enumerates exactly what is checked: AWS sign-in, requester-pays bucket access, DuckDB, local data folder, and monthly download total. This makes it immediately distinguishable from the data-fetching sibling tools.

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

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

It gives an explicit trigger condition: 'Run this first, or whenever a tool reports a credentials error.' That is strong when-to-use guidance, though it does not name specific sibling alternatives or state when not to use it.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds a genuinely useful non-obvious trait: the underlying files are not partitioned by wallet, so each requested part scans the full day's file — a real cost/latency signal that pairs with the schema's max_download_mb guard.

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

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

Two sentences, front-loaded with the concrete payload and followed by the operational caveat; nothing is wasted. The second sentence is terse to the point of slight ambiguity about what 'these files' refers to, keeping it just short of 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?

With an output schema present and 100% param coverage, the description need only frame scope and cost, which it does. The main remaining gap is routing guidance against reservoir_positions/reservoir_query, which an agent would need to choose this 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 explains date defaulting, address format, the include enum, and the download cap; baseline 3 applies. The description only indirectly motivates 'include' via the whole-file scan note and adds no format or default detail beyond the schema.

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

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

Names the specific resource (perp positions, spot balances, account values for one wallet on one day) and the source (global snapshots), which is concrete enough to distinguish it from a generic query tool. It does not explicitly name reservoir_positions or reservoir_query as the alternative, so sibling differentiation is only implied.

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?

Usage is implied by 'one wallet's daily snapshot' versus the whole-day global files, but there is no explicit when-to-use statement, no exclusion of reservoir_positions or reservoir_query, and no prerequisites (e.g. needing reservoir_setup_check first). The agent must infer selection from the name and the one-line scan caveat.

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