whale-data

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context by noting these are executed rather than projected liquidations, that results are split long versus short, and that the data is descriptive market data only. It also mentions identical data and credit cost for the plain-English alias, which is useful beyond the annotations.

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

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

The description is compact and front-loads the core distinction ('ALREADY recorded'). The alternative routing is concise, though the sentence about the plain-English name is slightly awkward and could confuse the agent given the sibling tool named 'liquidations'. Still, overall it is tight 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?

The output schema exists, so return-value details need not be in the description. Param semantics are fully covered by the schema, and annotations cover safety/idempotence. The description supplies tool-selection context, scope, and enough behavioral framing to make the tool confidently invokable.

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 documents all four parameters well. The description adds little directly about parameter semantics, but the 'one pair' and 'split long versus short' context helps frame the coin/pair parameters. This aligns with the baseline 3 for high schema coverage.

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

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

The description clearly states the tool returns forced closes already recorded for one pair, split long versus short, and explicitly contrasts it with projected levels and whole-market liquidations. This gives a specific verbless but unmistakable resource scope and distinguishes it from sibling tools like liq_zones and market_liquidations.

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 tells the agent when to use alternatives: liq_zones for projected liquidation levels and market_liquidations for the whole market. It also clarifies this tool is for executed, per-pair liquidations, providing both an inclusion and exclusion 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, idempotentHint, and destructiveHint. The description adds meaningful behavioral context beyond those: 'Descriptive market data only' and the nuance that news is 'offered as one candidate explanation, never asserted as the reason.' This fully aligns with the annotations and enriches them.

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

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

The description is compact and front-loaded: first sentence defines what the tool returns, second gives usage triggers, third provides sequencing and a caveat. It is slightly dense but every sentence earns its place.

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

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

Covers purpose, output contents (headlines, sentiment range, macro picture), when to use vs alternatives, sequencing after market-structure tools, and the descriptive-only nature. With an output schema present and annotations covering safety, nothing essential is missing for an agent to select and invoke the 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 the baseline applies. The description reinforces the 'one coin' scope but does not need to detail parameters because the schema already documents the coin default, pair alias, and the covered:false/null sentiment 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 and resource: provides recent crypto headlines with a pre-computed sentiment score for one coin plus the macro picture. It also distinguishes itself from the many sibling market tools by explicitly centering on news/sentiment and naming market_brief / whale flow / liquidations as related but different tools.

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

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

Gives explicit when-to-use guidance: 'when a move might be NEWS-driven' or when the user asks what is being said about a coin. It also tells the agent when not to rely on it — only AFTER a market read has ruled out market-structure causes — and clarifies that news should be a candidate explanation, never asserted as the reason.

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, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: keyless access, descriptive market data only, and clarifies that 'count' and 'total_usd' cover exactly the returned rows with a 'window' field, avoiding misinterpretation of fixed 24h figures. This exceeds the annotation baseline.

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, each dense with information: scope, event distinction, and metric semantics. No fluff, front-loaded with the most important purpose, and every sentence earns its place.

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

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

Given an output schema exists and annotations cover safety, the description covers scope, event type, chain availability, metric semantics, and alternative tool differentiation. It is complete for a read-only filtered tool with simple parameters.

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

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

Schema description coverage is 100% for both parameters, providing full documentation. The description further clarifies the 'limit' parameter's behavior (defaults, hard ceiling) and the 'chain' parameter's refusal behavior, adding value beyond schema. Baseline 3 is elevated to 4 due to meaningful extra context.

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 ('repaid debt and seized collateral') and clearly names resources (Aave V3, Morpho Blue on Ethereum, Arbitrum, Base). It distinguishes from the sibling 'liquidations' tool by explicitly saying it's a different event and never summed with one.

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 provides clear context on what the tool covers (lending liquidations vs perp liquidations) and names the alternative 'liquidations' tool for perp liquidations. It does not explicitly say 'when not to use' beyond the differentiation, but the guidance is specific enough to select correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond that: keyless access returns totals and a short token list with swap USD withheld, while a paid plan returns the full table. It also notes 'Descriptive market data only,' clarifying the nature of the data. No contradiction with annotations.

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

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

The description is compact yet information-dense: first sentence defines the resource and outputs, second sentence provides usage context with example questions, third sentence covers access limitations and alternatives. Every sentence earns its place, and no filler 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?

Given that the tool has no parameters, annotations already cover safety and idempotency, and an output schema exists, the description supplies all extra context an agent needs: content, usage intent, alternative routing, and access-tier behavior. Nothing material is missing.

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

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

The tool has zero parameters, so there is nothing for the description to document. The baseline for a parameterless tool is 4, and the description correctly focuses on behavior and output rather than inventing parameter guidance.

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

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

The description clearly identifies the tool as a one-call on-chain DEX state summary across Ethereum, Base, and Arbitrum, listing concrete outputs like 24h volume, TVL, top tokens, and whale swap activity. It also explicitly distinguishes itself from sibling tools by naming onchain_whales and whale_profile as alternatives, making purpose unambiguous.

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

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

The description explicitly states when to use this tool ('Use this for the DeFi / on-chain picture') with concrete example queries, and gives clear routing guidance: for individual wallets use onchain_whales, for CEX whale flow use whale_profile. This is explicit when/when-not guidance with named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable context beyond annotations: the 7% coverage limit, the meaning of tracked:false, and the 'descriptive market data only' caveat. No contradiction with annotations.

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

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

Three sentences, each purposeful: the first states the tool's function, the second disambiguates from a sibling, and the third discloses the critical coverage limitation. No wasted words; information is front-loaded and directly relevant.

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

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

Given the output schema exists (so return values are documented) and annotations cover safety, the description provides the essential remaining context: the tool's scope (Ethereum/Base/Arbitrum), the sibling distinction, and a realistic coverage limitation that affects interpretation. This is complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already fully describes both parameters, including address format and limit defaults/cap. The tool description reinforces the address/vs Hyperliquid distinction but does not add new parameter-specific meaning beyond what is in the schema, so baseline 3 is appropriate.

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

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

The description opens with 'One Ethereum, Base or Arbitrum address: its recorded DEX swaps, net flow per token and activity pattern,' clearly identifying the resource (wallet address) and specific actions (DEX swaps, net flow, activity pattern). It also explicitly distinguishes from hl_wallet, ensuring no confusion among 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 explicit direction to use hl_wallet for Hyperliquid accounts ('For a Hyperliquid ACCOUNT use hl_wallet instead') and warns about the 7% coverage limit with the instruction to 'state it once when the answer turns on it,' which guides when and how to interpret results. This is strong usage 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 mark the tool read-only and idempotent; the description adds useful context on top by noting that data is logged live and never backfilled, which shapes expectations about data availability and freshness. The 'Descriptive market data only' note reinforces the non-actionable nature of the data. No contradiction with annotations.

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

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

The description is one tight sentence that front-loads the central concept and adds only one clarifying caveat: 'Descriptive market data only.' Every clause carries information 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?

Given full parameter documentation, an output schema, and read-only annotations, the description covers the essential context: time scope, live-only provenance, and outcome fields. The main gap is the lack of an explicit pointer to the closely named sibling signal_outcomes to guide selection.

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?

All five parameters have detailed schema descriptions, so the schema carries the full semantic load. The free-text description adds no parameter-level guidance beyond referring to recently fired flags and later outcomes, which earns the baseline score for high schema coverage.

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

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

The description names a concrete resource—recently fired signal-ledger flags—and specifies the data shape: fire-time price and later price outcomes. It is clear at a glance, but it does not explicitly distinguish flag_outcomes from the similarly named sibling signal_outcomes.

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 phrases 'Recently fired' and 'never backfilled' imply this tool is for live, recent signal flags and not for historical or corrected data, which provides some usage context. However, it never names alternatives or states when to prefer signal_outcomes, so the guidance remains implied rather than explicit.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds useful behavioral context beyond that: 'Keyless on any streamed pair' reveals authentication and streaming-pair requirements, and 'Descriptive market data only' reinforces the non-mutating nature. It also discloses that prediction and payout time appear only 'where the venue provides it,' which helps set expectations about variable output.

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

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

The description is compact and front-loaded: output first, usage guidance second, alternatives third, and access/reliability notes last. Every sentence adds value, and the example queries make selection immediate without bloat.

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

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

Given the output schema exists, the description need not restate return fields. It covers what the tool returns, when to use it, when not to use it, which siblings to route to instead, authentication requirements, and data classification. That is complete for a read-only market-data 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%, with coin described as 'Alias for pair' and pair described with an example. The description adds the 'one pair' and 'streamed pair' context but does not materially expand parameter meaning beyond what the schema already provides. The baseline of 3 is appropriate.

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

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

The first sentence states a specific function: 'Per-venue funding rates for one pair, side by side' including predicted next rate and payout time. It clearly distinguishes from sibling tools like market_brief and market_history by describing what this tool covers versus what those cover.

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

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

The description explicitly says 'Use this when the user asks about funding across exchanges, where funding is most extreme, or where perp longs vs shorts are paying' and gives concrete example queries. It also tells the agent when not to use it: for single average funding, use market_brief; for historical comparisons, use market_history/market_extremes.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds meaningful behavioral context: the keyless vs. paid access difference, that keyless returns only top rows and states withheld counts, and that this is 'descriptive market data only.' No contradiction exists.

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

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

The description is compact yet information-dense: it leads with the core data content, gives concrete usage examples, then routing to alternatives, and closes with access-tier behavior. Every sentence earns its place and there is no fluff.

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

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

For a zero-parameter tool with an output schema, the description is fully complete: it defines the data, gives usage context, differentiates from relevant siblings, and explains access limitations. Nothing an agent needs to correctly select and invoke this tool is missing.

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

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

The tool has zero parameters and the schema already covers everything, so the baseline is 4. The description compensates by explaining what the returned board contains and the kinds of questions it answers, which adds semantic value beyond 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?

The description clearly identifies the tool as an aggregated view of tracked Hyperliquid whale accounts, listing the exact data dimensions (equity, open notional, leverage, net bias, per-coin crowding). It also distinguishes itself from sibling tools like hl_wallet and hl_whales, so an agent can confidently select it for positioning questions.

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 states when to use this tool ('how the tracked HL whales are positioned right now') with concrete example queries, and also names alternatives for different intents: hl_wallet for a specific wallet, smart_money or hl_traders for profitable traders, and hl_whales for recent fills. This is explicit when/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?

Beyond the readOnly and idempotent annotations, the description discloses methodology (screened from primary closing fills), claim limitations (stage-1 claim, equity/ROI not verified), metric semantics (profitableCloses counts distinct closing actions not partial fills), and access behavior (Keyless returns top rows and withheld count; paid plan returns whole board). This is rich behavioral context.

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

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

The description is dense but well-structured: definition, verification caveats, metric definitions, and access behavior. It is front-loaded with the core purpose and every sentence adds non-redundant information.

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

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

Given no parameters, a read-only annotation set, and an existing output schema, the description covers the essential operational details: what is screened, what is not verified, how metrics are counted, and how access differs by plan. It is complete for correct selection and use.

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

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

The input schema has zero parameters, so there is no parameter burden for the description. Baseline for no parameters is 4; the description appropriately uses its space to explain output and data semantics instead.

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 defines the tool's purpose: finding every Hyperliquid wallet that has closed a trade and screening for net-of-fees realized profit and human trade pace. It also explicitly distinguishes itself from smart_money and hl:proven, so an agent can tell them apart.

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 states when this is useful ('a profitable trader outside the venue's ranked leaderboard is still found') and gives an explicit when-not: equity, ROI, and market-maker volume ratio are not verified, making this a weaker and different claim than smart_money or hl:proven. Naming the alternatives and the limitation provides clear routing guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds useful behavioral detail beyond those flags: it explains keyless access to live data, paid-plan restrictions for computed history and full fill trails, and closes with 'Descriptive market data only.' This gives the agent a clearer model of data availability without contradicting annotations.

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

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

The description is compact and front-loaded with the core purpose, followed by access-tier nuances. Every sentence contributes useful information, though the final sentence 'Descriptive market data only' is somewhat redundant given the readOnly annotation.

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 tool with a full input schema, an output schema, and safety annotations, the description provides the remaining context needed: it clarifies keyless vs paid data access, the account-scoped nature, and the read-only character. No critical gap remains for an agent to 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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds thematic context around 'recent whale-sized fills' that maps to the limit parameter, but it does not meaningfully extend the schema's parameter explanations.

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: a single Hyperliquid account's live positions, equity, leverage, net bias, unrealized PnL, and recent whale-sized fills. It differentiates from market-wide or multi-account tools by emphasizing 'One Hyperliquid account,' though it does not explicitly name a sibling tool for comparison.

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 provides implied usage context by noting that live data is keyless while computed history and the full fill trail require a paid plan. However, it does not explicitly state when to prefer this tool over alternatives like hl_whales or whale_profile, nor does it mention 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond those structured fields: every row is followable to a live book, the feed names accounts on both sides, and the data is descriptive market data with no state mutation. This helps the agent understand the nature of the data without contradicting 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 efficient and front-loaded. It states the core behavior in the first sentence, then adds one sentence of unique source context, one sentence of use-case guidance, and one sentence of sibling routing. There is no wasted wording or repetition of schema details.

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, read-only tool with three optional parameters, full schema coverage, and an output schema, the description is complete. It tells the agent what the tool does, why it is unique, when to use alternatives, and that no authentication is required. Nothing important is left to inference.

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 of 3 applies. The description does not itself elaborate on coin, pair, or limit, but it also does not need to: the schema already documents the coin matching behavior, the pair alias, and the limit ceiling and default. No extra parameter semantics are missing.

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

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

The description opens with a specific verb+resource statement: returns recent whale-sized Hyperliquid fills with wallet addresses attached. It clearly distinguishes this tool from siblings by emphasizing that Hyperliquid's public feed names both sides of every fill, which is unique among the alternative whale-data tools.

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

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

The description gives an explicit use case ('which HL whales just bought BTC') and names the relevant alternatives for different queries: hl_wallet for one wallet's book and leverage, hl_board for ranked tracked accounts, and smart_money for proven-profitable traders. It also notes the tool is keyless, making invocation prerequisites clear.

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

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

The description goes well beyond the annotations by explaining live tape merging, restart persistence, the mapping of sell-side events to long liquidations, count vs dollar fields, truncation semantics, and the read-only market-data nature. This is 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?

The description is dense but every sentence earns its place, covering scope, field meanings, parameter behavior, and edge cases. It is front-loaded with the core purpose and avoids fluff.

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

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

For a read-only, pair-scoped liquidation data tool, the description covers parameter semantics, output field meanings, truncation edge cases, and the descriptive-only nature. With a full output schema and strong annotations, nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying how hours behaves, what window_minutes represents, and the meaning of output fields like truncated and total_in_window, going beyond the raw schema definitions.

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: liquidation trades for a pair with long/short breakdown. It adds concrete details about event counts vs dollar splits, making the purpose unmistakable, but it does not explicitly differentiate this tool from close siblings like coin_liquidations or market_liquidations.

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

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

The description gives clear usage context: pass hours to request a period, omit it for recent rows, and explains window_minutes and truncated behavior. It does not explicitly state when to prefer this tool over alternatives, but the pair-scoped descriptive nature is clearly conveyed.

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 idempotentHint=true. The description adds meaningful behavioral context beyond the annotations: the data is a projection, not executed trades, and the returned data depends on keyless vs. paid access.

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 carry substantial information with the key identity of the tool front-loaded in the first clause. The phrasing is efficient, though 'clearly labeled as a projection, not executed trades' is slightly redundant with 'modeled from leverage assumptions.'

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

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

Given the annotations, output schema, and 100% parameter schema coverage, the description covers the essential context: purpose, one-pair scope, projection nature, and access-tier differences. Nothing critical is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents coin as an alias for pair and pair's default and bare-symbol handling. The description reinforces the keyless/paid behavior but adds little new parameter meaning beyond the schema.

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

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

The description names a specific resource: a projected liquidation level book for one pair, and explicitly distinguishes it from executed trades by saying it is modeled from leverage assumptions. This clarity separates it from sibling liquidation tools that likely report actual liquidation events.

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

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

The description gives clear usage context: keyless callers receive free pairs without cascade chains, while paid plans get the full snapshot for any pair. It does not name specific alternatives or explicit when-not-to-use conditions, but the one-pair scope and access-tier behavior guide selection adequately.

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 provide readOnly, idempotent, and non-destructive hints; the description adds that the tool is descriptive only, that data and credit cost are identical to trade_context, and that it is a one-call aggregation. These are meaningful behavioral clarifications beyond the annotation booleans.

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

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

Three sentences with no filler: the payload is front-loaded in sentence one, the sibling-alias and credit note in sentence two, and usage/exclusion guidance in sentence three. Every sentence earns its place.

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

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

Given the rich output schema and detailed input schema, the description covers scope, alias, credit cost, exclusions, and use case. Nothing needed to choose or invoke the tool 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 schema already documents coin, pair, and position_usd. The description reinforces the 'ONE coin' scope but does not need to add parameter-level detail; 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?

Description states exactly what it returns ('complete current market brief for ONE coin in a single call') and enumerates the data categories: price, funding with carry, open interest, whale flow, liquidations, historical context. It also differentiates from the identical trade_context sibling and from granular whale/funding/liquidation tools.

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

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

Gives explicit when-to-use framing ('general what is happening with BTC / how is ETH positioned question') and explicit when-not-to: do not also call separate whale, funding, or liquidation tools unless the user drills in. This is exactly the routing guidance an agent needs.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, so the description does not need to repeat safety traits. It adds value by detailing the call's behavior: it returns a composite of risk regime, whale flows, unusual coins, movers, and forced-close picture, and explicitly notes perp/lending are kept separate. A minor gap is not specifying the exact recency window, but the output schema likely covers return details.

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 with no wasted words. The first sentence front-loads the core promise and content list; the second effectively differentiates the tool from market_digest. Every element earns its place and the length is appropriate for the complexity.

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 no-parameter tool with an output schema, the description fully covers purpose, scope, and positioning among many sibling tools. The only minor ambiguity is the vague time window ('recently'), which is likely intentional for an on-demand brief but could be tightened. Overall it is complete enough for an agent to select and invoke the tool correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameter ambiguities to resolve. The description instead lists the informational content of the call, which is all that is needed. It deliberately conveys no extra parameter detail because none exists.

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

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

The description opens with a clear verb+resource framing ('What changed across the market recently, in one call') and enumerates the specific data categories covered. It also distinguishes itself from sibling market_digest by framing the use case as on-demand versus timer-driven, which sets it apart from other market brief tools.

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

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

The description explicitly names market_digest as the same one-call brief intended for a timer, positioning market_changes for on-demand questions like 'what changed since this morning / overnight.' It also states 'Descriptive market data only,' giving the agent clear expectations about scope without needing to infer.

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

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

The description adds behavioral context beyond the annotations by stating 'No arguments; returns everything in one payload' and 'Descriptive market data only.' This tells the agent this is a read-only, non-executing aggregate snapshot, reinforcing the readOnlyHint and destructiveHint. It does not detail output schema specifics, but the output schema exists, so the added context is sufficient.

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 core purpose and usage context, then lists the payload contents in a compact series. Every clause adds information, with no filler or 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?

For a zero-parameter tool with an output schema, the description is complete: it defines when to use it, what it returns, that it is safe/descriptive, and that no arguments are needed. The absence of explicit return-field details is acceptable because the output schema exists.

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 are zero parameters, so the baseline is 4. The description explicitly confirms 'No arguments,' which is the only parameter-related information needed. Nothing is left ambiguous about the input surface.

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 clear purpose: a one-call market brief for scheduled or recurring runs. It enumerates the exact content (BTC risk regime, whale net flows, Smart Money Radar coins, biggest movers, 24h forced-close picture) and explicitly contrasts with a single-purpose tool by calling itself 'one-call' and 'everything in one payload.' This distinguishes it from the many focused sibling tools.

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

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

The description says this is for 'a scheduled or recurring run' and that 'an automation can ask it on a timer,' which gives clear context for when to use it. It does not explicitly name alternatives or when-not-to-use conditions, so it stops short of a full 5.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that data may be stale, pointing to as_of_day and stale fields, and notes that next-day outcome stats exist only where enough events are available. This is useful context beyond annotations, though it does not fully explain how to interpret staleness.

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 core purpose, followed by a clear caveat about data staleness. Every sentence earns its place with no redundancy.

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

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

With no input parameters and an output schema available, the description need not explain return values. It covers the key elements: what the tool reveals, the staleness caveat, and the descriptive-only nature. It could clarify what 'pairs' refers to, but that is domain-specific context rather than a critical 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?

The tool has zero parameters, so the baseline is 4. The description mentions as_of_day and stale but these are response fields, not inputs. No additional parameter semantics are needed.

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

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

The description clearly states it identifies pairs at record highs/lows or in the top/bottom 5% for funding, open interest, or liquidations relative to their own history, and provides next-day outcome stats. This is a specific, resource-focused purpose that distinguishes it from siblings like market_overview or market_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?

It provides context that the tool covers the latest recorded day, not necessarily today, and instructs to check as_of_day and stale before treating data as current. However, it does not explicitly name alternative tools or state when not to use it, 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 convey readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context by disclosing archive coverage limits, keyless versus paid plan access, and the read-only nature of the data. The schema further discloses settlement delay and as_of/data_age_days, but the main description still adds meaning beyond the annotations.

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

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

The description is three tight sentences that front-load the core purpose and data fields, then add archive dates, access limits, and read-only status. No sentence is wasted and no important detail is 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?

For a read-only historical data lookup with no required parameters, an output schema, and detailed parameter documentation, the package is complete. The description plus schema covers lane selection, defaults, archive windows, keyless vs paid caps, and the data freshness caveat.

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

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

Schema description coverage is 100%: all three optional parameters are thoroughly documented, including lane selection, pair defaults, coin overriding pair, the days cap, and the capped response field. The main description largely restates what the schema already covers, so a 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 states exactly what the tool returns: daily history with funding rate, open interest, price, and liquidation totals for one pair, or daily whale buy/sell flow for one coin. This is a specific verb+resource description and clearly distinguishes the tool from the many snapshot, news, and flow-focused siblings.

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

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

The description gives clear usage context: historical daily data for one pair or one coin, archive start dates, keyless 30-day coverage versus paid full archive access, and a read-only 'descriptive market data only' note. It does not explicitly name alternative sibling tools or state when-not-to-use, so it stops 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?

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses critical caveats: data only from venues publishing liquidation feeds, the Hyperliquid share is a sample, totals are a floor, and long dollars represent sell-side pressure. This is exactly the kind of behavioral context annotations do not provide.

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

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

The description is dense but every sentence adds unique value: scope, data caveats, separate lanes, and interpretation. It is structured logically, starting with the definition, then limitations, then usage warnings, and ending with a clarifying statement about descriptive data. 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?

Given the tool has an output schema and zero parameters, the description carries the responsibility of explaining the nuanced data behavior. It covers data provenance, aggregation method, the floor nature of totals, the unique named_liquidations, and the separation of lending liquidations. This is complete for a tool of this complexity.

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

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

The input schema has zero parameters, so the baseline is 4 per the rubric. The description does not need to add parameter detail because there are none, and the schema coverage is effectively 100%.

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

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

The description opens with a specific verb and resource: "The whole market's forced closes in one call rather than per pair." This clearly distinguishes it from per-pair liquidation tools, and the detailed breakdown (24h dollars/counts, long vs short, hourly, ranked by coin) makes the tool's purpose unambiguous.

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

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

The description states the tool is market-wide rather than per-pair, implying it should be used when a whole-market view is needed. It also provides an explicit when-not: lending_liquidations must never be added to perp numbers. However, it does not name specific sibling tools as alternatives, so it stops short of the highest bar.

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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context: it is 'Descriptive market state, never a prediction', includes volume so thin-volume moves are visible, and scopes to the streamed top-~300 board. No contradiction with annotations.

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

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

The description is densely functional and front-loads the core definition, then provides routing and caveats. The final two clauses ('Descriptive market state, never a prediction. Descriptive market data only.') are slightly redundant, but overall the length is justified by the amount of guidance.

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

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

Given the presence of an output schema, full parameter documentation, and annotations, the description covers all critical aspects: scope, content, use cases, alternatives, and non-predictive nature. Nothing essential is missing for an agent to select 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% and both parameters (only, limit) are fully described there, including enum values, defaults, and cap. The description does not add meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description names a specific resource ('biggest 24h gainers and losers across the streamed top-~300 board') and a concrete purpose (momentum discovery). It clearly distinguishes itself from siblings by naming market_brief, market_screener, and whale_radar for other use cases.

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

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

It gives explicit 'Use this for' scenarios with example queries, and explicitly states which alternative tool to use for WHY, cross-filtering, and whale flow. This leaves little ambiguity about when to select this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral note with 'Descriptive market data only' and implies no side effects, but it does not disclose pagination nuances or the available:false fallback, which are only in 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?

Two tight sentences cover the tool's data scope, the single-row mode, and the non-mutating nature. Every clause earns its place, and the most important information 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 overview tool with no required parameters and a full output schema, the description is nearly sufficient: it explains the purpose, the optional coin shortcut, and that data is descriptive. The only notable gap is lack of explicit guidance on when to prefer this tool over sibling overview-style 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%, so the schema already documents coin, pair, and limit thoroughly. The description reinforces the coin behavior and 'no paging needed,' but adds little meaning beyond what the input 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 action ('One-call market scan') and enumerates distinct resources: totals, whale net flow, BTC risk regime, and top rows by volume. This makes the tool's purpose clear, though it does not explicitly contrast itself with close siblings like market_snapshot or market_digest.

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

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

It gives clear context for the default board and a direct instruction for the coin parameter ('Pass coin to get one symbol's row directly'). It does not, however, say when to choose this tool over its many siblings or when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is established. The description adds the key behavioral nuance that band comparisons are 'vs each pair's OWN recorded days' and that the whale-flow multiple is relative to the coin's own average, which is useful context beyond the annotations. However, it doesn't describe pagination, rate limits, or exact output behavior beyond what schema/output schema already provide.

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 dense two-sentence structure that front-loads the core action ('Screen every recorded pair') and then lists filters. It earns its length by conveying the discovery call scope and relative-band logic, though the parenthetical enumeration of band values (record high, top 5%, etc.) duplicates schema content and could be shortened without losing value.

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 has 6 parameters, no required ones, full schema coverage, an output schema, and clear read-only annotations. The description supplies the missing high-level context: this is the cross-market discovery screen ('every recorded pair in one call') and filters are self-relative. It is complete enough for an agent to decide when to invoke and what to expect, without needing to explain return values due to the output schema.

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

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

All 6 parameters have complete, detailed descriptions in the schema (100% coverage), so the description does not need to compensate. The description reiterates filter concepts like 'funding_band / oi_band' and 'whale_mult_min' but adds no new parameter-level meaning beyond summarizing what the schema already documents. 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 opens with 'Screen every recorded pair in one call', giving a specific verb, resource, and scope. It then enumerates the filtering dimensions (funding/oi bands, whale-flow multiple, radar-unusual) and ends with 'The discovery call. Descriptive market data only.', which distinguishes it from other market tools like market_snapshot or whale_trades.

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 'The discovery call' clearly signals when to use this tool: when exploring across all recorded pairs. It also notes 'Descriptive market data only', excluding trade execution or data modification. However, it stops short of explicitly naming alternatives for different use cases (e.g., 'for pair-specific data use market_snapshot'), so it lacks formal exclusion guidance.

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

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

Annotations already signal read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by disclosing the keyless vs. paid plan coverage and stating "Descriptive market data only," which reinforces the read-only nature. It also notes that data comes "from the venues that publish them," giving agents insight into data sourcing without contradicting 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 three short sentences with no redundant phrasing. It front-loads the core purpose and data fields, then covers access and read-only nature efficiently. Every sentence contributes meaningful information without waste.

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

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

For a simple, read-only snapshot tool with an output schema and strong annotations, the description covers the essential context: what data is returned, access level requirements, and the descriptive nature of the call. It does not cover alternative selection, but that falls under usage guidance; the tool can be invoked correctly based on this description.

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 fully documents both 'coin' and 'pair' parameters, including defaults and access implications. The description does not add parameter-level detail beyond the schema; 'pair' is implied by "for a pair," but this is already well-covered. 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 clearly states the tool's specific function: "One-call market state for a pair" and enumerates the exact data fields (last price, 24h stats, average funding rate, open interest, recent liquidation totals). It names the resource (pair) and uses a specific verb, making the purpose straightforward, though it does not explicitly differentiate from siblings like market_brief or market_overview beyond its 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?

The description gives access-tier guidance ("Keyless calls cover the free pairs; a paid plan covers every streamed pair") and labels the tool as "Descriptive market data only," but it provides no guidance on when to use this tool versus alternatives such as market_brief, market_digest, or market_overview. No exclusions or alternative selection criteria are mentioned.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral context: it is free to call, never metered, and changes nothing about the connection's caps. It also explains the shared credit balance behavior and the common misconception about free API keys, beyond what annotations can convey.

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

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

The description is long but every sentence adds necessary behavioral or usage detail, and the opening phrase front-loads the core scope. It could be lightly restructured into shorter sentences for easier scanning, but it is not padded or 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?

For a zero-parameter access-info tool with an output schema, the description fully covers what the agent needs: what the tool returns conceptually, when to invoke it, what does not affect it, and how the cap-lifting model works. No critical calling context is missing.

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

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

The tool has zero parameters, so the description carries no parameter burden; the baseline of 4 applies. It adds value by clarifying what output dimensions the agent can expect, such as exact row caps, time windows, and locked items, which supports interpretation of the result even without parameter docs.

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 tells the agent this tool explains what the connection can and cannot see, covering plan tier, credits, row caps, time windows, and locked features. It is clearly distinct from the market-data siblings, which all report on crypto/DeFi content rather than the user's own access entitlements.

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

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

It gives explicit triggering conditions: call it when the user asks what they get, how many credits they have, why a result was capped, or how to upgrade. It also states when not to expect change, clarifying that a free API key does not lift caps and that only an active paid plan affects the limits.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description need not repeat those. It adds useful behavioral context: the tool is keyless, provides descriptive market data only, and records only swaps above a size floor rather than every swap on chain. This goes beyond what annotations convey, though it could say slightly more about response ordering or recency.

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

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

The description is compact, front-loads the core behavior, and every sentence earns its place: what is returned, when to use it, how to filter, and which siblings to choose instead. The use-case examples make it immediately actionable without bloating the 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?

Coverage is complete given the presence of a rich input schema, output schema, and annotations. The description supplies the selection context, filters, alternative tools, and data character while leaving schema-level details to the schema. An agent has enough to decide whether and how to call this tool.

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

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

Input schema covers all 5 parameters with descriptions, so the baseline is 3. The description reinforces that filtering by chain, coin, or minimum size is possible and clarifies the 'coin' use case, but it does not add substantial parameter meaning beyond what the schema already provides.

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

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

The description states exactly what the tool does: returns executed DEX whale swaps on Ethereum, Base, and Arbitrum along with wallet, DEX, token, and USD size. It also distinguishes itself from sibling tools by naming alternatives for related but different use cases, so an agent can select it confidently.

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

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

It gives explicit usage examples such as 'which wallets are buying PEPE' and 'large DEX swaps today', states the available filters (chain, coin, minimum size), and names three sibling tools to use instead for different intents: defi_summary, dex_wallet, and whale_trades. This is clear when-to-use and when-not-to-use 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=true, idempotent=true, and destructve=false. The description adds worthwhile behavioral context: it is keyless, it is 'Descriptive market data only', and the large-trade feed deepens on a paid plan. No contradiction with the annotations exists.

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

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

The description is compact, front-loaded with the resource and data contents, then adds auth and safety caveats in short declarative sentences. The parenthetical 'which act as magnets into expiry' is a little extra but still informative; overall no sentence is 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?

Given a rich output schema, full parameter schema coverage, and safety annotations, the description covers coins, exchange, data fields, auth model, paid-plan limitation, and descriptive nature. It is complete enough for an agent to invoke correctly, though it could have briefly noted when not to choose it among the many sibling market 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%, so the baseline is 3. The schema already documents coin and pair, including that BTC/ETH are the only supported coins and that BTC is default. The tool description repeats 'BTC or ETH' but does not add new parameter-level semantics beyond the schema.

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

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

The description clearly identifies the resource (Deribit BTC/ETH options) and the exact data points returned: open interest, strike walls, put/call balance, max pain, DVOL, and large trades. It uses a noun phrase ('The options picture') rather than a direct verb, but the scope and contents are unmistakable. It distinguishes itself from siblings by focusing on options-specific intelligence rather than general market data, though it does not name an 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?

The descriptionmakes the use case clear by enumerating options-relevant fields and saying it is aggregate market structure, so an agent can infer to use it for options sentiment/positioning questions. However, it does not explicitly state when to prefer it over siblings like market_snapshot or market_overview, nor mention exclusions or conditions.

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

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

The description discloses staleness fields (newest_candle_age_min, stale), the plan-based caps (168 vs 720), the capped field, the fact that the newest bar is still forming, and that it is descriptive data only. This goes well beyond the annotations and accurately reflects the operational 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 dense but every clause addes value: resource, interval, format, ordering, intended use, distinction from sibling, staleness fields, plan caps, and data-only nature. No waste and front-loaded with the core purpose.

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?

Combined with the rich schema and output schema, the description covers defaults, caps, error responses (capped/covered), freshness, ordering, and the live-vs-archive distinction. An agent has everything needed to invoke this tool correctly and interpret its role.

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

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

The input schema already documents all four parameters with 100% coverage, including defaults, plan caps, and invalid-interval fallback. The description restates those limits and defaults rather than adding new parameter-level meaning, though it does add context about bar ordering and OHLCV structure.

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

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

The description clearly states a specific resource (OHLCV price candes) and the action (retrieving near-live bars). It dintinguishes itself from market_history by emphasizing it is the live, bot-facing lane, so an agent can select it without opening sibling 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?

It expliciitly says this tool is for a bot computing its OWN indicators and separately on purpose from market_history, which settles days behind. This gives clear when-to-use guidance and names the alternative to avoid confusion.

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 readOnly/idempotent/destructive annotations, the description adds meaningful behavioral context: data is 'logged live and never backfilled', it has identical credit cost to flag_outcomes, and it is 'descriptive market data only'. This gives an agent operational expectations that annotations alone do not convey.

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

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

The description is three dense, purposeful sentences: what the tool does, the live/backfill behavior, and the sibling alias. There is no filler, and the most important semantic 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?

With full parameter schema coverage, an output schema present, and annotations covering safety and idempotence, the description adds the remaining needed context: data provenance, alias relationship, cost, and descriptive nature. Nothing material is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the parameter schema already documents coin, pair, type, hours, and limit thoroughly. The description adds no per-parameter meaning beyond what the schema provides, which puts it at the baseline of 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?

The description states exactly what the tool returns: recorded signals with the price at fire time and afterwards, showing whether signals historically led anywhere. It also explicitly identifies itself as the plain-English alias for flag_outcomes, which distinguishes it from a key sibling without needing to inspect 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 description explicitly names flag_outcomes as the identical counterpart and notes the same data and credit cost, which effectively tells an agent this tool is interchangeable with that sibling. It does not provide broader when-to-use versus other sibling tools, but for a tool that is an alias this is adequate context.

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

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

The description adds substantial behavioral detail beyond the annotations: positions_held and flow_traded are never added despite different units, unprofitable/unreadable wallets are never counted as flat, and rosterAgeHours is distinct from updated_at. These edge-case disclosures are valuable and consistent with the readOnly/idempotent 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 dense and front-loaded with the core purpose, and every sentence carries useful information. It is somewhat long and includes detailed methodology that could be trimmed, but it remains well-structured and free of 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?

Given the tool has an output schema, the description does not need to explain return values, and it covers the essential behavioral nuances: cohort definition, data units, wallet counts, flags, roster freshness, and unreadable-wallet handling. Nothing critical is missing for an agent to call this tool correctly.

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

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

Although the schema already covers the window parameter at 100%, the description enriches it by clarifying what window affects (flow_traded, not positions_held), the unit semantics, and that windows_available in the reply reflects what was actually published. This goes well beyond the bare enum definition.

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

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

The description clearly states the verb and resource: it reports what the PROVEN trader cohort is holding and trading, coin by coin. It also distinguishes itself from other tools by defining the cohort as Hyperliquid leaderboard accounts screened for provable profit rather than a guess.

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 provides clear context for when this tool is relevant — accessing proven-cohort holdings and traded flow — and notes it is keyless and descriptive. It does not explicitly name alternative tools or state when not to use it, 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 readOnlyHint and idempotentHint, so the safety profile is known. The description adds meaningful context beyond that: 'Descriptive, never a trade signal or a prediction' and 'Needs a paid plan' (auth requirement), plus the note that the call is refused without a paid plan for any pair. No contradiction with annotations.

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

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

The description is ~80 words, front-loaded with the core function, then use cases, alternatives, and caveats. It is well-structured, but there is minor redundancy between 'Descriptive, never a trade signal or a prediction' and 'Descriptive market data only' that prevents a perfect 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?

The description covers when to use the tool, when not to (explicit alternatives), the paid-plan requirement, and its non-predictive nature. An output schema exists, so return format is covered. Nothing essential an agent needs to select and call this tool correctly is missing.

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

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

Schema description coverage is 100%, and the description repeats rather than extends the parameters: 'coin' as alias and 'pair' details (e.g., 'Defaults to BTC/USD when omitted') are already in the schema. No added semantic value 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 function: a 'fused 0-100 crowding read' for one pair, listing the underlying components (funding, long/short accounts, taker imbalance, OI trend) and the overexposed side. It differentiates from siblings by explicitly routing WHERE forced closes land to liq_zones and past forced closes to liquidations/market_liquidations.

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 explicit when-to-use guidance: 'Use this when the user asks how crowded or squeeze-prone a coin is, or which side is over-leveraged,' with concrete example queries. It also names alternatives for other specific intents, so an agent can route correctly.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and the description adds substantial behavior beyond that: keyless access, a free-vs-paid plan split (percentile judgment, whale USD magnitudes, 24h stats, crowding score), compact-mode output shape (~30 vs 800 tokens), and the position_usd-gated carry arithmetic when omitted. No contradiction with 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 front-loaded with its content list and every clause carries information. It is mildly redundant at the close — 'Strictly descriptive' followed by 'Descriptive market data only' restate the same idea — and the opening sentence is a long single clause, costing 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 and full parameter coverage, the description need not explain return values, and it covers scope, plan tiers, compact mode, and the no-advice boundary. Remaining gaps are minor: 'keyless' is asserted without elaboration, and coin-vs-pair precedence when both are supplied is left unresolved.

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 each parameter is already richly documented in the schema (pair bare-symbol expansion, compact token counts, position_usd carry math). The description only cross-references position_usd as optional carry input, so it adds little beyond the schema — 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 composite deliverable — 'The pre-trade context blob in one call' — and enumerates its composition: price, cross-venue funding with carry arithmetic, open interest, whale flow, and recent visible liquidations. The composite one-call framing inherently distinguishes it from single-aspect siblings such as funding_matrix, coin_liquidations, and whale_flow.

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

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

It establishes clear usage context — 'pre-trade context in one call', 'on ANY streamed pair keyless' — and gives mode-level guidance for compact: true (one-line ~30-token answer). It also draws an exclusion boundary with 'Strictly descriptive... no advice', though it never names a preferred alternative when only one data type is needed.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by emphasizing 'Descriptive market data only' and clarifying that this is identical in behavior and cost to whale_profile. It does not contradict any annotation and gives extra semantic context about the nature of the 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 dense but not bloated, front-loading the main purpose and then enumerating specific outputs. The phrase 'recorded whale record' is slightly awkward, but the structure is efficient and informative without unnecessary 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?

Given the rich output schema, annotations, and the tool's complexity, the description covers the core selection-relevant context: what data is returned, that it is descriptive, and how it relates to whale_profile. It could add an example or clarify input constraints beyond the schema, but it is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the parameters are already documented at the schema level. The tool description does not add much parameter-level detail, but it reinforces the 'one coin' focal point. This meets the baseline for a fully schema-documented tool.

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

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

The description names a specific resource ('ONE coin'), a clear scope ('net flow over 1h, 4h, 24h and 7d...'), and the exact output categories. It also differentiates itself from whale_profile by explicitly stating it is the 'plain-English name' with identical data and credit cost. This gives an agent a precise understanding of what the tool does.

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 provides actionable usage context: it is 'the first tool for a general "what are whales doing with SOL" question' and positions itself as the human-friendly alias for whale_profile. It does not explicitly spell out when not to use it, but the use-case framing is clear enough for tool selection among many 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 idempotentHint=true, and the description adds meaningful behavior beyond that: keyless access returns multiples and records, USD magnitudes require an active paid plan, the response shape differs between single coin and list inputs, and 'descriptive market data only' reinforces its non-mutating nature. No contradiction with annotations.

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

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

Three dense sentences with no filler. The core differentiator is front-loaded, followed by input/output behavior and access-tier caveat. Every sentence earns its place.

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

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

Given the tool is read-only, idempotent, has only two well-documented params, and has an output schema, the description covers the essential operational facts: purpose, call shape, list behavior, keyless access, and paid-plan limitation. There is no meaningful gap for an agent to 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 description coverage is 100%, and the schema fully documents coin's comma-separated list behavior, flat vs {coins:[...]} response shapes, the available:false entry, omit behavior, and pair as an alias. The description largely restates this rather than adding new parameter-level meaning, 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 opens with a specific verb+resource: 'Per-coin whale flow vs that coin's OWN logged history', and explicitly brands itself as the 'is this unusual for THIS coin' call. This clearly distinguishes it from broader siblings like whale_flow or whale_activity.

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 establishes clear context: use this tool when you need to judge whether current whale flow is unusual relative to a coin's own history, and it explains the omit-coin behavior for top movers. However, it does not explicitly name sibling alternatives or state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to re-establish safety. It adds useful behavior beyond annotations: descriptive market data only, rolling window, one-coin scope, and CEX/DEX split. No contradiction with annotations.

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

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

The description is a single focused sentence that front-loads the core data shape and scope. Every clause adds useful information without repetition or 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?

The description, combined with rich parameter descriptions, annotations, and an output schema, gives an agent enough context to call the tool correctly. Minor missing context, such as explicit naming of alternatives, does not prevent correct use.

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 coin, pair, and hours in detail. The description itself does not add parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description states exactly what the tool returns: hourly buy/sell USD flow buckets for one coin, split by CEX and DEX, over a rolling window. It is specific and distinct from most sibling tools, though it does not explicitly name a sibling it is not.

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 conveys the data domain and scope clearly, so an agent can infer when hourly CEX/DEX flow data is needed. However, it offers no explicit guidance about when to prefer this tool over related whale/market tools, nor any exclusion criteria.

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

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

The description goes far beyond the readOnly/idempotent annotations, explaining that pressure.state is null with named reasons and must be reported as 'not enough to say', that venues.partial means venue dollars are UNKNOWN and must not be treated as zero, and that hoursCovered appears only on partial windows. It also warns that price-coverage shortfalls arrive as caveat fields, giving the agent precise reporting rules.

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?

Every sentence earns its place: the first sentence gives the core contract, then each subsequent sentence addresses a specific misinterpretation or edge case that an agent would otherwise get wrong. It is long because the tool has real output sematics, not because of 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 complex profile tool with an output schema, the description covers the main output groups, null semantics, partial-data rules, and access limits, while the schema fully documents all three parameters. An agent has enough to select, invoke, and interpret the result without guessing.

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 baselline is 3, but the description adds a useful access constraint: 'Keyless (7-day window; a paid plan reaches the full 30-day record)' clarifies what the `hours` parameter can actually retrieve for a given caller. The rest of the parameter meaning is already in the schema, so credit beyond baseline is warranted but modest.

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 precise verb–resource pair: one call returns everything the recorded whale record can say about ONE coin, enumerating flow windows, venue splits, concentration, sources, and pressure state. It is immediately distinguishable from siblings like whale_flow or whale_radar by its explicit 'single call' and 'one coin' scoping.

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 clearly frames when to call this tool: when a full, single-coin whale picture is needed in one call, and it notes descriptive-only data and the keyless 7-day access boundary. It does not explicitly name sibling alternatives or state when NOT to use it, but the context is strong enough to route an agent appropriately.

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, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it emphasizes 'Descriptive market data only,' explains that ranking is relative to the coin's own baseline rather than dollar size, and explicitly states there are no arguments. This is meaningful but not exhaustive; the output schema covers remaining 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 longer than average but every sentence earns its place: it front-loads the core function, then supplies use-case examples, ranking methodology, and explicit sibling routing. It is dense but not redundant; minor trimming of the quoted user-phrase examples could tighten it slightly.

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 zero parameters, a rich output schema, and strong annotations, the description covers everything an agent needs: what the tool does, when to choose it, what it does not do, and which alternatives to use. No critical context is missing for correct invocation.

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

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

There are no parameters and the schema is an empty object, so the baseline is already 4. The description goes further by explicitly stating 'No arguments,' which removes any ambiguity about whether hidden or optional inputs exist. This is sufficient for a zero-parameter tool.

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

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

The description uses a specific verb ('discover'/'rank') with a precise resource: coins with unusual whale flow relative to their own trailing baseline across 1h/4h/24h windows. It clearly differentiates from siblings by emphasizing discovery of unnamed coins and relative rather than absolute ranking.

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 states when to use this tool: when the user has not named a coin and wants unusual movements. It names concrete alternatives (whale_profile, whale_activity, whale_context, market_digest) and the conditions that select each, giving an agent unambiguous 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 mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail: it is deprecated, merges CEX and DEX data, returns newest first, applies keyless vs. paid shape differences, enforces row caps, and states 'Descriptive market data only.' No contradiction exists, and the description goes well beyond the annotation safety profile.

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 efficiently structured: the deprecation and preferred alternative are front-loaded, followed by the data coverage, then keyless vs. paid limitations, and a closing safety note. Every sentence adds information an agent needs, with no filler or repetition of schema content.

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

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

For a deprecated alias with five optional parameters, full schema coverage, an output schema, and read-only annotations, the description supplies the missing context: venue coverage, live vs. delayed data, plan-based shape differences, row caps, and the 'descriptive only' nature. Nothing essential for correct tool selection or invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including cap behavior, aliases, defaults, and the keyless $250K DEX floor. The description reinforces the plan-based limits and data scope but does not materially add parameter-level semantics beyond what the input schema already provides. 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 immediately declares this is a 'Deprecated alias for whale_trades' and that its purpose is to provide a 'Live whale trades merged across 15 CEX venues plus on-chain DEX swaps... newest first.' It clearly distinguishes itself from the preferred sibling by naming whale_trades and stating the relationship, so an agent understands what the tool is and how it relates to 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?

The description explicitly says 'Prefer whale_trades' and explains this alias exists only 'so existing clients keep working.' This is direct, unambiguous guidance to use the alternative unless backward compatibility is required. It also notes deeper pages are available on the REST API, which further helps an agent decide whether this tool is appropriate.

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 readOnlyHint and idempotentHint annotations, the description discloses key behavioral details: aggregation across venues, newest-first ordering, keyless free-shape restrictions, 30-minute delays, DEX swap thresholds, row caps of 25 vs 500, and an explicit 'descriptive market data only' safety note. This is unusually transparent for a read-only feed.

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 carry a substantial amount of specific, relevant detail with no filler; the first sentence immediately establishes what the feed is and how it is ordered. The second sentence is dense due to parentheticals and semicolons, but every clause serves a purpose, so it remains effective.

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 that the output schema is present, parameter coverage is 100%, and annotations already mark the tool read-only and idempotent, the description is complete enough for an agent to call it correctly. It covers venues, ordering, keyless vs paid behavior, row caps, delays, and value thresholds, leaving no obvious invocation-critical 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 coverage is 100% and the input schema already documents coin, pair, limit, source, and min_usd well. The description adds useful global context about free vs paid limits and DEX thresholds, but it does not add per-parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies a live feed of whale trades aggregated from 15 CEX venues plus on-chain DEX swaps, with newest-first ordering. This gives a concrete resource and scope that distinguishes it from generic market-data siblings, though it is phrased as a noun phrase rather than an explicit imperative verb like 'Get' or '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 makes the tool's niche explicit: merged CEX and DEX whale trades with specific keyless versus paid access differences, so an agent can infer when it is relevant. It does not explicitly name alternative tools or state when not to use it, such as versus whale_activity or whale_radar, so the usage guidance is implied rather than direct.

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