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

Annotations cover readOnly/idempotent/destructive, but the description adds substantial behavioral context beyond them: 60 s refresh cadence, latest-only with no history, the meaning of as_of_height at the L1 block, the caution to check age_s before citing, and the Pro-tier requirement. This is rich disclosure layered on top of 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?

Dense but front-loaded: the answer to 'what does this provide' leads, followed by the example, then caveats. Every sentence carries information, though the em-dash-heavy prose is slightly heavy for the payload.

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

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

With no output schema, the description compensates by naming the returned fields (total size, order count, DISTINCT WALLET count, oldest-order age, as_of_height) and the freshness constraint. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100% so the schema already documents coin, depth, and useToonFormat, giving a baseline of 3. The description adds value by showing depth=5 in a worked example and pointing to bids[2].wallets, tying the parameter to the returned structure rather than merely restating it.

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

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

States a concrete verb+resource (top price levels per side, best-first) and explicitly contrasts with the aggregated L2 view via 'market_orderbook remains the aggregated L2 view; this is the L4 one'. An agent can distinguish this from siblings without opening the schema.

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

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

Explicitly names the alternative (market_orderbook) and the condition selecting this tool, plus a concrete use case ('is SOL's 3rd bid level real depth or one wallet?'). The L2-vs-L4 routing is spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-obvious traits: snapshot-derived, refreshed every 60s, latest-only with no history, as_of_height semantics, and an instruction to check age_s before citing. It also flags case-sensitivity ('btc' will 404) and the Pro-tier requirement — well beyond what annotations 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?

Dense but organized, leading with the question it answers and the summary, then the example, then the important window-vs-totals caveat and freshness notes. Nearly every sentence carries load, though the paragraph is long and could be tightened without losing meaning.

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

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

For a snapshot tool with no output schema, the description explains both what is returned and how to read it (totals vs buckets, nearest triggers, beyond-window counts) plus freshness (age_s, as_of_height) and addressability constraints. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: the totals_below/totals_above/nearest_* fields always cover every trigger while `buckets` is limited to the within_pct window, which clarifies how the parameters interact with the output. The case-sensitivity and spelling guidance is largely repeated from the schema, capping it at 4.

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

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

Opens with a direct question the tool answers ('where are the stops, and how much size fires if price gets there?') then states the specific operation: bucketing untriggered stop/take-profit orders by distance from mid in 0.25% steps. It explicitly positions itself against the sibling market_orderbook ('the aggregated L2 view; this is the L4 one'), so an agent can distinguish them.

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

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

Provides a concrete usage example ('what is stacked under BTC within 2%?' with the exact call and which fields to read) and clarifies the L4-vs-L2 relationship. It does not enumerate hard when-not conditions or other alternatives, but the context is clear enough to 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?

On top of the readOnly/idempotent/openWorld annotations, the description discloses that results are snapshot-derived, refreshed every 60s, latest-only with no history, that as_of_height is the L1 block of truth, and that age_s should be checked before citing. It also flags Pro-tier gating. The main omission is expected response shape, which is partly covered by the field enumeration.

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

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

It is a long description but dense and front-loaded with the core question and the return enumeration before the caveats. Most sentences earn their place, though the coin-spelling warning is somewhat duplicative of the schema.

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

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

With no output schema, the description carries the return-value burden and does so by naming the bands, imbalance metrics, and touch statistics an agent will actually receive. Combined with the freshness and interpretation guidance, an agent has everything needed to call and correctly cite it.

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

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

Schema coverage is 100%, so both parameters are already documented, including the case-sensitive coin spelling, the 404 on 'btc', and the spot-pair exclusion. The description largely restates this, adding the nuance that the value is 'passed through unchanged', which is marginal. Baseline 3 applies when the schema carries the detail.

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

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

The description opens with the exact question the tool answers ('how deep and how lopsided is this book right now?') and then enumerates the specific outputs: touch prices, spread in bps, per-side size/count/wallets in nested bands, imbalance, and post-only share. It explicitly distinguishes itself from the sibling 'market_orderbook' by labeling this the L4 view versus the aggregated L2 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 gives a concrete worked example ('is HYPE's bid side thinner than its ask side inside 1 %?'), names the alternative tool and the condition that separates them (L4 vs L2), and states the refresh cadence and latest-only constraint so the agent knows when the answer is valid. Nothing about when to reach for this tool is left to inference.

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

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

Annotations already cover read-only/idempotent/no-destruction, but the description adds substantial non-structured context: snapshot-derived, refreshed every 60s, latest-only with no history, as_of_height semantics, and the instruction to check age_s before citing. It also flags 'Pro tier' for access 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?

Front-loads the core question, then return fields, example, caveats, and tier in a logical order with essentially no filler. It is dense and somewhat run-on, but every clause carries useful 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?

No output schema exists, yet the description enumerates return fields, the snapshot/refresh model, the as_of_height/age_s staleness caveat, coin spelling, and tier. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the case-sensitivity rules and toon-format toggle. The description largely repeats the coin case-sensitivity guidance and only adds an example 'limit=10' usage, so the baseline of 3 applies.

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

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

States a specific question it answers ('who is sitting on this book, and where?') and enumerates the returned fields (wallet, side, price, size, original size, distance from mid, tif, order type, rest time). It also explicitly separates itself from the sibling 'market_orderbook' as the L4 view rather than the aggregated L2 view.

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

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

Gives a concrete when-to-use scenario ('is one wallet holding up the ETH bid?') with an example call and how to read the result. It names the alternative market_orderbook and the condition (L2 aggregate vs L4 individual orders) that selects between them, and routes to the trader tools for wallet joins.

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

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

Goes well beyond the annotations by disclosing that tiers are LIFETIME labels in legacy slug form, that untracked wallets are surfaced so per-tier counts sum to totalUsers, that attribution undercounts versus ledger revenue, and that the computation may exceed a 30s budget (retry once a minute later).

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

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

Front-loads the core purpose in the first sentence and keeps caveats tight, though it is dense and packs several clauses (attribution, tiers, Pro tier, timeout) into a long paragraph. Efficient but not maximally scannable.

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

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

With no output schema, the description carries the full burden and does so: it enumerates the returned fields (users, share of totalUsers, builder fees, attributed volume, realized PnL, fills) and points to the response's dataNotes for attribution caveats.

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 period/builder/useToonFormat are already documented in the schema. The description adds conceptual meaning to the tier outputs (pnlTiers/sizeTiers slugs) but contributes little parameter-specific guidance beyond what the schema provides.

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

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

States a precise verb+resource: the cohort composition of a builder's attributed users over day/week/month, split by all-time profitability tier and size tier. It explicitly distinguishes itself from siblings by noting it emits LIFETIME legacy-slug tiers rather than the 30d-rolling tiers used by the pulse cohort 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 concrete motivating questions ('is builder X's user base smart money or exit liquidity?', 'do whales or shrimp pay most of its fees?') and states the Pro-tier prerequisite plus availability/retry behavior. It even contrasts with the alternative cohort tools.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important limitations: trigger-order fills are not yet attributed, the feed undercounts versus ledger revenue, the lookback is clamped to 90d, and untracked order ids are null. It also points to dataNotes for further context. This is strong 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 well-structured, leading with the core purpose, then filters, return fields, known limitations, use cases, and access requirements. Every sentence delivers new information without redundancy.

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

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

With no output schema, the description compensates by enumerating the returned fields (time, wallet, coin, marketType, side, price, size, USD volume, realized PnL, builderFeeUsd, tid, order id). It also covers caveats, authentication requirements, and filtering options, making the tool fully callable without additional context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning by interpreting the since parameter ('30m', '6h', '7d', clamped to 90d) and explaining coin filter variants (BTC, xyz:GOLD, @123 spot, #10010 HIP-4). It enriches rather than merely repeating the schema.

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

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

The description states a specific verb and resource: returns individual fills attributed to a builder address within a lookback window. It clearly distinguishes itself from sibling builder tools by focusing on fills, their fields, and the builder attribution model.

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 concrete use cases ('show me the flow going through frontend X right now' or auditing one wallet's activity via a builder) and notes the Pro tier requirement. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select this tool 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?

Beyond the annotations (which already declare read-only/idempotent/non-destructive), the description discloses the Pro-tier requirement, the fixed minFills=3 qualifying threshold, the per-wallet-then-aggregate computation, and the truncation bias that pushes day counts low, pointing to dataNotes. That is meaningful behavioral context the annotations cannot carry.

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

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

It is front-loaded with the core purpose and every clause carries metric, caveat, or routing information, which is defensible given the absence of an output schema. It is still a dense run-on that could be broken into scannable sentences.

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

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

With no output schema, the description responsibly enumerates the returned fields and their semantics (e.g., concentration=1 means evenly spread, 0 when median is 0), defines the cohort universe and window, and flags the bias, leaving no material gap for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents both the builder pattern and useToonFormat, giving a baseline of 3. The description only restates that a 0x-hex builder address is taken and adds no format or value guidance beyond the schema; its claim of 'no other parameters' is also slightly loose given useToonFormat 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 names the exact population, metrics, and computations (avgRevenueUsd, medianRevenueUsd, concentration, daysToPeak/Half/ThreeQuarters, peakDayDistribution) for a specific resource — a builder's acquisition cohort. It explicitly distinguishes itself from the sibling builder_lifecycle by scoping to the trailing-year cohort.

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 supplies an explicit trigger question ('how fast and how unevenly does builder X monetize a new user?') and a 'NOT ... builder_lifecycle covers' exclusion, so the agent knows both when to use it and which sibling to pick instead. It also states the Pro-tier prerequisite.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing that attributed metrics undercount ledger revenue due to unattributed trigger-order fills, pointing to dataNotes, explaining the 'verified' stamp, and warning that ledger history begins at the first on-chain entry. This is the kind of caveat an agent cannot get from structured fields.

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?

Dense but front-loaded: the ranking definition comes first, followed by row contents, caveats, and usage. Every sentence carries distinct information, though the middle section is heavy enough to risk readability.

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?

Despite having no output schema, the description enumerates returned fields (feeTenthsBp, builderName, prev-window metrics, dataNotes, verified stamp) and coverage behavior, giving the agent enough to interpret results 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 limit, offset, period, and useToonFormat are fully documented in the schema. The description adds response-field semantics but nothing new about the parameters themselves, so the baseline 3 applies.

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

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

States a specific verb+resource+scope: builders ranked by exact revenue from the on-chain cumulative builder-fee ledger. It clearly distinguishes itself from siblings like builder_profile, builder_traders, and builder_fills by centering on revenue 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?

Gives concrete use cases ('which builders earn the most?', 'is builder X growing?') and a prerequisite ('Requires Starter tier or higher'). It does not explicitly name alternatives or when-not to use it, 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?

Annotations already cover read-only and idempotent safety, but the description adds substantial behavioral context: mutually exclusive statuses that sum to totalUsers, the LIFETIME universe on the ORDERS plane, the exact recency windows, whether unfilled wallets are included, and the fact that only the status test reads recent attributed fills. It also discloses tier requirements, latency, and retry 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?

It is long and dense, but the length is largely justified by the need to define five statuses and several derived metrics. The purpose and sibling distinction are front-loaded, and every clause carries substantive meaning, though bullets or clearer segmentation would improve readability.

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

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

With no output schema, the description compensates by enumerating the returned fields and their relationships, including status definitions, retention/churn/competitiveLoss calculations, and competitiveLossFeesUsd. It also covers caveats, dataNotes, tier requirements, and operational latency, leaving little an agent needs to infer.

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 builder and useToonFormat parameters are already documented in the schema. The description reinforces the builder address format and notes that no other query parameters are accepted, but it does not add meaningful semantics beyond the schema and does not mention useToonFormat.

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

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

It states a specific resource and operation: a lifetime snapshot of every wallet that ever traded via a builder, with five mutually exclusive statuses and derived retention metrics. It explicitly distinguishes itself from builder_retention by contrasting a single historical snapshot with a per-cohort monthly grid.

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

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

It gives a concrete use case quote, states that only a 0x-hex builder address is accepted, notes Pro tier requirement, and provides availability and retry guidance. It also tells the agent when to prefer this over builder_retention.

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 annotations, it discloses important scoping details: orders that never filled still count, trigger history starts on 2026-03-24, resolved placements are excluded from totalIntents/trigger actions but included in the breakdown, and response dataNotes should be consulted. This goes well beyond the structured annotations.

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

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

The description is dense and runs long, but every clause carries functional information needed because there is no output schema. It is front-loaded with the intent question and uses dashes to separate logical sections, though it could be more readable as a structured list.

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's complexity and the absence of an output schema, the description is remarkably complete: it explains the core metric, breakdown fields, exclusions, historical boundary, fill-conversion semantics, and points to dataNotes. An agent has enough to correctly invoke and interpret the result.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds contextual meaning around builder and period but does not add meaningful detail beyond the schema, and it does not mention useToonFormat. 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 measures: placement-time intents for a builder's users, aggregated by period. It clearly distinguishes this from fill-plane tools by saying it is 'Measured on the PLACEMENT plane, not the fill plane behind builder_fills and builder_traders.'

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 an explicit use case: 'Use for do builder X's users place stops and take-profits, and how much of their order flow actually fills?' It also tells the agent when not to use it by contrasting with builder_fills and builder_traders, and notes the Pro tier requirement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond that: it explains the attribution denominator, caveats about trigger-order fills undercounting, omission of unknown builderName, and that shared users' feesUsd is what those users paid to the OTHER builder. It also flags the Pro tier requirement.

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: it front-loads the core purpose, then details the return shape, then includes caveats and use cases. Every sentence adds information an agent needs, and nothing is redundant with the schema or annotations.

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

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

With no output schema, the description compensates fully by enumerating the returned fields (activeUsers, sharedUsers, share, feesUsd, builderName omission), explaining the denominator, and noting the undercounting caveat. It also gives clear selection guidance and tier requirements, making the tool callable correctly without further documentation.

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 100% coverage for all three parameters, so the schema already documents period, builder, and useToonFormat. The description adds minimal parameter-level meaning beyond restating the day/week/month window and emphasizing the builder address context, which is not enough to raise the score above the baseline.

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

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

The description states a precise verb and resource: it lists the top 10 OTHER builders whose frontends/bots/dexes this builder's active users also traded through, ranked by shared users. It clearly distinguishes this from sibling builder performance tools by focusing on audience overlap rather than the builder's own metrics.

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

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

The description explicitly provides use cases: 'who is builder X's closest competitor?' and 'where else does its audience trade?'. It does not name specific alternative tools or exclusion criteria, but the context is clear enough for an agent to select this over sibling builder tools.

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

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

Adds substantial context beyond the annotations: 404 behavior for zero-revenue addresses, 10-25s latency on large builders, topCoins null-on-budget with dataNotes explanation, known undercounting vs ledger revenue, registry-sourced builderName omission, and ledger history scope. Annotations cover the safety profile, and the description layers on operational and data-quality traits.

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

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

Purpose is front-loaded and every clause carries information, but the entire definition is a single dense run-on paragraph mixing return values, caveats, latency, and coverage notes. It is information-rich rather than wasteful, yet structure and scannability suffer.

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

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

No output schema exists, so the description must carry the return-value explanation, and it does thoroughly (revenue, timestamps, tokens, rate, daily series, top coins, profitability count, dataNotes caveats). For a complex analytics tool with a mandatory address parameter, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it explains feeTenthsBp units (tenths of a basis point), clarifies that topCoins may come back null, and reinforces the period window semantics. Genuine added value over the structured fields.

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

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

States a specific resource ('single-builder overview for a 0x-hex builder address') and enumerates exactly what is returned: ledger revenue, timestamps, fee tokens, fee rates, daily attributed series, top coins, profitable wallets. It is unmistakably distinct from builder_leaderboard, builder_fills, and the pulse_* 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?

Provides concrete trigger phrasing ('how is builder X doing?', 'what do people trade on frontend Y?') plus a tier prerequisite (Starter+). It does not explicitly name a sibling alternative or a when-not-to-use condition, so it falls short of a 5.

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

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

Even with strong readOnly/idempotent annotations, the description adds substantial behavioral detail: cohorting by first builder-fee order, the definition of active, index 0 = newWallets, 12-month window with oldest-first ordering, and the ORDERS-plane caveat. It also flags dataNotes and the Pro tier requirement.

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 substantive element earns its place, and the key purpose is front-loaded. It loses one point for the inaccurate parenthetical and for packing definitions into a long run-on sentence, though this is more a clarity issue than 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?

With no output schema available, the description supplies the essential response semantics: cohort key, activeWallets[k], newWallets, time range, ordering, and dataNotes caveat. An agent receives enough context to call the tool correctly and interpret the returned retention matrix.

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 a baseline of 3 would normally apply, but the description's emphatic claim 'no other parameters' contradicts the schema's optional useToonFormat parameter. This is actively misleading for invocation despite the useful note that the builder must be a 0x-hex address.

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 deliverable ('Monthly retention matrix') and the exact question it answers, and differentiates itself from builder_cohorts/builder_overlap by calling out the ORDERS-plane measurement. The distinction is enough for an agent to select it over the sibling retention-related 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 frames the intended use as retention/churn analysis and points out when its counts will differ from the attributed-fill metrics on builder_cohorts/builder_overlap. This gives clear routing guidance to siblings without further inference.

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

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

Annotations cover the safety profile (read-only, idempotent, open-world), and the description layers on genuinely non-obvious behavior: per-builder on-request computation that can blow a 30s budget, retry guidance, attribution undercount vs ledger revenue, and the lifetime-vs-30d tier distinction that affects how memberships compare to cohort tools.

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?

Dense but front-loaded: what the tool returns comes first, then the caveats, then usage and availability. Every clause carries information, though the single long paragraph and nested parentheticals make it harder to scan than a short bulleted caveat block would be.

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

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

With no output schema, the description carries the return-shape burden and does so: it enumerates each row field, flags the dataNotes caveat, and documents the availability limit. An agent has everything needed to call and interpret 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the semantics of the emitted equity sentinel (0 when untracked) and the tier fields (legacy slugs, null when untracked) and why lifetime tiers differ from rolling ones. It does not add syntax beyond the schema for the enum params themselves.

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

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

States a specific resource and scope: wallets that traded via a given builder address within a window, with explicit ranking dimensions. It is clearly distinguishable from siblings like builder_fills (fill-level) or builder_leaderboard, and the two example questions pin the intent down.

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?

Provides concrete use cases ('who are builder X's biggest fee payers?', 'are smart-money wallets using this frontend?') plus a Pro-tier prerequisite and a timeout/retry rule. It stops short of naming an explicit alternative sibling to use instead when this tool is not the right fit.

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/openWorld/idempotent annotations, the description discloses rich operational behavior: sources queried sequentially due to a small per-key burst allowance, a failing source reported in notes rather than failing the call, no date ever guessed, book snapshots refreshed every 60 s with no history, and free-tier gating surfaced in notes.

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

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

Front-loaded with the core purpose before the dataset inventory, and every clause carries information. It is dense and parenthetical-heavy, reading as one long paragraph, so it is effective rather than elegant, but nothing is padding.

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

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

There is no output schema, so the description must describe returns, and it does: per-dataset window fields (with windowStart null + note when unavailable), freshness stamps, source notes, and the server { version, hiddenTools, toolCount } object. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% (baseline 3), but the description goes further by glossing each opaque enum value — e.g. 'builder_ledger (fee ledger + attribution coverage)', 'census (chain-state stamp)', 'book (L4 order-book rollups ... no history)' — which the bare enum cannot convey. useToonFormat is left entirely to the schema.

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

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

The description states a precise verb+resource pair ('report the data window and freshness stamp of each dataset behind this server') and adds provenance (API route per figure). It is unmistakably a meta/diagnostic tool, clearly separable from the analytical siblings like trades, liquidations or cohort tools.

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

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

It gives an explicit trigger: 'check window and freshness before relying on a historical range or citing a date.' That is clear when-to-use guidance. It does not name a when-not condition or a competing sibling, which keeps it below a 5, though no true alternative tool exists in the roster.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond these by stating the Pro-or-higher key requirement and summarizing the returned counts. This auth constraint is important for an agent deciding whether the tool is callable in the current 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 three sentences with no filler. It front-loads the core purpose, then lists the key returned values, then states the access requirement. 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?

The tool has only two optional parameters, and both are fully documented in the schema. The description covers the output semantics, the access requirement, and the cross-product scope clearly enough. Since no output schema exists, the description's mention of returned counts and percentage provides the needed return-value context.

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 both parameters, including defaults and constraints, at 100% coverage. The description does not add much parameter-specific meaning beyond the schema, but it does clarify that the tool is window-based and returns overlap-related counts, which aligns with the 'days' parameter.

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 ('Measure overlap') and a precise resource combination: HIP-4 outcome traders versus perp traders. The tool name and description together clearly distinguish it from sibling tools like pulse_compare or builder_overlap, since the cross-product scope is explicit.

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

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

The intended use is implied: an agent can infer this tool is appropriate when overlap metrics between HIP-4 outcome traders and perp traders are requested. However, the description does not explicitly state when to prefer this tool over related siblings or provide exclusions, leaving some routing ambiguity.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior the schema cannot express: HIP-4 fills are indexed from mainnet launch 2026-05-02 and the API clamps every look-back to that date. It stops short of describing response shape or truncation behavior, which matters since there is no output 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 sentences, front-loaded with the payload contents before the usage cue and the data-coverage caveat. Every clause carries information an agent needs; nothing is restated from the name or title.

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

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

For a read-only, no-output-schema tool the description compensates well by naming the returned metrics and warning about the launch-date clamp. The only remaining gap is expected response structure/pagination, which is minor given the annotations and the small 2-parameter surface.

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 are fully documented in the schema (days default/max, useToonFormat default). The description adds only 'by day' granularity and does not elaborate on the 1–60 day clamp or the toon-format toggle, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Get daily HIP-4 volume trajectory') and enumerates the exact measures returned: fills, unique trades, unique wallets, contracts, notional USDH by day. That granularity separates it from siblings such as hip4_andwer_summary or hip4_most_active without the agent needing to open any schema.

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

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

'Use for outcome-market activity trends' gives a clear usage context, and the pointer to data_coverage for freshness is a useful secondary route. However, it never names an explicit alternative (e.g., hip4_outcome_summary, hip4_most_active) or a when-not condition, so routing remains partly inferential.

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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context by specifying the ranking order ('ranked by fill count') and the conditional inclusion of metadata ('when available'), which goes beyond the structured annotations.

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

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

The description is two sentences with no wasted words. The core purpose and ranking criterion are front-loaded in the first sentence, and the second sentence adds a useful caveat about metadata availability.

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 ranked-list tool with fully described parameters and no output schema, the description adequately conveys the output shape: outcomes ranked by fill count with optional metadata. It does not enumerate specific return fields, but this is a minor gap given the tool's simplicity.

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 all parameters (hours, limit, useToonFormat) already documented with defaults and ranges. The description adds no new parameter-level meaning beyond what the schema 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 names a specific verb ('Return'), a specific resource ('HIP-4 outcomes'), and a precise selection/ranking criterion ('ranked by fill count' over a recent window). This clearly distinguishes it from sibling tools like hip4_outcome_summary, hip4_outcome_recent_trades, and hip4_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 implies when to use the tool: when you want the most active HIP-4 outcomes ranked by fill count. However, it does not explicitly state when not to use it or name alternative tools for related needs, so the guidance is implicit 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful return-content context, such as 'metadata when available' plus specific fields, but it does not disclose additional behavioral traits like pagination, latency, or data availability limits beyond what annotations and schema already imply.

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

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

The description is a single, front-loaded sentence with a clear verb, target, and output summary. There is no redundancy, filler, or unnecessary elaboration, so every clause earns its place.

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

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

For a read-only single-record tool with complete schema coverage, the description gives enough context about scope and return content for correct invocation. It does not explicitly explain how this tool differs from the many nearby hip4_outcome siblings, but that gap is more about usage routing than completeness of the tool definition itself.

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

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

Schema description coverage is 100%, and the schema already explains outcomeId's encoding ('Side-token coins are encoded as #<10*outcomeId+side>') and useToonFormat's default behavior. The description adds no new parameter meaning, but it does not need to because the schema carries the full burden.

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 and resource: 'Get details for one HIP-4 outcome contract by outcome ID,' and enumerates the returned fields (metadata, side tokens, fills, unique wallets, notional USDH, trading timestamps). It is clear, but it does not explicitly distinguish itself from sibling tools like hip4_outcome_summary or hip4_outcome_recent_trades, so it falls just short of a top score.

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 intended use is implied: call this when you need full details for a single HIP-4 outcome. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives among the many sibling tools. The large sibling set makes this a noticeable gap.

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 non-destructive behavior, lowering the burden on the description. The description adds meaningful behavioral context beyond annotations by specifying exactly which fill types are excluded and listing the returned fields: trade time, wallet, side, price, size, PnL, and fee.

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 filler. The core action and scope are front-loaded, exclusions follow immediately, and the return fields are listed compactly. Every sentence adds 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?

For a read-only recent-trades listing tool with a single required parameter and three optional parameters, the description is complete. It explains what data is returned and what is excluded, which is especially important given there is no output schema to document the response shape.

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 all four parameters. The description briefly reinforces that the tool targets one HIP-4 outcome, aligning with outcomeId, but it does not add meaningful semantics 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 a specific verb and resource: 'Get recent real fills for one HIP-4 outcome.' It further distinguishes the tool by excluding settlement, pair-redeem, and auction-phase fills, making it clear how it differs from related tools like hip4_recent_settlements or pulse_recent_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 description implies when to use the tool by focusing on 'real fills' and explicitly excluding settlement and auction fills, but it does not name alternative tools or state when not to use it. An agent can infer the intended use case but gets no explicit routing guidance among the many sibling tools.

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

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

Annotations already declare read-only/idempotent/no-destructive, and the description layers on substantial extra behavior: sort order (notionalUsdh descending), the connector-side cap because the API route has no paging, the count/totalCount/truncated/note fields, how to see more (raise limit or shorten hours), and the mainnet-launch indexing floor with a pointer to data_coverage.

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

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

Purpose is front-loaded in the first sentence, and the following clauses each carry real information (sort order, cap mechanics, index floor). It is dense and slightly long, but no sentence is filler.

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

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

With no output schema, the description still enumerates the return payload (IDs, question metadata, side tokens, fills, wallets, notional USDH, timestamps, truncation fields) and the look-back constraint. An agent has everything needed to call it and interpret truncation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining why the caps exist (connector-applied, no paging) and the operational consequence of truncated/count, which materially clarifies how limit and hours behave.

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: 'List active HIP-4 outcome contracts that traded recently,' and even enumerates the returned fields. It is clear what the tool does, though it never explicitly distinguishes itself from near-neighbors like hip4_most_active or hip4_outcome_summary, so sibling differentiation is left to inference.

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

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

'Use when users ask what prediction/outcome markets are active' gives a concrete trigger context, and 'see data_coverage for freshness' routes the agent elsewhere for a related concern. There are no explicit when-not conditions or named alternatives for overlapping tools such as hip4_most_active.

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 valuable behavioral context beyond annotations by disclosing the auth requirement and specifying exactly what data will be returned, which helps an agent set expectations.

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 filler. The main action and resource are front-loaded, the returned fields are listed compactly, and the access requirement is appended without disrupting the core message.

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

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

For a tool with only two parameters and complete schema descriptions, the description gives everything an agent needs: the resource scope, the returned fields, and the access requirement. Although there is no output schema, the field list effectively documents the return shape.

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 documents outcomeId and useToonFormat. The description does not add new parameter-level meaning; it only restates the high-level purpose, which aligns with the baseline score of 3 for complete schema coverage.

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

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

The description uses a specific verb ('Get'), names the exact resource ('HIP-4 summary for one outcome'), and enumerates the included metrics, making the tool's function clear. It differentiates from most sibling tools by emphasizing 'across both sides' and 'full summary', but it does not explicitly distinguish itself from the closely named hip4_outcome sibling.

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

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

The description implies when to use this tool—whenever a full HIP-4 outcome summary is needed—and gives a clear access prerequisite ('Starter-or-higher key'). However, it provides no explicit guidance about when not to use it or which alternative sibling tools might be more appropriate for related but different queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the meaningful behavioral detail that a Pro-or-higher API key is required, which is not conveyed by annotations. 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 dense but well-organized: purpose first, followed by return fields, then explicit use cases and the auth requirement. Every sentence contributes useful 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 there is no output schema, the description reasonably compensates by listing the main output categories and clarifying intended queries. It does not detail exact response shapes or toon-format structure, but those are secondary given the rich output list and schema-covered 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%, so the schema already documents all four parameters including defaults and ranges. The description adds only a general reference to 'one HIP-4 outcome' aligning with outcomeId, but does not meaningfully extend parameter understanding 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 uses a specific verb ('Join') and clearly identifies the resource: HIP-4 outcome holders joined to open perp positions on the same underlying asset. It also enumerates the computed metrics, making the tool's function concrete and easily distinguishable from 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 explicitly states when to use the tool: when users ask whether outcome traders are exposed to the same asset, whether a side is directional or hedged, or which large outcome holders lack perp exposure. It does not name alternative tools or exclusion criteria, but the use cases are specific enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds some context by naming the source (outcomeMeta) and noting that parsed fields are included 'when present,' but it does not disclose pagination, ordering, or response structure.

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 sentence that leads with the core purpose and then packs relevant field details into a readable list. It is slightly dense due to the enumeration, but every item contributes to explaining what the tool returns.

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's low complexity (one optional parameter, no output schema, read-only annotations), the description provides a clear picture of what is returned and from where. It could be more complete with an explicit mention of the default toon format behavior, but that is already documented in the schema.

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

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

The input schema has 100% description coverage for the single optional parameter useToonFormat, so the schema already explains the parameter fully. The description adds no additional parameter-level semantics beyond what the schema provides.

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

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

The description clearly identifies the action ('List') and the resource ('HIP-4 question metadata from Hyperliquid outcomeMeta'), and enumerates the specific metadata fields returned. It does not explicitly contrast itself with sibling tools like hip4_outcomes or hip4_outcome_summary, so it does not fully achieve the highest sibling-differentiation standard.

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

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

The description gives no guidance on when to use this tool versus its many sibling tools, nor does it state any exclusions or alternative recommendations. An agent would have to infer use cases from the tool name and field list alone.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond that: it reports settlement time, winning side 'when determinable,' fill counts, payouts, and losses. This gives the agent a clear picture of what sort of data to expect and acknowledges uncertainty in outcome determination.

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

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

Two sentences, no filler, and the core action is front-loaded. The return-field enumeration is compact but informative. Every word 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?

With no output schema, the description supplies the essential return vocabulary, including the caveat that winning side is included only when determinable. It could add sorting or defaults, but those are largely covered by the schema and the word 'recent.' For a read-only list tool, this is sufficiently complete.

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

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

The input schema already describes all three parameters with defaults, ranges, and meaning, and schema coverage is 100%. The description adds no parameter-level detail, which is acceptable because the schema carries the full burden. 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 a specific verb and resource: 'List recent HIP-4 settlements.' It then lists the exact return fields, making the tool's purpose concrete and distinguishable from sibling tools about outcomes, trades, and volume. A settlement-specific listing tool is clearly separate from hip4_outcome_summary and hip4_outcome_recent_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 description makes the basic use case obvious—retrieve recent HIP-4 settlements—but it does not explicitly state when to prefer this tool over alternatives or when not to use it. No sibling differentiation or exclusion guidance is provided, so the agent must infer suitability from the name and return fields.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context beyond annotations by specifying the access tier required and enumerating the returned fields, though it does not cover pagination or sorting 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. It front-loads the core purpose, then efficiently lists return fields and the access requirement.

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 ranking tool with no output schema, the description compensates well by listing the returned fields and required access tier. It does not define the exact ranking metric behind 'recent outcome activity' or specify ordering, but this is a minor gap given the simple parameter set and annotations.

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

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

Schema description coverage is 100%, so all three parameters (days, limit, useToonFormat) are already documented with defaults and bounds in the input schema. The tool description adds no additional parameter-level meaning, which matches the baseline expectation for fully covered schemas.

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 and resource ('Rank top HIP-4 outcome traders') and specifies the output fields, making the tool's purpose clear. It does not explicitly differentiate itself from similar siblings like hip4_most_active or pulse_leaderboard, so it falls just short of a perfect score.

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

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

The description clearly states the tool ranks traders by recent outcome activity, which gives an agent the context needed to select it. It also mentions the access requirement ('Starter-or-higher key'), but it does not name alternatives or explicitly state when not to use 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?

Goes well beyond the read-only/idempotent annotations: discloses the tier requirement, the sort key (gross notional descending), the connector-applied cap because the API route has no paging, the truncation metadata returned (count, totalCount, truncated, note), and the API's days clamping to 90 and to mainnet launch. This is the kind of behavioral context annotations cannot carry.

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

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

Front-loads purpose, then requirement, then ordering/truncation, then clamping — a sensible order. It is dense and delivered as one long paragraph with an em-dash run, but nearly every clause carries decision-relevant detail.

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

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

With no output schema, the description carries the return-shape burden and does so by listing the row fields and the truncation envelope. Combined with auth tier, sorting, capping, and clamping rules, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: the connector-side cap rationale for `limit` and how raising it or shortening `days` changes results. The days clamp is partly a restatement of the schema, keeping it out of the top band.

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

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

States a specific verb and resource ('Get one wallet's HIP-4 outcome history') and enumerates the returned fields (outcome ID, side index, side token, fills, net shares, gross bought/sold USDH, realized PnL, first/last traded). The wallet-scoped framing implicitly separates it from non-wallet HIP-4 siblings, but it never names an alternative to route against, so it stops short of the top band.

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?

Provides a real prerequisite ('Requires a Starter-or-higher key') and tells the agent how to widen results ('raise limit or shorten days to see more'), plus a pointer to data_coverage. However, it never states when to reach for this tool versus siblings like hip4_top_traders or hip4_outcome_summary, so usage is only implied.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: the server resolves synonyms automatically, and the tool returns trade venues, collateral tokens, open interest per venue, and synonyms. This goes beyond annotation basics without contradicting them.

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

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

Three sentences, each earning its place: what it does, what it returns, and when to use it. No filler, no repetition of schema annotations, and the main lookup purpose 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 simple two-parameter read-only tool, the description covers the core behavior, return content, and usage context. It does not mention error behavior for unknown assets, but given the rich annotations and full schema coverage, the description is sufficiently complete 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 coverage is 100%, so the schema already documents both parameters and gives examples for 'canonical.' The description reinforces synonym resolution and ties canonical names to examples, but it does not add substantial new parameter semantics 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 a specific verb ('Lookup'), a precise resource ('one asset'), and the expected output fields (venues, collateral tokens, open interest, synonyms). It also clarifies that both canonical names and synonyms are accepted, which distinguishes it from plural list tools like list_assets and list_markets.

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

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

The description gives an explicit usage condition: 'Use when the user mentions a specific asset and you need its venue availability.' However, it does not explicitly state when not to use it or name alternatives such as list_assets for multi-asset lookups, so it stops short of full guidance.

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

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

Annotations already establish a safe read-only idempotent operation, so the bar is lower. The description adds useful behavior beyond that: assets are canonical and grouped by economic exposure, and each entry includes synonyms, venues, aggregate OI, and a cross-market flag. It does not disclose size/performance traits, but they are not critical for a read-only directory with rich annotation coverage.

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

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

Two sentences with no filler: the first defines scope and output content, the second gives usage examples. The distinguishing scoping phrase 'grouped by economic exposure (not by venue ticker)' is placed early and earns its place.

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

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

For a simple read-only tool with two well-described optional parameters and no output schema, the description covers what the result contains and when to prefer it. It does not mention the closely named sibling list_asset (singular), so an agent hunting for a single-asset detail view gets only partial routing context, but this is a minor 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%, so the schema already documents both optional booleans. The description reinforces crossMarketOnly by defining cross-market as 'listed on 2+ venues' and supplying a matching query example, but it adds no new information about useToonFormat or syntax.

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 names a precise resource: a directory of every canonical Hyperliquid/builder-dex asset, and specifies how it is organized (economic exposure, not venue ticker). It also differentiates from list_markets by giving concrete query phrasings, so an agent can identify this tool without opening 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?

Explicitly instructs to prefer this over list_markets for specific user questions ('what assets are available?', 'which venues is GOLD on?', 'show me cross-market assets'). This is direct when-to-use guidance that routes to the correct sibling.

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, destructiveHint=false, and openWorldHint, so the safety profile is largely covered. The description adds value by disclosing the exact field set returned and the scope (native + builder dexes), though it omits pagination/result-size behavior for a potentially large list.

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

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

Front-loaded with the canonical designation, then scope, then return fields, then usage triggers and the alternative. Three dense sentences with little waste, though the CLAIMANT-style emphasis and the trigger list make it slightly longer than strictly necessary.

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

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

There is no output schema, and the description compensates by enumerating the returned fields and the market universe covered. It stops short of describing pagination or result limits for a 'returns every symbol' tool, but is otherwise complete enough to invoke correctly.

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

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

Schema description coverage is 100% and both parameters (dex enum, useToonFormat) are documented in the schema, so the description need not repeat them. It does not add syntax or filtering semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb (list/returns) and resource (every trading symbol on Hyperliquid and its builder dexes) and enumerates the returned fields (mark price, 24h volume, funding rate, OI, 24h change). It explicitly distinguishes itself as the CANONICAL discovery tool versus list_assets for asset-level grouping.

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 concrete triggers ('what markets are available?', mentions of commodities, stocks, or builder-dex markets) and names the alternative sibling (list_assets) with the condition that selects it. Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context by specifying the metric returned (net long/short bias per tier) and the live temporal scope. No contradiction; the extra detail goes 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?

Three short sentences convey purpose, output, and a concrete example. The first sentence and second sentence overlap slightly ('what each trader cohort is doing' vs 'net long/short bias'), but the example question earns its place and the overall description is tight and readable.

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 fully documented parameters, the description adequately explains the resource, the metric, and the live scope. There is no output schema, so the description's mention of per-tier net bias helps fill that gap. It could mention tier definitions or data latency, but these are not essential for correct invocation.

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

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

Schema description coverage is 100%, and both coin and useToonFormat already have clear descriptions in the schema. The tool description does not add parameter-level detail, but the schema fully carries that burden, so baseline 3 applies.

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

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

Description states a specific verb ('See... Returns') with a precise resource: net long/short bias per trader cohort on a given coin, right now. It names example tiers (Apex, Sharps, Middleweights) and gives a concrete question it answers, making the tool's purpose unmistakable and distinct from history-oriented 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 'RIGHT NOW' phrasing and example question clearly establish this as the tool for current, real-time cohort bias. It does not explicitly name alternatives like live_cohort_bias_history, but the live-vs-history contrast is strongly implied and the use case is concrete.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, non-destructive), so the description only needs to add context. It does so by disclosing that the tool returns hourly net-bias snapshots and can return all tiers or a single tier over time. It adds useful behavioral detail 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?

Three sentences, each earning its place: purpose, usage triggers, and return shape. The most important information is front-loaded, and there is no filler 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?

With no output schema, the description adequately characterizes the return value as hourly net-bias snapshots per tier over time. It covers the main parameter semantics and usage context. It does not describe edge cases like unknown coins or value units, but the schema covers parameters and annotations cover safety, making this sufficient for most invocation scenarios.

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 semantic value beyond the schema by explaining what 'bias' means in context ('accumulating or exiting') and by clarifying how the tier parameter behaves ('each tier or a specific tier'). This goes beyond the schema's terse field descriptions.

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

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

The description states a specific verb ('Get'), a clear resource ('historical cohort bias data for a specific coin'), and a precise scope. It also includes example user questions that make the purpose immediately understandable and distinguish it from the sibling 'live_cohort_bias' by emphasizing 'historical' and 'hourly... over time'.

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

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

The description gives explicit trigger phrases ('were smart-money cohorts accumulating or exiting?' and 'which tier flipped first?'), which is strong when-to-use guidance. It does not mention when not to use this tool or point to alternatives like pulse_cohort_bias_history, 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds non-obvious behavior: markDislocations is omitted by default, the response self-describes via sections/omittedSections, and freshness/availability stamps live in the payload. The ~700-rows-per-12h size note helps the agent judge payload cost.

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

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

Front-loaded with purpose and use-cases, then payload contents, then the include caveat and alternative tool. Dense but every sentence carries actionable information; the parenthetical size detail justifies the default omission rather than padding.

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

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

With no output schema, the description compensates by naming the returned sections and the response's self-describing metadata (sections, omittedSections, freshness/availability). An agent has enough to call this correctly and interpret the result shape.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics for include beyond the schema by explaining the default omission and that markDislocations is bucketed to the max-|basisPct| minute per hour. It does not add anything for hours or useToonFormat, which the schema already documents.

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?

Opens with a specific verb+resource ('Get the historical risk lane for a coin') and enumerates the exact sections returned (hourly OI, long/short history, cohort rotation, candles, liquidation counts). It implicitly delineates itself from live_mark_dislocations and live_coin_risk_snapshot by scoping to historical breadth across many sections.

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 concrete triggering questions ('how did this setup become fragile?', 'did smart money rotate before the move?') and names an explicit alternative with its selection condition ('use live_mark_dislocations for finer resolution'). It also routes the agent to data_coverage for the risk-data window.

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 safety is covered. The description adds temporal scope ('current') and enumerates the risk dimensions returned, but it does not disclose any additional behavioral traits such as data freshness, formatting quirks, or limits. This is adequate but not richly transparent.

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

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

The description is three compact sentences: purpose, usage triggers, and returned content. It is front-loaded with the core action, every sentence earns its place, and there is no filler or redundant restating of the tool name.

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

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

With no output schema, the description compensates by listing seven return categories (OI, wallet count, long/short posture, position-size concentration, top positions, liquidation heatmap, 7-day liquidation totals). This gives an agent a solid mental model of the result. It is not a 5 because the exact shape of the heatmap and toon-format output is left unspecified.

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 both 'coin' and 'useToonFormat' already having clear descriptions including the prefix convention for builder dex markets. The tool description itself adds no new parameter-level meaning, so it meets the baseline but does not exceed it.

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: 'Get the current risk snapshot for a single coin.' It distinguishes itself from siblings like live_coin_risk_history and live_risk_overview via 'current' and 'single coin,' and reinforces intent with concrete user questions and a list of returned risk dimensions.

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

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

The description gives explicit trigger scenarios ('is BTC crowded?', 'who is holding the risk?', 'how liquidation-prone is this market right now?'), making the intended use clear. It does not explicitly name alternative tools or state when not to use it, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that the tool surfaces liquidation clusters across price levels for any coin, but does not cover operational behaviors such as rate limits, data freshness, or exact return format. 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 two sentences with no filler. The first sentence front-loads the action and resource, and the second explains what the tool shows and when it is useful. Every clause earns its place.

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

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

The schema documents all four parameters and annotations cover the read-only, idempotent, non-destructive nature of the tool. The description explains the core output concept, liquidation clusters across price levels, which is sufficient for an agent to understand the tool's purpose even without an output schema.

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

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

Schema description coverage is 100%, and each parameter (coin, range, buckets, useToonFormat) already has a detailed description. The tool description adds no parameter-specific meaning, but it does not need to because the schema carries the full burden.

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 and resource: 'Get a liquidation heatmap for any coin.' It further clarifies the tool's distinguishing purpose by explaining it shows liquidation clusters across price levels, which separates it from sibling tools like live_recent_liquidations or live_liquidation_summary.

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

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

The description implies the tool is for identifying support/resistance and potential squeeze zones, which gives useful context. However, it does not explicitly state when to use this heatmap versus alternatives like live_liquidation_summary or live_recent_liquidations, nor does it mention any 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 establish readOnly, idempotent, and non-destructive behavior. The description adds value beyond annotations by disclosing the aggregated nature, the time-window scope, and the specific output components (event count, penalty fees, closed PnL, per-coin rollups, liquidation timeline). 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?

Two efficient sentences with no filler. The core purpose and time-window behavior are front-loaded, followed by a compact list of return contents and intended use cases. 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?

With no output schema, the description compensates by enumerating the main return components. It could be richer by specifying ordering, timeline granularity, or aggregation semantics, but for a read-only summary tool with three optional parameters, this is reasonably complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a little context by mentioning time window and per-coin rollups, which map to 'since' and 'coin', but it does not meaningfully enhance understanding of 'useToonFormat' or parameter syntax beyond the schema.

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

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

States a specific verb and resource: 'Get an aggregated liquidation summary over a time window.' The description further clarifies intended use cases ('summaries, rankings, and trend analysis') and distinguishes this from sibling liquidation tools like live_liquidation_heatmap and live_recent_liquidations by emphasizing aggregation and rankings.

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

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

Explicitly says this is the best liquidation tool for summaries, rankings, and trend analysis, giving the agent a clear use case. It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough to route the agent 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 this tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful functional context about global vs. per-coin behavior, but it does not disclose response shape, data freshness, or any other behavioral constraints beyond what the schema and annotations already imply.

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

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

The description is two sentences, front-loaded with the core action, and wastes no words. The conditional behavior is stated clearly and compactly.

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?

This is a low-complexity read-only data tool with three optional parameters and no output schema. The description covers the main invocation modes and key optional behavior. It does not describe the return value structure, but for a simple ratio query this is not 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?

Schema description coverage is 100%, so the baseline is 3. The description restates the coin conditional behavior and the optional historical window, but adds little beyond the schema: it does not explain useToonFormat or any parameter formatting details beyond what is already documented.

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

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

The description uses a specific verb ('Get') and resource ('long/short ratio data'), and immediately clarifies the two main scopes: global vs. per-coin. This clearly differentiates it from sibling tools, most of which concern other market or trader metrics.

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

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

The description provides clear conditional usage guidance: omit coin for global ratio, provide coin for a specific pair, and optionally request historical data. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide when to call 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds substantial behavior: per-minute source series, bucketing rule (max-|basisPct| minute per resolution bucket), newest-kept truncation, and the totalCount/truncated/note signals emitted when rows are dropped. It also points to data_coverage for the freshness stamp.

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

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

Front-loaded with the purpose, then return shape, then bucketing/truncation semantics, then a usage tip — a sensible ordering with no filler sentences. It is dense and runs long for a single paragraph, but each clause carries information.

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

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

With no output schema, the description carries the return-shape burden and does: timestamped mark price, oracle price, basis percentage, plus totalCount/truncated/note metadata. Combined with the bucketing and paging guidance, an agent has everything needed to call and interpret 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?

Schema coverage is 100% and already documents defaults, bounds, and the bucket rule, so the baseline is 3. The description goes further by tying resolution and limit together into an aggregation/truncation model and by advising the resolution choice for a 7-day window, adding practical meaning beyond the field list.

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

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

States a specific verb+resource ('Get historical mark/oracle dislocation data for a coin') and anchors it with a concrete example question about basis stress preceding liquidations. The resource is distinct from every sibling (risk snapshots, liquidation summaries, OI history), so an agent can select it without opening the schema.

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

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

Gives actionable usage guidance: when to reach for it (diagnosing basis/oracle drift before liquidations), how to get 7 days at full detail (resolution=1h), and how to page (shorten hours). No explicit when-not or named alternative sibling, which keeps it 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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the data source is Hyperliquid's Info API, snapshots are hourly, and the payload includes open interest, mark price, and 24h notional volume. There is 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 composed of four short sentences, each earning its place: identity/source, output contents, use cases, and time-range defaults. It is front-loaded with the core purpose and contains 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?

For a tool with 4 parameters, full schema coverage, and no output schema, the description covers the essential behavioral contract: output fields, frequency, data source, default range, and maximum range. A minor omission is explaining what 'toon format' means, but that is addressed in the schema's parameter 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 all four parameters are already documented in the schema; baseline is 3. The description's wording around 'per-dex' and 'official' reinforces the meaning of the dex and coin parameters but does not meaningfully add constraints or format details beyond the schema.

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

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

The description opens with 'Official per-dex open interest for a coin, sourced from Hyperliquid's Info API (not derived from live_positions)', which names the resource, scope, and source while explicitly distinguishing it from computed OI. It also states what the tool returns: hourly snapshots with open interest, mark price, and 24h notional volume.

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 has an explicit 'Use when...' clause listing venue-reported ground truth, per-dex breakdown, and cross-checking computed OI against official numbers. It does not name a specific sibling tool as an alternative or provide an explicit when-not, but the selection context is clear enough for an agent to choose 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 some scope context (coin-specific vs. global) but no additional behavioral details like pagination, output format, or latency. This is adequate but not notably informative.

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 wasted words. It front-loads the purpose, then adds use cases and constraints. Every sentence contributes to helping the agent decide and invoke the tool.

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

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

The description covers the main invocation choices (coin or global, time window) and conveys the analytical intent. There is no output schema, so a bit more detail on the response shape or granularity could help, but it is not critical for correct selection and invocation.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description reinforces the defaults and max ('Default 7 days, max 30 days') and the global option ('Omit for global OI'), but it does not add new meaning beyond what the schema 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 states a clear verb ('Get') and resource ('historical open interest data'), with explicit scope: any coin on Hyperliquid or global OI. It is not a tautology and is easy to understand. However, it does not explicitly differentiate itself from sibling tools like market_historical_oi or live_official_oi, so it loses the fifth point.

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 use cases ('Best for identifying accumulation/distribution phases, market conviction shifts, and whether a move was backed by positioning'), which tells the agent when this tool is appropriate. It does not mention when not to use it or name alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is covered. The description adds useful behavior beyond annotations by noting the data source ('from the syncer'), emphasizing 'real' liquidation events, and listing returned fields. This is meaningful context for an agent deciding whether the tool matches the query.

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

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

The description is compact and front-loaded: the core action is in the first sentence, followed by concrete example queries and the returned fields. Every sentence earns its place without extraneous detail.

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

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

For a read-only list tool with no required parameters, full schema coverage, and no output schema, the description provides enough context: what it returns, example user intents, and the source of the data. It could be slightly more complete by contrasting with live_liquidation_summary or live_liquidation_heatmap, but the available information is sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, so all four parameters are already well-documented in the input schema. The description's example about BTC liquidations over 30 days indirectly reinforces the coin and since parameters, but it does not add new semantic detail beyond what the schema 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 clearly states the tool gets real liquidation events from the syncer, with a specific verb and resource. It provides example questions and the returned fields, making the tool's purpose understandable. It does not explicitly name or differentiate sibling tools like live_liquidation_summary or live_liquidation_heatmap, so it stops short of a 5.

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

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

The 'Best for questions like...' phrasing gives concrete usage context, such as locating actual forced unwind activity or requesting BTC liquidations over a period. It does not explicitly state when not to use this tool or point to alternatives, but the examples are enough for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety/behavior is well covered. The description adds useful context about what data the snapshot aggregates and includes, but it does not disclose additional behavioral traits such as time windows, sampling, or any caveats about the returned data.

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