LiqFlow

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds semantic value by defining how a cascade is computed (a 4-hour move plus prior liquidation exposure), which goes beyond the annotations. It does not disclose return format, ordering behavior, or result limits, leaving that to the schema.

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

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

A single front-loaded sentence that leads with the core concept and does not pad. Slightly dense with the back-referenced 'min_move_pct' and dash clause, but every part earns its place.

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

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

For a 5-parameter read-only analytics tool with no output schema, the description conveys the concept but omits usage routing and any characterization of returned records. Adequate to understand the metric, but incomplete on when to reach for it over the many liquidation siblings.

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

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

Schema coverage is 60%: coin, sort and min_move_pct carry inline descriptions while days and limit do not. The description reinforces min_move_pct ('at least min_move_pct in one 4-hour step'), adding context on the unit, but adds nothing for coin, days, sort or limit. Baseline 3 is appropriate given the schema does most of the work.

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 analytical resource: past sharp moves paired with the liquidation exposure that sat in their path, framed as evidence about whether clusters get 'run'. This is distinct from siblings like liquidation_map or liquidation_totals, though it never names those siblings to sharpen the distinction. A clear verb+resource, but not explicitly differentiated from its alternatives.

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, when-not-to-use, or routing to alternatives. The phrase 'the evidence for whether clusters actually get run' hints at the analytical purpose, but with siblings like liquidation_map, liquidation_totals and recent_liquidations present, the agent gets no guidance on which to pick. Usage is implied at best.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint, so the safety profile is covered. The description adds a real behavioral detail beyond them: 'Uses 2 API calls without a coin,' which discloses a cost/behavioral difference tied to the coin argument. It still does not mention rate limits or data freshness, 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 core definition is front-loaded and dense with concrete bucket ranges, followed by a short motivating question and an API-call note. Every sentence adds information, though the opening sentence is long and could be split for faster scanning.

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 output schema, the description carries the burden of describing returns, and it does so well: cohort groupings, notional values, and share-long per group. It also discloses the API-call cost. What is missing is guidance on choosing this over sibling positioning tools, but the core content is complete 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% and there is only one optional parameter whose meaning ('omit for all markets combined') is already documented in the schema. The description's phrase 'without a coin' reinforces but does not extend the schema's semantics. 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?

The description names a specific analysis (how trader cohorts are positioned) and enumerates the exact groupings returned — account-size buckets from Micro to Whale and PnL buckets from Highly Unprofitable to Highly Profitable — plus the metrics per group (long/short notional, share long). This distinguishes it from siblings like cohort_top_coins and top_positions without needing to open their schemas.

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

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

The motivating question ('Are whales and the profitable traders on the other side of retail?') implies when the tool is useful, giving the agent a use case. However, it never explicitly states when to prefer this over cohort_top_coins, top_positions, or other positioning tools, nor any prerequisites. Usage is only implied.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds useful context beyond annotations: it describes the returned fields, the overall lean comparison, and that omitting side costs 2 API calls, which helps an agent reason about invocation cost.

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

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

The description is front-loaded with the core question and then covers output fields and API-call behavior. It is dense but efficient, with no obviously wasted sentence, though the first sentence is somewhat long and colon-heavy.

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 output schema, the description helpfully explains the returned metrics such as long/short notional, net USD, share long, wallet count, and cohort lean. It covers the essential behavior for a read-only analytics tool, though it does not describe response ordering or error conditions.

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 in the schema. The description reinforces the meaning of side omission by noting the 2-call behavior without a side, but it adds little parameter detail beyond what the schema provides.

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

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

The description states a specific resource and ranking task: which coins a given trader cohort is most long and short on across every market. It frames the exact question it answers and distinguishes the output from a single-market snapshot by mentioning the cohort's overall lean across all markets.

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 implies when to use the tool, but the description does not explicitly state alternatives or when not to use it versus siblings like cohort_positioning or top_positions. Usage is clear enough from the framing but not 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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful behavior the annotations do not: the result is thinned to at most 60 points, and price is included only 'where the data has it' (i.e., sometimes absent). That downsampling and nullable-price disclosure materially affects interpretation.

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 sentence, front-loaded with the core act (metric history for one market), followed by the two qualifiers that matter (price availability, 60-point thinning). No filler or redundancy.

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

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

There is no output schema, so the description correctly carries the return-shape burden, explaining what is returned (metric history with price, thinned to 60 points). It leaves the days parameter's default/range behavior to the schema, which is acceptable, but a hint about ordering or granularity would have closed the 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 67%, so the schema already documents coin and metric (with enum meanings) while days carries only type/default/bounds. The description's 'a metric's history for one market' loosely maps to coin+metric but adds no format or range semantics for days. Baseline 3 is appropriate given the schema does most of the work.

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

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

The description names a specific verb and resource: returns a metric's history for one market, with price data attached. An agent can tell it apart from the sibling coin_snapshot (current state) by the word 'history', though no sibling is named 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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The agent must infer from the word 'history' that this is the time-series counterpart of coin_snapshot, and nothing tells it whether to prefer this over market_overview or funding for related data.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered; the description's distinctive contribution is the 'Uses 2 API calls' cost disclosure, which is real operational information an agent needs for fan-out decisions. It doesn't state whether the snapshot is cached or how fresh 'right now' is, keeping it below 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 value proposition is front-loaded in the first clause, the enumeration follows, and the routing instruction plus the API-cost note close it out. No sentence is redundant with the schema or the 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?

For a one-parameter, read-only lookup with no output schema, the description effectively stands in for the return value by listing the fields the agent will get back, and adds cost and routing context. It leaves out response shape details such as units or how the liquidation-pressure score is scaled, which would matter for interpreting the output.

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 the schema already documents it at 100% coverage with a concrete symbol format example (BTC, ETH, HYPE, xyz:SKHX). The description adds only that the tool concerns a single market, so the schema is doing the heavy lifting — baseline 3.

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

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

States a specific verb-and-resource with scope: 'everything about one market right now', then enumerates the payload (price, 24h change, liquidation-pressure score, exposure, cluster, rank, delta since previous snapshot). The 'right now' vs 'since the previous snapshot' framing implicitly separates it from coin_history, but it never names a sibling outright, so it stops short of a 5.

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

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

'Start here for any question about one coin' is an explicit routing rule that tells the agent when to select this over the many aggregated siblings (market_overview, cascades, cohort_*) and 'Uses 2 API calls' gives a cost signal for multi-coin loops. No explicit when-not or named alternative is given, so a 4 rather than a 5.

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

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

Annotations already establish read-only, idempotent, open-world behavior, so the bar is lower; the description still adds real substance: rates are normalised to 8 hours, venues are enumerated, the aggregate is open-interest weighted, and the sign convention ('Positive = longs pay shorts') is defined. It stops short of noting caching or rate limits, but that is a minor omission.

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

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

Front-loaded with the resource, then the two modes, then the sign convention. Every sentence carries information; the venue enumeration is slightly list-heavy but justified since it defines the aggregate's scope.

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 output schema, the description must describe the return shape and it does: per-venue normalised rates plus an OI-weighted aggregate in coin mode, and ranked extreme payers in default mode. An agent has everything needed to call and interpret 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 the schema already documents both parameters, making 3 the baseline. The description reinforces the coin/no-coin dichotomy, but adds no syntax, units, or interpretation for 'limit' beyond what the schema states.

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

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

States a specific resource (perp funding rates) and spells out the two distinct operating modes: per-venue + OI-weighted aggregate when a coin is given, and top positive/negative payers when not. No sibling tool covers funding rates, so it is trivially distinguishable from the 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?

The description explicitly conditions behavior on whether a coin is supplied, telling the agent which mode to expect. It does not name an alternative sibling or state when another tool would be preferable, but for this tool the mode selection is the key guidance and it is fully covered.

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 disclose readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the ranking resource and metrics but does not add operational details such as pagination, rate limits, auth, or result ordering beyond what annotations and schema imply.

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 sentence states the tool's output and two ranking modes with zero filler, and the key information is front-loaded. It is appropriately sized for a simple lookup tool.

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

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

With rich annotations and schema constraints for limit, the description is minimally adequate for this simple leaderboard. However, it omits the limit parameter and does not describe what each ranked wallet entry contains, so it is not fully complete for a tool with no output schema.

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

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

Schema coverage is 50%: the 'by' parameter is described in the schema, while 'limit' has no description anywhere. The description repeats the two ranking options already listed in the enum but adds no new syntax, default, or meaning for either parameter, and says nothing about the undocumented limit.

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 ranking operation over a named resource ('Hyperliquid wallets') and two ranking bases, so the purpose is clear. It does not explicitly distinguish itself from nearby ranking/analytics siblings such as open_interest_ranking or cohort_positioning, keeping it 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 no when-to-use condition, no exclusions, and names no alternatives among the many sibling analytics tools. The intended use is inferable from the name, but the definition provides no guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the scope ("every wallet on the node") and the cost signal ("Uses 2 API calls"). It does not mention pagination or rate limits, but for a read-only analytical tool this is solid added value.

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

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

Front-loaded with the core answer and the parenthetical ("longs below = forced sells, shorts above = forced buys") genuinely aids interpretation rather than padding. It runs slightly long and the "2 API calls" note could sit earlier, but every clause carries 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 no output schema, the description must convey what comes back, and it does: liquidation prices, resting trigger orders, banded order-book depth, and biggest clusters. Combined with the annotations and complete parameter schema, an agent has everything needed to invoke and interpret the result correctly.

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

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

Schema description coverage is 100%, so coin, bands, and range_pct are already fully documented with types, defaults, and bounds. The description explains the output shape (bands either side of the mark price) but 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?

States a specific analytical concept (forced orders / liquidation heatmap for one market) with concrete content: liquidation prices, SL/TP triggers, order-book depth in price bands, and top clusters. An agent can immediately tell this produces a spatial liquidation map, not a history or a total, so it is distinguishable from siblings like recent_liquidations and liquidation_totals 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?

Frames the exact question it answers ("where would a move run into cascading liquidations, and how much is there"), which gives clear context for when to reach for it. It does not explicitly name or exclude the alternative sibling tools (cascades, liquidation_totals, recent_liquidations), so it stops short of explicit routing.

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

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

Annotations already establish the safe read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description adds genuinely useful behavior: missed windows appear under `gaps` and are missing data rather than quiet periods. This prevents a real misinterpretation of results. No rate limits, auth, or pagination behavior is mentioned.

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

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

Four short sentences, front-loaded with the core question ('How much was liquidated') and then the two modes, with the gaps caveat last. No sentence is redundant and each carries distinct 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 output schema, the description must carry return-value meaning, and it does reasonably: it describes the ranking contents (long vs short liquidated USD), the series shape (per time bucket), and one output field (`gaps`). It leaves the hours parameter and the exact response fields otherwise unspecified, so it is complete enough but not exhaustive.

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 75% (coin, limit, interval documented; hours not), so the schema does much of the work, but the description adds meaning beyond it: coin switches between ranking and time series, and buckets are the interval of the series. It does not clarify the hours window or the limit/ranking interaction in text.

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

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

The description states a specific verb+resource (liquidation totals) and precisely delineates the two output shapes: a market ranking when no coin is given, and a per-bucket time series when a coin is given. It does not explicitly differentiate itself from siblings like recent_liquidations or liquidation_map, so it stops short of a 5.

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

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

The 'Without a coin... With a coin...' construction tells the agent exactly which mode a given call selects, which is effective when-to-use guidance driven by the coin parameter. However, it never names alternative siblings (recent_liquidations, cascades, liquidation_map) or states when this aggregation is preferable to them.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds real behavioral context beyond them: the cost ("Uses 2 API calls") and the data-availability gap where non-scored markets return node data only (positions, levels, liquidations). No return format or pagination detail, hence 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?

Two sentences, front-loaded with the resource and the resolution purpose, with the scored/non-scored caveat and API-call cost appended. Slightly dense but no wasted clauses.

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 output schema, the description carries the burden of explaining what comes back, and it does: scored markets yield scores/funding/depth/volume, others node data. Cost in API calls is also disclosed. Missing only field-level return detail, which is acceptable for a small registry lookup.

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 a single optional query parameter, and the schema's own description gives examples ("pepe", "bitcoin"). The description adds no matching syntax or filtering nuance 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?

It states a specific resource (market symbols LiqFlow covers) and the concrete job it performs: resolving a human-readable name like "solana" to the venue symbol SOL. That alone separates it from data siblings such as coin_snapshot or funding, which consume symbols rather than resolve them.

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

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

The description clearly frames the use case (name-to-symbol resolution) and explains the scored vs. non-scored split, which tells an agent which markets have deep data downstream. It never names an alternative tool or an explicit 'do not use this for X' condition, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds two genuinely useful behavioral facts beyond that: the cost ('Uses 2 API calls') and a full explanation of how the score is constructed and what its sign means, which is exactly the kind of interpretive context annotations cannot 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?

Purpose is front-loaded in the first sentence, and the score explanation is dense but earns its place by making the returned number interpretable. The trailing 'Uses 2 API calls' is a slightly dangling fact but is short and informative.

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 output schema and only one optional parameter, the description carries the burden of explaining the return value, and it does: score direction, what the two sides represent, and that top markets per side are listed. The main missing piece is any statement of ordering, thresholds, or what a score near zero implies.

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 parameter 'top' is fully documented in the schema (default 5, range 1-20, 'how many markets to list on each side'). The description mentions 'the markets leaning hardest each way' but adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific resource and scope: a market-wide bullish/bearish skew derived from liquidation pressure, plus the hardest-leaning markets each way. It is clearly differentiated in substance from point tools like liquidation_map or recent_liquidations, but it never names a sibling, so an agent must infer the boundary itself.

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 whole market in one reading' implies this is the aggregate/summary tool, which is useful framing, but there is no explicit when-to-use statement, no when-not-to-use, and no routing to alternatives such as liquidation_totals or open_interest_ranking. Usage is implied rather than stated.

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

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

Annotations already declare this as read-only, idempotent, open-world, and non-destructive. The description adds useful scope context by saying the data includes positions from every wallet on the node and reports how many positions are open in each market, but it does not disclose ordering direction, freshness, or pagination 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 a single front-loaded sentence with no filler. It efficiently conveys the resource, ranking metric, currency, and included position-count detail.

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 low-complexity read-only ranking tool with rich annotations, the description covers the core data and source scope. However, it omits the limit parameter behavior and does not clarify ordering or completeness/pagination, which an agent needs to invoke it predictably without an output schema.

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

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

The only parameter, limit, is not mentioned in the description, and the schema provides no textual description for it despite having default/minimum/maximum constraints. The description does not compensate for the 0% schema description coverage by explaining result count or default/maximum behavior.

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-like operation and resource: markets ranked by open interest in USD, with position counts. It is clearly more specific than a generic market list, but it does not explicitly distinguish itself from siblings such as market_overview, list_markets, or top_positions.

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 guidance on when to use this ranking versus alternatives like market_overview, list_markets, or top_positions. The intended use is only implied by the phrase 'ranked by open interest'.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: freshness ('straight off the node'), ordering ('newest first'), and the crucial data-model caveat that one liquidation can span several fills sharing an order id, which affects counting/dedup.

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, front-loaded with the resource and its ordering, then the one non-obvious data caveat. No filler and nothing redundant with the schema.

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

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

No output schema exists, so the description usefully sketches the return shape (who, market, size, price). Safety is covered by annotations, but the undocumented hours and limit parameters and any pagination/truncation behavior are not addressed, leaving a small gap for a 5-parameter filter 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 60%: coin, side and min_usd are documented in the schema, while hours and limit have no descriptions at all. The description adds no parameter-level meaning (no defaults, no units, no filtering semantics beyond what the schema titles carry), so it neither compensates for the gap nor earns above baseline.

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

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

States a specific verb+resource with granularity and ordering: 'individual Hyperliquid liquidation fills, newest first'. The word 'individual' implicitly distinguishes it from aggregate siblings like liquidation_totals and liquidation_map, so an agent can route 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?

The granularity hint ('individual ... fills') implies this is the per-fill alternative to the aggregate liquidation tools, but no sibling is named and no when/when-not condition is given. Usage must be inferred from the contrast in scope.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context that data is read live from the node and lists the exact returned fields, but it does not mention rate limits, pagination, or authentication behavior. With annotations carrying the safety burden, this is adequate but not rich.

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

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

It is a single, front-loaded sentence that states the core resource first and then enumerates returned fields after a colon. There is no filler, though the long field list makes it slightly dense and less scannable than a perfectly structured entry.

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 simple query tool with 100% schema coverage and no output schema, the description compensates by listing the returned fields (wallet, size, notional, entry, leverage, liquidation price, unrealised PnL, cohort). Annotations cover safety, so an agent has enough to call it correctly, though sibling-routing guidance is missing.

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

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

Schema coverage is 100%, so all three parameters (coin, side, limit) are fully documented in the schema, including defaults, enum values, and the per-side meaning of limit. The description adds no syntax or constraints 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?

The description states a specific resource and scope: the largest open positions on Hyperliquid, with longs and shorts, plus a full enumeration of returned fields. It is clear enough to distinguish from sibling tools like leaderboard or open_interest_ranking, but it never explicitly names or differentiates itself from any sibling, 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?

There is no guidance about when to use this tool versus alternatives such as open_interest_ranking, cohort_positioning, or leaderboard. The description describes what the tool returns, not when an agent should choose it, and provides no 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real context beyond them: 'read live from the node' discloses data freshness (not cached), and since there is no output schema it usefully enumerates the returned fields including leverage, liquidation price and distance-to-liquidation. It omits error behavior for an invalid or empty wallet and any rate limits.

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 opens with the scope ('One Hyperliquid wallet right now') before the colon-list of contents. The enumeration is long but each item is informative, and it is justified because no output schema exists to carry the return shape.

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 tool with no output schema, the description adequately conveys the return payload (account value, PnL, positions, orders). It stops short of covering edge cases such as invalid addresses, wallets with no positions, or limits on the number of orders returned.

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 'address' parameter is fully documented as 'Hyperliquid wallet address, 0x...' in the schema. The description adds no format, validation or example detail beyond that, 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 resource and verb: read the live state of one Hyperliquid wallet, enumerating account value, PnL, positions and open orders. The 'One Hyperliquid wallet' framing implicitly scopes it against market-wide siblings like top_positions and leaderboard, but no sibling is named 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?

The description says what the tool returns but never states when to use it versus alternatives (e.g. top_positions for market-wide views, leaderboard for ranking traders). No prerequisites or exclusions are given; the agent must infer the per-wallet use case from the word 'One'.

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