Ironflow: Hyperliquid data

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by enumerating the metadata returned (tables, columns, lookback, query tips, examples, user limits), though it remains vague about what 'your own limits' actually entails.

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 a single front-loaded sentence that states the core purpose first and then enumerates the data domains. The long parenthetical is dense but every listed domain adds useful scope information; it could be marginally more structured but is not bloated.

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

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

Given an output schema exists, the description need not detail return values, but it still gives a rich summary of what the output includes. It is complete enough for a zero-parameter metadata tool, though it would be slightly stronger if it explicitly linked itself to run_query usage.

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 no parameter semantics to explain. The baseline score for a no-parameter tool is 4, and the description does not need to compensate for missing schema detail.

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 ('Returns') and resource ('SQL tables') and clearly scopes the Hyperliquid data domains covered. It distinguishes itself from sibling query tools by indicating it returns metadata such as columns, history depth, query tips, and examples rather than data rows.

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 a discovery/schema-introspection tool useful before writing SQL queries, especially through phrases like 'query tips, worked examples and your own limits.' However, it does not explicitly say when to use this instead of run_query or other sibling tools, nor does it state exclusions or prerequisites.

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 openWorldHint, so the safety profile is covered; the description still adds real behavior beyond that — candles are built from every trade (completeness guarantee), results are ordered oldest first, and the default fetch is the latest 24 with a 500 cap. It does not mention pagination or gaps for illiquid intervals, but with an output schema present the return shape needn't be spelled out.

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 no filler: the payload contents come first, then the default/size behavior, then usage plus sibling disambiguation. Every clause carries information an agent would otherwise have to infer.

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-market read tool with only three fully documented parameters, an output schema and read-only annotations, nothing essential is missing. The description covers what the data is derived from, ordering, sizing defaults and the alternative tools.

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

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

Schema coverage is 100% and each parameter already carries its own description including the 1-500 range, the 24 default and the interval enum. The description restates the default window and interval span but adds no new syntax or constraint 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?

The description names a specific resource and verb shape: OHLCV candles for one Hyperliquid market, built from every trade, with the exact fields (open, high, low, close, volume, trade count). It also names the scope limit (one market) so an agent can immediately distinguish it from portfolio- or wallet-level 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 gives positive usage guidance ("use it for price history, ranges and charts") and explicitly routes two adjacent needs to named siblings: get_price for the current price and get_recent_trades for individual trades. Both the when and the when-not 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?

Beyond the read-only and open-world annotations, it discloses the 100-address result cap, cohort-specific metric meanings and USD units, and that fetched_at reflects when the cohort was last computed. These details set useful expectations about result size, interpretation, and freshness.

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 sentences front-load the result and then cover the prerequisite and downstream workflow. Nearly every clause adds actionable information, and the examples remain relevant without becoming filler.

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

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

For a one-parameter read with an output schema and read-only annotations, this covers scope, limits, data meaning, freshness, cohort discovery, and next steps. Nothing material is missing for selecting and invoking 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 coverage is 100%, and the description largely repeats that name should come from list_cohorts rather than adding new syntax or validation details. The ranking-metric explanations concern returned values rather than the parameter itself, so the high-coverage baseline 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 opening identifies the exact resource—wallet addresses for one named cohort—and the description distinguishes this from list_cohorts, which supplies cohort names and selection logic, and from downstream wallet-inspection tools. The 100-address cap and cohort-specific ranking values further sharpen its scope.

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 prerequisite—call list_cohorts first—and explains that this provides valid names and cohort selection criteria. It also names three downstream tools and explains when to feed the returned addresses to them, providing a concrete workflow.

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=true, openWorldHint=true), and the description adds real behavioral detail beyond them: the $10k order threshold, the 30-minute measurement horizon, the minimum-5-scored-orders filter that silently drops wallets, and the fact that the response restates the formulas. The one notable omission is how the returned wallets are ranked or ordered, which matters for interpreting a capped list.

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 definition is front-loaded in the first sentence, followed by the per-wallet metric list, the eligibility rule, and the usage routing. The first sentence is long and clause-heavy, but nearly every clause (threshold, directionality, 30-minute horizon, window) carries decision-relevant information, so there is little 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?

For a screening tool with a rich output schema, the description covers what is measured, the thresholds applied, the qualifying condition, the stated caveat about predictive validity, and where to go next. Since an output schema exists, the absence of exhaustive return-format documentation is not a gap.

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

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

Schema description coverage is 100%, so all three parameters (limit, market, window) are already documented, and the description mostly restates them ('over the last 7 or 30 days'). It adds a little meaning by tying the window to the scoring period and stressing 'one Hyperliquid market' as the unit of analysis, but says nothing about the limit parameter or the interaction between window length and the 5-order minimum. Baseline 3 is appropriate.

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

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

The description names a specific verb-like objective (surface wallets whose >=$10k orders preceded favorable moves on one Hyperliquid market) and enumerates the exact per-wallet outputs: scored order count, total notional, lead score in basis points, hit rate, last order time, and cancelled-share. This is clearly distinguishable from sibling tools such as get_market_top_wallets or get_trader_profile, which do not score order timing.

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 'Use it to find wallets worth watching on one market, then check them with get_trader_profile or get_user_state,' naming the follow-up alternatives and the selection condition (single-market screening). It also states the eligibility floor of 5 scored orders and the caveat that past activity does not predict future results, so an agent knows both the entry point and the limits of the output.

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 openWorldHint, so safety is covered. The description adds genuinely useful context beyond that: it draws from indexed history and explains the key advantage over Hyperliquid's native userFills endpoints (which truncate at 10,000 fills), giving the agent a reason to prefer this tool. It doesn't mention pagination semantics or latency, but the core behavioral differentiator is disclosed.

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 front-loads what is returned, the second justifies the tool with a concrete comparison. No filler, though the returned-field list sits a bit dense and could be trimmed since an output schema 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 annotations covering safety, a full parameter schema, and an output schema, the description only needs to convey scope and the indexing rationale, which it does. A mention of ordering (chronological vs reverse) would round it out fully.

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 all three parameters are already documented, including limit range and market naming formats. The description only implies the market filter is optional and that address scopes to one wallet, adding minimal value beyond the schema. 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+resource (retrieve every fill for one wallet), names the returned fields (price, size, side, fee, realized PnL) and the optional market scope. Distinguishes it from related siblings like get_recent_trades and get_user_ledger by tying it to a single wallet's fill history.

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?

Implicit guidance: use this when you need a wallet's fill history beyond the API's 10,000-fill cap, and the optional market parameter hints at filtered lookups. But it never states when NOT to use it or names an alternative sibling (e.g. get_user_ledger for non-fill ledger events, get_recent_trades for market-wide trades).

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 openWorldHint, so the safety profile is covered. The description goes beyond them by disclosing the hourly sampling interval and decoding the sign convention (positive = longs pay shorts), which an agent cannot infer from the annotations and would otherwise likely get wrong. It stops short of covering pagination or limit behavior, but that is minor here.

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 short sentences with zero filler, and the resource definition is front-loaded before the interpretive note. Nothing is repeated from the schema or annotations.

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 shape need not be described, and the description covers granularity, market scope, and the sign semantics an agent needs to interpret results. A pointer to get_funding_stats for aggregate vs. historical statistics is the only notable omission.

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 documented there, including market name formats, so the baseline of 3 applies. The description adds no syntax or default detail beyond the schema; the HIP-3 mention lightly signals supported market families but does not explain parameter usage.

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 ("Hourly funding rate history") and scopes it to Hyperliquid perps, explicitly including HIP-3 builder perps. It does not name the closely related siblings (get_funding_stats, get_user_funding), so an agent must infer the split from the name alone.

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 word "history" and the hourly granularity, but there is no explicit statement of when to pick this over get_funding_stats or get_user_funding, and no exclusions or prerequisites. An agent can guess the intent but receives no routing help.

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=true and openWorldHint=true, so the safety profile is covered. The description adds that results are bucketed and aggregated, which is genuinely beyond the annotations. It says nothing about how the bucket window aligns, whether the annualized rate is scaled to 8h funding periods, or how limit truncates the series.

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 names the resource first and enumerates outputs after. No filler and nothing to trim.

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 prose, and the schema fully documents the three parameters. What remains missing is domain context an agent would want before relying on results, such as the funding interval basis for the annualized figure; the definition is otherwise sufficient to 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 description coverage is 100%, with per-parameter text covering market formats, the interval enum, and the limit default, so the schema does the heavy lifting. The description's phrase 'per time bucket' loosely maps to interval but adds no syntax or default beyond what is already documented.

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

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

States a specific resource (funding statistics for a Hyperliquid perp) plus the exact aggregation set returned: average, minimum, maximum, annualized rate. That is far more precise than the title. It stops short of naming sibling get_funding_rates, so the raw-vs-aggregated distinction must be inferred from the field list.

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: 'per time bucket' and the aggregation wording suggest this is the summary counterpart to get_funding_rates, but no alternative is named and no when-not-to-use condition is given. An agent must infer the routing from sibling names alone.

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?

Adds real value beyond the annotations: it discloses the credential tier required (Builder or Enterprise) and the concrete failure mode for keyless/free-key calls (403). Annotations only cover readOnlyHint and openWorldHint, so the auth prerequisite is genuinely new information. It still omits any time-window or pagination behavior for what is presumably a large dataset.

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, no waste, and the definition of the metric is front-loaded ahead of the access caveat. Each sentence earns its place: one says what the data is, one says whether you can get it.

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 shape needn't be described, and both parameters are fully documented in the schema. The remaining burden — what the tool computes and what access it requires — is covered. Only the sibling routing and time scope are thin, and those are secondary for a two-parameter read 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 description coverage is 100%, so both market and bucket_size are already documented, including allowed values and the default of 100. The description reinforces that bucketing is by price, which loosely frames bucket_size, but adds no syntax or semantics the schema doesn't already carry — baseline 3 applies.

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

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

Names a specific verb+resource: liquidated notional on a Hyperliquid perp, bucketed by price, with a clarifying gloss ('where longs and shorts were wiped out'). The 'bucketed by price' framing implicitly separates it from raw-event siblings like get_liquidations, but it never names them, so differentiation is inferred rather than stated.

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

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

Usage is only implied — an agent can infer this is the aggregate-by-price view rather than the event-level or summary view, but with three liquidation siblings (get_liquidations, get_liquidation_summary, get_liquidation_levels) the description offers no explicit routing guidance. There are no when-not-to-use conditions either.

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 openWorldHint, so the bar is lower, yet the description adds genuinely useful context: the data comes from the provider's own nodes and Hyperliquid's public API has no liquidation feed, which explains why this tool exists and implies coverage limits. It stops short of disclosing ordering, retention window, or event latency.

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 short sentences, front-loaded with what the tool returns, followed by a one-clause justification of its provenance. No filler and nothing repeated from the name or annotations.

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 annotations covering safety, the description only needs to explain scope and origin, which it does. The remaining gap is behavioral detail an agent would want for a time-series feed — ordering (newest first?) and how far back events go.

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 market parameter's accepted formats and the limit range are fully documented in-schema. The description adds nothing about parameter semantics, 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 resource (liquidation events on a Hyperliquid perp) and enumerates the returned fields (price, size, side, liquidated wallet), which distinguishes it from aggregate siblings like get_liquidation_summary. It never names those siblings, so the differentiation is implicit rather than explicit.

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 by the noun phrase 'Liquidations ... : price, size, side and the liquidated wallet' — an agent can infer this is the raw-event tool versus the summary/levels tools, but there is no explicit when-to-use or when-not-to-use statement.

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 (readOnlyHint, openWorldHint), and the description adds real behavioral context the annotations don't: the ranking criteria and the minimum 5-closed-trades filter that determines who appears. It stops short of noting result ordering stability, pagination, or what happens when a market has too few qualifying wallets.

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?

One dense sentence, front-loaded with what is returned and followed by the ranking and inclusion rules. Every clause earns its place and nothing is repeated from structured fields.

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 a full input schema and an output schema, the description only needs to explain the selection logic, which it does completely via ranking order and the trade-count threshold. Minor gaps remain around tie-breaking and empty-result behavior, but nothing essential to calling 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%, including market name formats, limit range, and window enum, so the schema carries the parameter burden. The description reinforces the meaning of 'market' via 'one Hyperliquid market' but adds no syntax 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?

States a specific resource (best traders on one Hyperliquid market) and the exact ranking rule (profit factor, then win rate) plus the inclusion threshold (5 closed trades). That combination separates it from generic siblings like get_top_traders or get_pnl_leaderboard, though it never names an alternative 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 only implied: an agent can infer this is the tool for per-market trader ranking, but there is no statement of when to prefer it over get_market_top_wallets, get_top_traders, or get_pnl_leaderboard, and no explicit 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 readOnlyHint and openWorldHint, so safety is covered; the description adds useful behavior: only "active" markets are included, the response is a top-N ranking (default 25, unless limit is set), and funding is hourly with the sign convention defined in the schema. It does not mention whether values are snapshot-at-call or delayed, but for a read-only snapshot tool the disclosure is solid.

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: what it returns, how to rank it, how to filter, plus the default cardinality — front-loaded with zero filler. Every clause carries actionable 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, return-field documentation is not required; coverage of the six optional params, the default size, and the active-market scope is enough for an agent to call it correctly on the first try.

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

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

Schema description coverage is 100%, and the schema already documents defaults (limit 25, sort_by volume), the enum values, and the funding sign convention. The description restates the default top-25 behavior and the min_volume_usd intent without adding syntax or edge-case detail the schema lacks, 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?

It names a specific verb and resource ("Active Hyperliquid markets ranked in one call") and enumerates the returned metrics — mark price, 24h change/volume, open interest, hourly funding — which differentiates it from the single-metric siblings (get_mark_prices, get_open_interest, get_funding_rates). It stops short of explicitly naming those alternatives, so the composite-vs-single-metric distinction must be inferred.

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?

"Sort by abs_funding for the most extreme funding, abs_change_24h for the biggest movers" ties each sort key to a concrete analyst intent, and "Use min_volume_usd to skip illiquid markets" states when a filter is warranted. There is no explicit when-not-to-use or pointer to a sibling for narrower queries (e.g. a single price), so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the 200-row ceiling and market scoping, which is useful. It does not disclose pagination behavior, how ties are broken, or whether wallets with zero activity are included — acceptable gaps given annotation coverage but nothing beyond the basics.

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?

One sentence, front-loaded with the resource and scope, no filler. It is efficient, though it is terse enough that it could have absorbed one clause about alternatives without becoming bloated.

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

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

With an output schema present, return values need not be explained, and the 5-parameter schema is fully described. The description covers scope and row cap; only the choice among sibling leaderboard tools is left unaddressed, which is minor given the complete 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 description coverage is 100%, so every parameter (from/to, limit, market format, sort_by enum) is already documented in the schema. The description echoes the ranking metrics and the 200-row limit but adds no new semantics such as default sort behavior or time-window implications.

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 clear verb+resource ('Top wallets') scoped to 'one Hyperliquid market' and the two ranking modes (volume, realized PnL), plus a row cap. It does not explicitly distinguish itself from the similar siblings get_top_traders, get_pnl_leaderboard, or get_market_leaders, which is the only missing piece.

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?

Implicit usage is inferable: use this when you want the leaderboard for a single market rather than a global leaderboard. But there is no explicit when-to-use/when-not, no naming of the alternative siblings that also return trader rankings, and no note on when to prefer volume vs realized_pnl ranking.

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 openWorldHint, so the safety profile is covered. The description adds real domain semantics beyond that: funding is a fraction per hour with a worked conversion example and a sign convention (positive means longs pay shorts), plus the fact that a reading timestamp is returned. It doesn't discuss data freshness or failure behavior for unknown markets, which keeps it short of a 5.

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

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

Front-loads the returned data, then units and sign convention, then routing to alternatives. Every clause carries information; no filler or restatement of the title.

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 tool with an output schema and read-only annotations, the description supplies the remaining needed context: what is returned, units and sign convention for funding, and when to prefer siblings. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema description already enumerates accepted market formats (BTC-PERP, xyz:NVDA-PERP, HYPE/USDC, BTC, @107). The description only reinforces the single-market scope ('one Hyperliquid perp'), adding little syntax or validation 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?

States a specific set of resources (latest mark price, oracle price, hourly funding rate, reading time) for a scoped unit (one Hyperliquid perp). An agent can distinguish it from get_price and get_funding_rates 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?

Gives an explicit trigger ('when you need the oracle price or funding next to the mark, for example for basis or premium') and names three alternatives with the condition that selects each: get_price for price only, get_funding_rates for history, get_markets_snapshot for many markets.

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 openWorldHint, so safety is covered. The description adds genuine value by disclosing the unit convention and the USD conversion recipe (multiply by get_price), which prevents a common misinterpretation. It does not cover refresh cadence/staleness of the 'latest' reading or rate limits, so it stays above baseline but below rich behavioral disclosure.

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 what the tool returns and its units, followed by the USD conversion recipe and sibling routing. No filler or restatement of the title.

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 need not be enumerated, yet the description still flags the unit and the companion fields an agent must not miss. For a single-parameter read tool, 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 market parameter already documents accepted forms (BTC-PERP, xyz:NVDA-PERP, HYPE/USDC, Hyperliquid names). The description only reinforces single-market scope via 'one Hyperliquid perp' and adds no syntax or format 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?

Names a specific verb and resource ('Latest open interest of one Hyperliquid perp') and pins down the otherwise ambiguous unit ('units of the base asset, BTC for BTC-PERP'), plus the extra fields returned (24h volume in USD, timestamp). The scope 'one perp' clearly separates it from aggregate/market-wide 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?

Explicitly routes the agent: cross-market comparison goes to get_markets_snapshot, historical series goes to run_query via describe_data, and USD conversion uses get_price. Both when-to-use and when-to-use-something-else are stated with the selecting condition.

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 openWorldHint, so the safety profile is covered. The description adds a real behavioral rule beyond structured data: wallets with fewer than 5 fills in the window are excluded, which materially affects interpretation of results and is not in the schema. It does not mention pagination/truncation behavior beyond the schema's limit.

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, no filler, with the core purpose front-loaded and the eligibility caveat as a follow-up. Every clause carries information.

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

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

An output schema exists and annotations cover safety, so the description needn't explain returns. Given four optional params with full schema documentation, it is essentially complete; the only missing piece is routing guidance versus the sibling ranking tools.

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

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

Schema description coverage is 100% with formats, defaults, and the sort_by enum fully documented, so the baseline applies. The description's 'over a window' and metric list only mirror from/to and sort_by without adding syntax or edge-case 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 verb (ranked), resource (every Hyperliquid wallet), and the metrics used (realized PnL, losses, volume) over a window — an agent knows exactly what comes back. It does not differentiate itself from plausible siblings like get_top_traders, get_market_top_wallets, or get_vault_leaderboard, which also return ranked wallets.

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 by 'ranked ... over a window'; there is no statement of when to pick this over the other leaderboard/ranking siblings, nor any prerequisite or exclusion guidance. An agent must infer the choice from sibling names alone.

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=true and openWorldHint=true, so the safety profile is covered. The description adds genuine value by specifying the return shape ('as a single number') and by contrasting mark price with oracle price, which is the main semantic trap for this tool. It does not mention error behavior for unknown market symbols, which keeps 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?

Three tight sentences: the answer shape and coverage first, then the use case, then the disambiguation list. Every clause carries routing or semantic information and there is no redundant restatement of the title.

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?

A single required parameter at full schema coverage, an output schema that defines the return value, and annotations covering the safety profile. The description supplies the one thing structured fields cannot: how mark price differs from oracle price and which sibling to pick instead. 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 market parameter description already enumerates BTC-PERP, xyz:NVDA-PERP, HYPE/USDC, and bare Hyperliquid names. The description reinforces the accepted symbol families but adds no new format, casing, or normalization rules beyond the schema. Baseline 3 applies 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?

States a specific verb and resource ('Latest mark price of one Hyperliquid market as a single number') and immediately enumerates the market families it covers (native perps, HIP-3 builder perps like xyz:NVDA-PERP, spot). The agent can distinguish it from get_mark_prices, get_candles, and get_markets_snapshot 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?

Gives an explicit selection heuristic ('The quickest answer to what is X trading at') plus three named alternatives with the exact condition that routes to each: get_mark_prices for oracle price and funding, get_candles for history, get_markets_snapshot for multi-market comparison. 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 read-only and open-world, so the safety profile is covered. The description adds genuine context beyond that — tick-level granularity, provenance ('from our own nodes'), and the full market-type coverage — but says nothing about ordering (newest-first assumed), the 100-row cap behavior, or whether history is bounded.

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, zero filler: the resource and returned fields come first, and the market-coverage sentence answers the obvious follow-up question about which instruments work. 'From our own nodes' is a meaningful provenance signal 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 and full parameter coverage in the schema, the description needn't explain return shape or pagination. The main residual gap is ordering / recency semantics for 'latest' trades, which an agent would want before relying on the first element.

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%; both parameters are documented, including the market name formats (BTC-PERP, xyz:NVDA-PERP, HYPE/USDC, @107). The description adds no parameter meaning beyond what the schema already carries, 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 verb+resource ('Latest tick-level trades on a Hyperliquid market') and enumerates the returned fields (price, size, side, block time), plus the market families covered. It never names the closest sibling, get_fills (per-user fills), so the boundary is inferable but not explicit.

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 by 'latest' and 'tick-level' — an agent can guess this is the market-wide recent-trades tool, but nothing says when to prefer it over get_fills or get_candles for aggregation, nor any exclusions or data-freshness caveats.

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=true and openWorldHint=true, so the safety profile is covered. The description adds the scope of what is returned (state, freshness, component health), but says nothing about caching, refresh cadence, or what 'freshness' means operationally — and since an output schema exists, the return-content sentence is largely redundant.

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 naming the resource first and the payload second, with no filler. Every clause carries information.

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

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

With no parameters, a full output schema, and annotations covering safety, the description only needs to establish purpose and scope, which it does. The remaining gap is routing guidance toward the two sibling status tools, which would make selection unambiguous.

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 schema-description baseline applies; nothing about arguments needs explaining. No credit is lost or gained beyond that 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 resource (Ironflow service status) and the three things it reports: overall state, per-venue data freshness, and component health. The phrase 'right now' implicitly separates it from get_status_history and get_status_metrics, though neither sibling is named, so the differentiation is inferential rather than explicit.

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?

'Right now' hints that this is the current-state variant, which points an agent away from get_status_history, but no alternative is named and no condition is given for choosing status versus history or metrics. Usage is implied only.

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=true and openWorldHint=true, so safety is covered. The description adds useful behavioral context beyond them: the default window when no period is supplied, that each point carries a freshness-in-seconds field, and that an aggregate uptime percent is included. It stops short of noting pagination, point density, or rate limits, so it is not fully exhaustive.

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, front-loaded with what the tool returns, then the diagnostic use case, then the sibling routing. Every clause carries distinct information with no padding.

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

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

For a single optional enum parameter with an output schema present, the description covers what is needed: scope, default window, and when to prefer siblings. Nothing required for a correct call 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 single enum parameter already documents '24h' (default) and '7d'. The description's restatement of the default window adds confirmation but no syntax or edge-case meaning beyond the schema, 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?

States a specific verb and resource ('Ironflow's own uptime over the last 24 hours (default) or 7 days') and enumerates the payload (status points, data freshness in seconds, overall uptime percent). It explicitly distinguishes itself from the two nearest siblings, get_status and get_status_metrics.

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 concrete diagnostic trigger: 'Use it to check whether a gap or odd value in other results came from an Ironflow outage.' It then routes the agent away with explicit alternatives — get_status for current status, get_status_metrics for latency and error rates — each with the condition that selects 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered without the description's help. The description adds the meaningful detail that metrics are aggregated over rolling windows rather than being a snapshot, but says nothing about window lengths, refresh cadence, or cost/latency of the call — all relevant for a metrics endpoint.

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 names the domain first and then enumerates metric families. No filler, no restatement of the title, nothing to cut.

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 annotations covering read-only/open-world behavior, the description only needs to establish scope, which it does. The one residual gap is that 'rolling windows' is never sized (e.g. 1m/5m/1h), and since there are no parameters the agent cannot discover the granularity at call time.

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 there is nothing for the description to disambiguate; baseline 4 applies. The description doesn't claim or imply any filtering knobs, which is consistent with the empty 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 (Ironflow performance) and enumerates the concrete metric families — API latency, error rate, ingestion lag, synthetic probe timings — over rolling windows. This clearly separates it from point-in-time siblings like get_status and get_status_history, though it never names those siblings explicitly to make the contrast airtight.

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 phrase 'over rolling windows' hints at monitoring use, but the description gives no explicit when-to-use, when-not-to-use, or alternative (get_status vs get_status_history vs get_status_metrics is never adjudicated). An agent must infer routing from the description alone, which is a real gap given three similarly named 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the metric set and window semantics, but says nothing about pagination, ordering guarantees, or coverage limits beyond what the schema and output schema already carry.

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

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

Two sentences, front-loaded with what the tool returns and followed by the sort semantics. No filler, though the metric enumeration is a bit list-like and 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 description needn't explain return structure, and annotations cover the read-only nature. What remains slightly incomplete is routing relative to the many sibling leaderboard/profile tools, which the description never addresses.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns an extra point by explaining what each sort enum value actually ranks on, giving meaning beyond the schema's terse 'Ranking. Default top' — a real value-add for the ambiguous enum.

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 (traders ranked across all markets) and enumerates the metrics returned, so the agent knows exactly what kind of data comes back. It does not explicitly distinguish itself from close siblings like get_pnl_leaderboard or get_market_leaders, which is the only missing piece.

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 three sort modes are explained with concrete meaning (realized PnL, smallest max drawdown, most recently first seen), which effectively tells the agent which ranking to pick for which intent. It stops short of naming alternatives such as get_pnl_leaderboard, so there is no explicit when-not guidance.

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

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

The annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds real context beyond them: the numbers are recomputed from fills rather than stored, and a 90d window on a very active wallet can take several seconds, which warns the agent about latency. It stops short of stating whether results are cached or how heavy the per-market aggregation is, so it is not fully transparent.

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 paragraph is front-loaded with capability, then routing, then a latency caveat, and every clause is load-bearing. The long enumeration of returned metrics is somewhat redundant given an output schema exists, which keeps it from 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?

For a two-parameter read-only analytics tool with a full output schema, the description covers purpose, alternatives, data provenance, and the one operational pitfall (slow 90d queries). An agent has everything needed to choose and invoke 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 coverage is 100%, so the enum values, the default 30d, and the 0x address format are already documented in the schema. The description reinforces that the window governs the lookback over which all metrics are computed, but adds no new syntax or constraint details. Baseline 3 applies when the schema carries the parameter 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 a specific resource (one Hyperliquid trader) and a specific computed artifact (win rate, profit factor, realized PnL, max drawdown, per-market breakdown, liquidations, trade lifecycle) over named windows. It also states the provenance ('rebuilt from its fills'), so an agent knows this is derived analytics rather than raw records, and it is clearly separable from raw-fill siblings like get_fills.

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 concrete decision rule ('Use it to vet a wallet before following it') plus three explicit exclusions with the condition that selects each alternative: get_user_summary for plain totals over any range, get_user_state for live positions, get_wallet_behavior for style labels. 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral content beyond that: the sign convention for amounts and what the aggregation buckets produce (daily totals vs. raw hourly payments). It doesn't discuss pagination behavior or limits, but with annotations present this is a solid contribution.

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 what the tool returns, then the sign convention, then bucket behavior. No filler and nothing that repeats the schema verbatim without adding meaning.

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-shape detail is unnecessary, and the description covers the two things an agent most needs that the schema can't express: sign interpretation and bucket granularity. The unexplained third enum value ('raw') and the absence of any steering versus sibling funding tools are the remaining small gaps.

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. The description goes beyond the schema's terse 'Aggregation bucket; default 1d' by explaining what 1d and 1h actually yield, which materially helps an agent choose a bucket. Minor gap: the enum also offers 'raw', which the description never addresses and which reads as overlapping with the stated '1h = raw hourly payments'.

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

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

States a specific resource and semantics: funding payments paid or received by a Hyperliquid wallet, broken out per market per bucket. The sign convention ('positive means received, negative means paid') makes the output's direction unambiguous. It doesn't explicitly name how it differs from the nearby get_funding_rates / get_funding_stats siblings, which are market-level rather than wallet-level, so a 4 rather than 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 wallet-scoped funding tool when it has an address and wants payment history. There is no explicit 'use this when…' statement and no routing to get_funding_rates, get_funding_stats, or get_user_ledger for the adjacent cases. The bucket guidance partially compensates by telling the agent how to pick granularity.

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 openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: the sign convention ('positive amounts go into the account') and a retention cutoff for two event classes, which tells the agent the results may be incomplete for a time range. It still omits ordering and what happens when the window exceeds the cap, but it clears the lower bar set by 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?

Two short sentences, zero filler, and the resource identification is front-loaded followed by the two caveats that matter most. The first sentence is a verbless fragment, which slightly blunts the opening, but nothing is padded or repeated.

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 read-only with a fully described input schema and an output schema, so the description need not explain return shapes. What it must add – what the ledger contains, how to read the amounts, and where the data is truncated – is present. Ordering of entries and any implication of the limit cap are the only notable omissions, and those are minor given the rich 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% – every parameter, including the event_types enum values and the timestamp formats, is already documented in the schema. The description adds no parameter-level meaning, so the baseline 3 applies. The one extra hint is implicit: the mention of deposits/withdrawals/transfers hints at the event_types space already spelled out in the schema.

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

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

The description names the specific resource (a Hyperliquid wallet's vault deposits, withdrawals and transfers) with the sign convention, so an agent knows what data comes back. It does not differentiate from close siblings such as get_vault_operations or get_user_state, which also sound ledger-like, so an agent still has to infer whether this is the right tool for plain account cash flows.

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

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

There is no explicit when-to-use or when-not-to-use statement and no sibling is named as an alternative. The one usage-relevant constraint given is a data-coverage caveat (account deposits and withdrawals only recorded up to 2026-06-06), which helps an agent decide whether the tool can answer a recent-activity question, but alternatives for that case are left unnamed.

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=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing what the breakdown contains (volume, fees, rebates) and an interpretive rule for spotting market makers (high maker share with negative maker fees). No mention of default time window or result granularity, 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?

Two tight sentences: the first front-loads what is returned, the second adds actionable interpretation. No filler and 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?

With an output schema present and full parameter documentation, the description needn't detail return values. The remaining gap is that from/to are optional and no default window is stated, which matters for interpreting the result.

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 four parameters are fully documented with formats in the schema. The description only echoes the 'per market' scoping and says nothing about the from/to window conventions, 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 resource and operation: maker vs taker breakdown of a wallet's fills per market, returning volume, fees and rebates. That is enough to distinguish it from generic siblings like get_fills or get_user_summary, though it never names an alternative 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: it's for analyzing a wallet's execution style per market. There is no when-to-use/when-not guidance against close siblings (get_fills, get_wallet_behavior, get_trader_profile), so the agent must infer selection.

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=true/openWorldHint=true, so the safety profile is covered; the description instead adds the semantic trait that matters — results are incremental buckets, not a cumulative series, which the caller must sum. It does not mention limits on range width or how many buckets can be requested, which is the remaining behavioral gap.

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: what it returns first, then the aggregation hint, then the two sibling redirects. No filler, and the most decision-relevant information (realized-only, bucketed) is front-loaded.

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 tool with a full input schema, an output schema, and correct sibling routing, essentially everything needed to call it is present. The only shortfall is no guidance on acceptable window sizes or bucket-count limits, which matters for a time-series endpoint with open-ended from/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 description coverage is 100%, including formats and defaults for from/to/bucket_ms, so the baseline is 3. The description's 'by default daily over the last 30 days' merely restates the schema defaults and adds no new syntax or constraint information about the parameters.

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

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

States a specific verb+resource+scope: realized PnL of one Hyperliquid wallet over time, bucketed, defaulting to daily over 30 days. It explicitly separates itself from get_user_state (unrealized) and get_user_summary (range totals), so an agent can pick it 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?

Names both alternatives and the exact condition that routes to each: unrealized PnL belongs in get_user_state, range totals in get_user_summary. It also implies the correct use case (building a running curve by summing buckets) with nothing 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 readOnlyHint and openWorldHint, so the description only needs to add scope, which it does: a point-in-time snapshot covering both native and HIP-3 perps. It doesn't mention edge cases such as a wallet with no positions or an unsupported address, but the behavioral picture is largely complete.

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, with the scope declared before the usage example. Every clause earns its place and 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-shape explanation is unnecessary; the description supplies the temporal and market-coverage context an agent needs. Only the absence of edge-case or empty-result notes keeps it below 5.

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

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

There is a single required parameter and the schema already documents it fully ('0x-prefixed 20-byte hex address'), so the description adds nothing on this axis. Baseline 3 per the high-coverage rule.

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 (open positions plus unrealized PnL), the scope (native and HIP-3 perps), and the temporal mode ('right now'), which cleanly separates it from siblings like get_user_summary or get_user_pnl_series. An agent can pick it without opening the schema.

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

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

The example question ('is this wallet long or short?') gives a concrete trigger for invoking this tool. It stops short of naming alternatives — nothing says to use get_user_summary for balances or get_fills for historical trades — so routing between the many user_* siblings still relies on 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context by specifying the default time window (last 24 hours) and the exact aggregation output (fill count, volume, realized PnL, fees, wins/losses, win rate, maker/taker share, current account state). It does not discuss rate limits or data freshness, but that is a minor gap given 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 description is two sentences, front-loaded with the tool's purpose and output metrics, followed by a usage example and explicit sibling routing. Every clause earns its place by either clarifying scope or directing the agent to the right alternative; there is no redundant or vague wording.

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 the description does not need to explain return values in detail, yet it still enumerates the key metrics for quick comprehension. With annotations covering safety and schema covering parameters, the description is complete for a read-only wallet summary tool; 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%, so the input schema already documents address format and the accepted formats/defaults for from and to. The description repeats the default window ('last 24 hours') but adds no new syntax or semantic guidance beyond what the schema provides. 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?

The description states a specific verb and resource: 'Totals for one Hyperliquid wallet over a time range', and enumerates exactly what is included (fill count, volume, PnL, fees, wins, losses, win rate, maker/taker share, account state). It explicitly distinguishes itself from sibling tools get_trader_profile and get_user_pnl_series, so an agent can select it 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?

It gives a concrete usage example ('how much did this wallet trade or make this week') and explicitly routes the agent to alternatives for related but different needs: get_trader_profile for scored records with profit factor/drawdown/per-market breakdown, and get_user_pnl_series for PnL over time. When-to-use and when-to-use-something-else are both 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 only cover readOnly/openWorld; the description adds the non-obvious behavioral fact that unauthenticated calls are silently truncated to 24 hours while a free key unlocks the full 7 days, which directly affects result interpretation. It does not discuss pagination or whether the ranking is recomputed live, so not 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?

The ranking definition and window are front-loaded in a single tight clause, then the access caveat. The URL plug is slightly promotional but still carries actionable 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?

An output schema exists, so return structure needn't be explained; what matters — ranking basis, time window, and the auth-dependent data truncation — is all present. Only the interaction between limit and the truncation behavior is left unstated.

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?

Only one parameter and schema description coverage is 100% (limit with default and max already documented in the schema). The description adds no semantics for it, 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 (ranked), resource (Hyperliquid vaults), ranking metric (net deposits = deposits minus withdrawals) and window (last 7 days), plus an included field (depositor counts). This cleanly separates it from siblings like get_vault_operations (per-vault ops) and get_pnl_leaderboard (PnL-ranked).

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?

Implicitly tells the agent this is the leaderboard/ranking entry point rather than a detail lookup, but never names an alternative sibling or states when not to use it. No preconditions beyond the key note are spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the important filter requirement that at least one of vault/address is needed, but it does not add much beyond that about ordering, pagination, or other runtime 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 two short sentences and front-loads the operational scope before the parameter requirement. There is no redundant or filler text.

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 operation-history tool with a full input schema and an output schema, the description covers the key scope and required filter condition. It could be slightly stronger by mentioning pagination or ordering behavior, but it is largely complete.

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 meaningful semantics by clarifying that vault and address can be used individually or together and that at least one is required despite the schema's empty required array. It also provides the HLP vault address as a concrete example.

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 resource and scope: deposit and withdrawal operations for a single vault or a single depositor. It is specific enough to distinguish this from leaderboard or general wallet-history tools, though it does not explicitly name a sibling alternative.

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 key calling constraint that vault, address, or both must be supplied, and gives the HLP address as an example. However, it does not explain when to use this tool rather than related tools such as get_vault_leaderboard or get_user_ledger.

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 (readOnlyHint, openWorldHint), and the description adds the 30-day lookback window and the concrete metric set returned, which the annotations say nothing about. It doesn't mention cost, rate limits, or what happens when an address has no activity, so it earns a 4 rather than 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?

Two sentences, front-loaded with what the tool returns and finished with how to call it. The long parenthetical label and metric lists are dense but genuinely informative since the agent learns the taxonomy without opening the schema; they cost it the top score.

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, a fully documented 5-parameter schema, and annotations covering the safety profile, the remaining description burden is scope and time window, both of which are stated. Only the sibling disambiguation 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 every parameter is already documented, giving a baseline of 3. The description reinforces the addresses-vs-label switch but adds no syntax, format, or default detail beyond what the schema already states (e.g. the 50-address cap and max 100 limit live only in the schema).

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

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

The description names the resource precisely: Hyperliquid wallet trading behavior over the last 30 days, enumerating both the label taxonomy and the underlying metrics. An agent immediately knows what comes back. It stops short of a 5 because a sibling named get_wallet_labels exists and the description never says how these two differ.

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?

'Look up specific addresses, or list wallets with one label' cleanly states the two invocation modes and the condition selecting each, which is real routing guidance. It gives no exclusion or redirect toward get_wallet_labels or get_trader_profile, so the agent must infer sibling boundaries on its own.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context about the default list mode versus targeted address lookup, but it does not disclose rate limits, auth requirements, or data freshness.

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 two efficient sentences with no wasted wording. The main purpose and the key optional-parameter behavior are front-loaded.

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 full schema coverage, read-only/open-world annotations, and an output schema, the description supplies enough context to invoke the tool correctly. It explains what labels are available and how the addresses parameter changes behavior, without needing to restate return values.

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 parameters are already documented in the schema. The description adds meaning for the optional addresses parameter and the default listing behavior, but smart_top_n and whale_top_n are only explained by 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 clearly identifies the resource as labels for notable Hyperliquid wallets and names the covered categories: top whales by volume, top traders by PnL, vaults, and vault leaders. It also explains the optional address-based lookup, though it does not explicitly contrast itself with closely related siblings such as get_top_traders or get_vault_leaderboard.

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 usage guidance for the optional addresses parameter: pass addresses to check specific wallets, omit them to list whales and smart money. It does not explicitly state when to use this tool instead of the many sibling ranking/leaderboard 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 readOnlyHint and openWorldHint annotations already cover the safety and openness profile. The description adds useful scope detail by enumerating the predefined cohorts and mentioning caller-created custom cohorts, but it does not discuss access constraints, pagination, or ordering behavior. With annotations present, this is adequate but not rich beyond structured 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?

The description is a single front-loaded sentence with no wasted framing. The enumerated cohort names are specific and useful for an agent trying to recognize the resource.

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

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

With no input parameters and an output schema present, the description need not explain return values. It gives enough context for a simple catalog listing, though it could more explicitly position this tool relative to get_cohort_addresses.

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 parameter semantics are essentially not applicable. The schema coverage is 100% and the baseline for zero-parameter tools is 4.

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

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

The description states a specific verb and resource: listing available address cohorts. It also enumerates the six predefined cohorts and notes that caller-created custom cohorts are included, making the scope clear. It does not explicitly name or differentiate itself from the sibling get_cohort_addresses, 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?

Usage is only implied: an agent can infer this is the discovery step before fetching cohort addresses. The description does not explicitly say when to use this tool versus get_cohort_addresses or how the two are meant to be sequenced.

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 readOnlyHint=true and openWorldHint=true, so the description only needs to add behavioral context. It mentions page size of up to 100 and cursor-based pagination, but those details are also in the schema, and it does not disclose auth needs, rate limits, or error behavior. The note about live HIP-4 outcomes adds some useful context, but overall the description adds only modest value beyond annotations and 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?

The description is three sentences with the purpose front-loaded, followed by a concrete search example and pagination guidance. It is compact and every sentence contributes useful information without repetition.

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 seven optional parameters, an output schema, and read-only/open-world annotations, the description covers the core task: resolving market names, searching, paginating, and distinguishing live outcomes. The only notable gap is lack of explicit routing guidance versus sibling tools, but the tool is otherwise complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description improves on that with a concrete q search example showing that q=nvda returns xyz:NVDA-PERP and other NVDA perps, which clarifies search semantics beyond the schema. Other parameters are left to their already thorough schema descriptions.

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 explains how a Hyperliquid market is named and enumerates perps, spot, and live HIP-4 outcomes. It is clear what the tool returns, including symbol, class, issuer, base asset, and Hyperliquid coin. It does not explicitly contrast itself with siblings such as get_markets_snapshot, so it falls 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?

The description gives a useful search usage cue with the q=nvda example and explains pagination via cursor. However, it does not explicitly say when to use this tool instead of get_markets_snapshot, get_price, or other market-related siblings, nor does it state when to omit filters. Usage is implied rather than fully guided.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: hard rate limits (5 s per query, 60 query seconds per hour per IP), a 1,000-row result cap, the tier-dependent history window (24 h keyless, 30 days with a key), and the 'no FORMAT clause' constraint. These are exactly the operational facts an agent needs before constructing a query.

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 sentences, front-loaded with the action and the table inventory, followed by the aggregation guidance and then the limits. Every clause carries operational information; nothing is 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?

With an output schema present, return values need no explanation, and the description covers the remaining gaps an agent would hit: which tables exist, aggregation expectation, row caps, rate limits, and how to unlock deeper history. Complete for a read-only SQL passthrough.

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; the description earns an extra point by explaining the practical consequence of max_rows ('results are capped (1,000 rows keyless)') and reinforcing that the sql parameter must be a single aggregate-oriented SELECT. It does not, however, add anything about default 200 vs tier caps beyond what the schema says.

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 one read-only ClickHouse SELECT over Ironflow's Hyperliquid tables') and enumerates the exact hl.* tables available, which is far more concrete than the title. It stops short of 5 because the differentiation from the many prebuilt sibling query tools (get_fills, get_user_summary, etc.) is only implicit through the raw-SQL framing rather than stated.

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

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

'Aggregate in SQL: results are capped (1,000 rows keyless)' implies this tool is for custom aggregation the prebuilt endpoints can't express, and the keyless/key tier note gives practical context. However, there is no explicit statement of when to prefer this over a sibling like get_fills or get_market_leaders, and no when-not-to-use exclusion.

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