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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context: tiers are lifetime labels emitted as legacy slugs, missing wallets roll into 'untracked' so counts always sum to totalUsers, attribution undercounts relative to ledger revenue due to trigger-order fills, results are ordered largest cohort first, and Pro tier is required. No contradictions 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 dense but every sentence earns its place: core resource and metrics, tier semantics and untracked bucket, attribution caveat, concrete use cases, and access requirement. It is front-loaded with the most important compositional detail before caveats and use cases.

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

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

With no output schema, the description carries the burden of explaining the return contents, and it does: fields returned, cohort ordering, tier semantics, untracked behavior, dataNotes caveat, and access restrictions. For a moderately complex 3-parameter tool, nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents builder, period, and useToonFormat. The description echoes the period concept and notes the day/week/month window, but adds no new parameter-level meaning beyond the schema. This matches the baseline 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 clearly identifies the resource — a builder's attributed users — and specifies the exact segmentation (all-time profitability and size tiers) plus the metrics returned, so an agent can tell it apart from pulse cohort tools. It distinguishes from siblings by explicitly noting these are lifetime tiers, not the 30d-rolling tiers used by pulse cohort tools. However, it opens with a noun phrase ('Cohort composition of...') rather than an explicit verb like 'Returns' or 'Lists'.

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 explicit use cases: 'is builder X's user base smart money or exit liquidity?' and 'do whales or shrimp pay most of its fees?'. It also gives a when-not signal by contrasting the lifetime tiers with the 30d-rolling tiers used by pulse cohort tools, steering agents toward the correct tool family.

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?

The description goes well beyond the annotations, disclosing that zero-activity cells are zero-valued and never omitted, that weekdays and hours are UTC, that the window is fixed at 84 days, that attributed fills undercount ledger revenue, that Pro tier is required, and that the first call can take ~90 seconds and should be retried on timeout. This is rich, actionable behavioral context with no contradiction against the readOnly/idempotent hints.

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

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

Every sentence carries meaningful information, and there is no filler, but the first sentence is a very long run-on that buries the main purpose under output-shape details. Better front-loading—e.g., a direct 'Returns a 7x24 grid for a builder's attributed trades'—would make the description easier for an agent to parse quickly.

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 present, the description fully compensates by specifying the exact shape of days[] and hours[], the cell fields, zero-value behavior, UTC semantics, the fixed window, known undercounting, access tier, and performance/caching behavior. An agent has everything needed to invoke the tool and interpret its response 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%, with both builder and useToonFormat already documented. The description adds useful clarifications such as 'no period parameter' and the fixed 84-day window, but it does not substantially improve parameter understanding beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the resource (a builder's attributed flow) and the core deliverable: a 7x24 weekday-by-hour grid of volume, fees, and fills. It lacks an explicit verb like 'returns' or 'computes,' starting instead with a 'When...' clause, but the intended function is unmistakable and distinct from sibling heatmap tools.

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

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

The description gives concrete use cases: determining when a builder's volume peaks, whether activity is bot-like, and when it is safe to ship. It does not explicitly name alternatives or say when not to use this tool, but the use-case framing plus the fixed-window/UTC constraints give an agent enough context to select it 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?

Even though annotations already establish readOnly/openWorld/idempotent behavior, the description adds substantial non-obvious behavioral details: fixed minFills=3, trailing-year cohort construction, per-wallet aggregation, truncation bias in young cohorts, dataNotes in the response, and slow/cached first call. This goes well beyond what annotations provide.

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

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

The description is dense and run-on in places, but every sentence carries meaningful information: metrics, cohort definition, caveats, use case, tier, and performance. It is front-loaded with purpose and needs to be long because there is no output schema to document the return values.

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

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

For a complex metric-heavy tool with no output schema, the description is remarkably complete: it defines the universe, the per-wallet computation, all metric names, the bias caveat, the comparison tool, required tier, and call behavior. An agent has enough context to invoke it correctly and interpret the response.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that builder is the only substantive analytical parameter ('no other parameters') and explaining the cohort semantics tied to that address. It does not add much about useToonFormat beyond the schema, but schema already covers it well.

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 analytical question ('how fast and how unevenly does builder X monetize a new user?'), names the exact resource (a builder's trailing-year acquisition cohort), and enumerates concrete metrics. It explicitly differentiates itself from builder_lifecycle, making sibling confusion unlikely.

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

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

The description gives an explicit use case in quotes, explicitly says what it is NOT ('NOT the lifetime user base builder_lifecycle covers'), and provides operational guidance such as Pro tier requirement, ~90 second first-call latency, caching, and retry on timeout. This fully equips 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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses a material data caveat: 'Attributed metrics slightly undercount versus ledger revenue because trigger-order fills (stop/TP) are not yet attributed.' It also explains the 'verified' stamp and that builderName is omitted when unknown, which are useful behavioral details. The access-tier requirement is an additional disclosure annotations don't capture.

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 purposeful: it front-loads the core purpose, then enumerates returned fields, adds the undercount caveat, and closes with use cases. The em-dash-heavy structure makes it slightly harder to parse, but every clause adds information an agent needs. It earns a high score for no wasted sentences, though it could be tightened.

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

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

With no output schema present, the description carries the burden of describing return values, and it does so thoroughly: fill volume, distinct users, fill counts, preceding-window deltas, feeTenthsBp, and builderName. It also tells the agent where to look for caveats (dataNotes) and what 'verified' means. Combined with the schema and annotations, nothing essential is missing for calling this tool correctly.

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

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

All four parameters (limit, offset, period, useToonFormat) already have full descriptions in the schema, so baseline is 3. The tool description reinforces the period semantics ('immediately preceding window for deltas') and references feeTenthsBp as an output field, but it adds no new parameter-level guidance beyond the schema. Since schema coverage is 100%, the description need not compensate.

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 precise definition: 'Builders (HIP-3 dexes, frontends, bots) ranked by exact revenue from Hyperliquid's on-chain cumulative builder-fee ledger over the requested period.' This specifies the verb, resource, and data source, and distinguishes it from sibling builder_* tools that focus on profiles, fills, or traders. The inclusion of 'Use for...' question templates further anchors what the tool answers.

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

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

The description explicitly states two canonical use cases: 'which builders earn the most?' and 'is builder X growing?', giving an agent a clear decision rule for selecting this tool. It also states the access precondition ('Requires Starter tier or higher'), but does not name alternative builder_* tools or give a when-not-to-use condition, so it stops short of full differentiation.

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

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

Annotations only provide readOnly, openWorld, idempotent, and non-destructive hints. The description goes far beyond them by defining the five mutually exclusive status windows, the lifetime ORDERS-plane universe including unfilled orders, the formulas for retention, churn, and competitive loss, and the fact that the status test reads only recent attributed fills. This gives the agent genuinely useful behavioral context for interpreting the results.

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

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

The description is a dense, single run-on sentence with heavy parentheticals and nested clauses, which makes it harder to parse than necessary. That said, nearly all the content is relevant given the genuine complexity of the lifecycle status model, so the length is justified even if the structure is not ideal.

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

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

With no output schema, the description carries the burden of explaining return semantics, and it does: status counts, shares, ratios, competitive-loss fees, and the lifetime-universe caveats are all covered. It also notes the response dataNotes and Pro-tier requirement. The main completeness gap is the misleading 'no other parameters' statement and the absence of any prose mention of the useToonFormat flag.

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 builder and useToonFormat. The description repeats the 0x-hex builder address requirement but actively misleads by claiming 'no other parameters' while the schema includes the optional useToonFormat boolean. That false statement undermines the parameter guidance more than the prose adds value.

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

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

The description clearly identifies the tool as a lifetime lifecycle snapshot of every wallet that has traded via a builder, with an explicit use case: 'how many of builder X's users are still active, and how many did a rival take?'. It also distinguishes itself from builder_retention by contrasting a single historical snapshot with a per-cohort monthly grid, making the tool easy to select correctly.

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

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

The description gives a direct use case in quoted form, states the Pro-tier requirement, and explains the key alternative boundary: this is one snapshot of the whole historical user base rather than builder_retention's per-cohort monthly grid. It also clarifies when the switched status is only detectable, which helps an agent decide if this tool fits the attribution context.

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

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

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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral context beyond that: attributed metrics undercount ledger revenue due to trigger-order fills, builderName comes from a curated registry and may be omitted, and the tool returns 404 for addresses with no fee-ledger revenue. This is exactly the kind of caveat-rich detail an agent needs.

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

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

The description is long but densely informative with no filler. It front-loads the core purpose, then adds caveats, error behavior, usage examples, and access requirements. It could be slightly streamlined, but every sentence carries meaningful operational 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?

There is no output schema, so the description properly carries the burden of explaining return contents, including the daily series, undercounting caveat, registry behavior, and 404 error case. It also covers access tier and concrete use cases, making the tool fully actionable without needing to open sibling definitions.

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 builder, period, topCoins, and useToonFormat. The description reinforces period semantics by listing day/week/month and explains that 'top coins' refer to attributed volume, aligning with the schema. It does not add significant new parameter-level detail beyond the schema, 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?

The description names a specific verb and resource: 'Single-builder overview for a 0x-hex builder address' and enumerates the exact outputs (ledger revenue, timestamps, fee tokens, fee rate, daily series, top coins, profitable wallets). It clearly differentiates itself from the many sibling tools by focusing on a holistic per-builder summary rather than trades, fills, or leaderboards.

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 explicit use cases: "Use for 'how is builder X doing?' or 'what do people trade on frontend Y?'". It also states the tier requirement. It does not explicitly contrast itself with sibling tools like builder_leaderboard or builder_fills, but the use-case guidance is strong enough to route an 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?

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 already declare readOnly/openWorld/idempotent/non-destructive hints, so the bar is lower, but the description adds valuable behavioral caveats: attributed fills undercount versus ledger revenue, trigger-order fills are not yet attributed, dataNotes exist in the response, and cohort tiers are lifetime labels unlike 30d-rolling pulse tiers. 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 but every sentence earns its place: purpose, row fields, a data caveat, concrete use cases, and access tier. It is front-loaded with the core function and avoids filler or repetition.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: each row's fields are enumerated, including untracked nulls and the 0-if-untracked equity behavior. It also covers the undercounting caveat and Pro tier requirement. Combined with full schema param coverage, an agent has enough context to call this 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. The description aligns with schema parameters by mentioning sortable by builder fees/volume/PnL and window, but it does not add meaning beyond the schema's own field descriptions. The schema already documents sort, limit, offset, period, builder, and useToonFormat adequately.

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 wallets that traded via a builder address, scoped to a window and sortable by fee, volume, or PnL. It also distinguishes itself from pulse cohort tools by explicitly contrasting lifetime tiers with 30d-rolling tiers, so an agent can tell it apart from siblings without inspecting schemas.

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

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

The description gives concrete use cases: 'who are builder X's biggest fee payers?' and 'are smart-money wallets using this frontend?'. It also differentiates from pulse cohort tools by calling out the tier semantics difference. However, it does not explicitly state when not to use this tool or name a specific sibling alternative for comparison, so it falls short of full exclusion guidance.

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

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

Annotations already 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 convey the safety profile (read-only, idempotent, non-destructive), so the description does not need to restate that. It adds contextual value by framing the data as a daily trajectory for outcome-market trends, but does not disclose additional behavioral details such as ordering, pagination, or limits.

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

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

Two sentences with no filler. The primary action and included metrics appear first, followed by the intended use case. Every part earns its place.

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

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

For a simple read-only trend tool with well-documented parameters and rich annotations, the description is complete. It lists the returned metric dimensions and the intended analytical use, so an agent can invoke it correctly without needing 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 coverage is 100% and both parameters (days, useToonFormat) have descriptive documentation in the schema itself. The description adds general context about the data being daily but does not need to compensate for missing schema information.

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 daily HIP-4 volume trajectory') and enumerates the exact metrics returned (fills, unique trades, unique wallets, contracts, notional USDH). This clearly identifies the tool's scope and differentiates it from sibling HIP-4 tools like outcome summaries or 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 gives clear intended context: 'Use for outcome-market activity trends.' This tells an agent when the tool is appropriate, though it does not explicitly mention when not to use it or name alternative 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 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 cover read-only, open-world, idempotent, non-destructive behavior, so the description only needs to add value beyond that. It does add useful context: it lists only contracts that traded recently, mentions question metadata 'when available', and names the returned trade/volume/timestamp fields. It does not mention ordering, pagination, or result limits.

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

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

Three short sentences: an action statement, a compact list of return fields, and a usage directive. Every sentence earns its place with no filler or redundancy.

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

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

For a simple optional-parameter list tool with no output schema, the description covers what is listed, what fields are returned, and when to use it. It does not explain result ordering or caps, but the schema fully covers the hours and format 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 hours and useToonFormat are already fully documented with defaults, bounds, and behavior. The description adds no additional parameter-level meaning, so the baseline score 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'), resource ('active HIP-4 outcome contracts'), and scope ('traded recently'), then enumerates the returned fields. It is clearly about listing contracts rather than summarizing trades or questions, though it does not explicitly contrast with sibling tools like hip4_outcome_recent_trades or hip4_most_active.

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 'Use when users ask what prediction/outcome markets are active,' giving a clear context for when to invoke this tool. It does not specify when not to use it or name alternative tools, but the guidance is direct and not misleading.

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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds operational value by stating the authentication requirement ('Requires a Starter-or-higher key') and specifying the returned data fields, which goes beyond the annotations 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?

The description is a single well-structured sentence that front-loads the primary purpose, then lists the return fields, then states the access requirement. Every element earns its place and there is no redundant or filler content. It is concise without sacrificing necessary 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 present, the description compensates by listing the expected return fields in reasonable detail and also discloses the auth requirement. It is sufficient for basic invocation, though it could be slightly more complete by noting how this tool relates to sibling outcome-focused tools or by mentioning any pagination or result-size limits.

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

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

Schema description coverage is 100%, so the parameters days, address, and useToonFormat are already fully documented in the input schema. The description does not add extra parameter-level meaning, but it doesn't need to because the schema carries that burden adequately. Therefore a 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 uses a specific verb and resource: 'Get one wallet's HIP-4 outcome history,' and then enumerates the exact fields returned. This clearly differentiates it from sibling tools like hip4_outcome_summary or hip4_outcome_recent_trades by emphasizing per-wallet detailed history. It leaves no ambiguity about what the tool does.

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

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

The phrase 'one wallet's HIP-4 outcome history' implies the tool is for per-wallet historical detail, but the description never explicitly states when to choose this over alternatives such as hip4_outcome_summary or hip4_outcome_recent_trades. No exclusions or alternative routing are provided, so the usage context is only implied rather than explicit.

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

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

Annotations already 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, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it is the canonical discovery tool, returns the full market set with specific fields, and shares data with pulse_market_overview. No contradictions or hidden side effects are present.

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

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

The description is compact and front-loaded with the core function, then gives trigger examples and sibling routing. Every sentence earns its place, and there is no fluff or redundant restating of the title.

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

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

For a simple two-optional-parameter read-only tool with no output schema, the description is complete: it names the return fields, states when to use it, and routes to alternatives. Nothing needed for correct selection or invocation is missing.

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

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

Schema description coverage is 100%, and both parameters have clear descriptions in the schema. The tool description does not add much parameter-level meaning beyond reinforcing that dexes cover builder-dex markets and that commodities/stocks are relevant use cases, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Returns every trading symbol on Hyperliquid and its builder dexes' with the exact data fields included. It also distinguishes itself from pulse_market_overview and list_assets, making it easy for an agent to select this tool over near-named siblings.

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

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

The description gives explicit trigger conditions ('whenever the user asks what markets are available?, mentions a commodity, stock, or builder-dex market') and names alternatives with routing guidance: prefer over pulse_market_overview for backward compatibility, use list_assets for asset-level grouping. This is clear, actionable, and complete.

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 (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds valuable behavioral context beyond annotations: the data is hourly, includes multiple historical series, and some data (mark/oracle dislocation history) is included only 'when available.' No contradiction exists between the description and 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 purposeful sentences: what it does, when to use it, and what it returns. The most important intent is front-loaded, and the return-component list is compact. 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 well by enumerating the major output components and caveating availability. The hours range and output format are already documented in the schema, so their absence from the description is acceptable. It could have briefly noted the default 7-day window, but the description is otherwise sufficient for a history-retrieval tool.

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

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

Schema description coverage is 100%, so the schema already fully documents coin, hours, and useToonFormat. The description does not add new parameter-specific meaning beyond reinforcing the historical nature of the data. Baseline 3 is appropriate because the schema carries the 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 the historical risk lane for a coin.' It also provides example questions and enumerates the returned data types (OI, long/short history, cohort rotation, candles, mark/oracle dislocations, liquidations), making its purpose concrete. The word 'historical' clearly distinguishes it from the sibling 'live_coin_risk_snapshot', 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?

The 'Best for questions like...' phrasing gives clear contextual guidance for when to use this tool, especially for historical risk analysis. It does not explicitly state when not to use it or name alternative snapshot/current-state tools, but the historical framing and example questions strongly imply the appropriate use case.

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 already mark the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context by clarifying the data is historical (despite 'live' in the name), bounded to the last 30 days, and composed of timestamped mark/oracle/basis values. No caveats about pagination or freshness are given, but the annotations lower the burden.

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 a front-loaded action, an illustrative use case, and a concise return-value summary. No word is wasted; the second sentence clarifies the output without 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 annotations covering safety and schema covering all parameters, the description supplies the missing output-level information (timestamped fields, 30-day history). An agent can correctly select and call this tool with the provided information alone.

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

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

The input schema already documents all three parameters at 100% coverage, including coin prefix syntax, hours bounds/default, and toon format. The description only implies the 30-day historical window and adds no parameter-specific guidance beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get historical mark/oracle dislocation data for a coin,' and immediately distinguishes the tool's focus from broader price/risk tools by naming the returned fields (mark price, oracle price, basis percentage). The example question about basis stress/oracle drift before liquidations reinforces a unique use case among the sibling tools.

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

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

It gives a concrete trigger ('Use this to answer questions like...') that maps to dislocation analysis, which tells an agent when this tool is relevant. It does not explicitly name alternatives or give when-not-to-use conditions, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, 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.

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

Two sentences with no filler. The core purpose is front-loaded, followed by practical example questions and a compact list of return dimensions. Every sentence earns its place.

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

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

Given the tool has no output schema, the description compensates by listing the key return categories clearly. It is sufficient for a single-optional-parameter, read-only overview tool. It could be slightly more complete by clarifying time windows or distinguishing itself from live_coin_risk_snapshot, but overall the agent has enough context to invoke it correctly.

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

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

The schema covers the single optional parameter useToonFormat with a description and default, so schema coverage is 100%. The tool description does not mention this parameter, but the schema already documents it fully. No additional parameter semantics are needed.

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

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

The description opens with a specific verb and resource: 'Get the exchange-wide market risk snapshot.' It clearly states the scope (exchange-wide) and enumerates concrete outputs (total open interest, leverage, crowding concentration, near-liquidation exposure, 7-day liquidation totals, top fragile coins). This distinguishes it from per-coin sibling tools like live_coin_risk_snapshot.

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 use-case examples: 'Best for questions like "what looks fragile right now?" or "which coins are most crowded?"' This provides clear context for when to use it. However, it does not explicitly name alternatives or state when not to use this tool versus sibling tools like live_coin_risk_snapshot or live_liquidation_heatmap.

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/non-destructive behavior. The description adds meaningful behavioral context: hourly snapshot granularity, notional USD denomination, per-coin vs global aggregation, and the maximum range. This goes beyond what annotations alone communicate.

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 the core purpose and key constraints front-loaded. No filler or redundant restatement 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?

For a read-only lookup with well-documented parameters, the description provides the essential missing context: historical hourly granularity, notional USD units, and the 30-day bound. A return-format example would be nice, but the description is sufficiently complete for selecting and invoking the tool.

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

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

The schema already documents all five parameters with 100% coverage, including examples and defaults. The description reinforces the 'filter by coin vs global aggregate' distinction but does not add new parameter-level semantics beyond the schema.

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

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

The description states a specific verb ('Get'), a precise resource ('historical hourly open interest snapshots'), and the unit ('notional USD'). It also distinguishes this historical tool from live siblings by explicitly saying 'historical hourly'.

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 implies historical use cases and states the 30-day max range, but it does not explicitly contrast with live alternatives like live_oi_history or live_official_oi. An agent must infer when to choose this over those siblings.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context by specifying that it returns bid/ask depth with levels and sizes on both sides. It does not overpromise or contradict the annotations.

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

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

Two sentences with no wasted words. The primary action and resource are front-loaded, and the second sentence adds practical value by stating the intended use case. No redundant restating of the tool name or schema.

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

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

For a simple read-only market data tool, the description explains what the tool returns and why it is useful. There is no output schema, but the returned shape is summarized well enough. The only minor gap is lack of explicit mention of snapshot/current nature, but this is strongly implied by 'order book.'

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 parameter descriptions are already detailed, including symbol format examples and depth constraints. The tool description adds no parameter-level detail, but it does not need to because the schema already carries that 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 opens with a specific verb and resource: 'Get the order book (bid/ask depth) for any trading pair on Hyperliquid.' It clearly states what data is returned ('price levels and sizes on both sides'), making it easy to distinguish from sibling market tools like market_price or market_historical_oi.

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-case context: 'Essential for understanding liquidity, spread, and potential support/resistance.' It does not explicitly name alternatives or exclusion criteria, but the use cases are specific enough for an agent to infer when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds mild context like 'current' and 'open positions,' but does not disclose behavior such as empty-result handling or response format nuances.

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

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

The description is two short sentences, front-loaded with the action and scope, with no filler or repetition of the tool name. Every word 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 simple read-only tool with two parameters and no output schema, the description adequately conveys what the caller gets back: entries, sizes, unrealized PnL, and leverage. It could be slightly stronger by specifying the return shape or contrasting with closed-position siblings, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline applies. The description reinforces that the address identifies any wallet, but it adds no new parameter-level meaning beyond the schema; useToonFormat is already well documented in the input schema.

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

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

The description names a specific verb and resource: 'Get all open positions for any wallet address on Hyperliquid.' It also lists the key returned data (entries, sizes, unrealized PnL, leverage), making it clearly distinct from closed-position and market-data siblings.

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

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

The description clearly implies the use case: querying a single wallet's current open positions on Hyperliquid. It does not explicitly name alternatives or exclusions, but the context is clear and no misleading guidance is present.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation, so the description does not need to restate that. The description adds the 'current mark price' semantic and symbol-format scope, but it does not disclose return-shape details or rate-limit/error behavior. 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 compact sentences, with the core action front-loaded and the symbol-format nuance in the second sentence. No filler or redundant restatement of the title.

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

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

For a two-parameter price lookup with rich read-only annotations and full schema coverage, the description plus schema cover what the tool needs: symbol formats, current-price semantics, and output-format switch. It does not enumerate the exact return fields since no output schema exists, but it is adequate for 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 both `symbol` and `useToonFormat` already documented in the input schema. The description largely repeats the symbol examples from the schema rather than adding new parameter-level meaning, so it stays at the baseline for full 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 opens with a specific verb ('Get') and resource ('current mark price for any trading pair on Hyperliquid'), making the tool's function immediately clear. It also names accepted symbol formats, distinguishing it from sibling market tools like orderbook, candles, and OI 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 concrete guidance on how to specify symbols—standard tickers vs builder dex prefix:COIN—so an agent knows exactly what inputs are valid. It does not explicitly state when not to use this tool or name alternatives, but the context is clear enough for a simple price lookup.

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