HyperSignal MCP

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the description's added value is auth/paywall requirements and the env-var cohort fallback, which are genuinely non-obvious. It also discloses the return shape ('clusters and the strongest pairs') and an 'analytics only' disclaimer, though it says nothing about rate limits or cost magnitude per call.

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?

Roughly three sentences with no filler, and every clause carries information (paywall, method, cohort source, output, disclaimer). The premium/API-key bracket is front-loaded ahead of the actual purpose, slightly delaying what the tool does, but it is legitimately actionable.

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

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

An output schema exists, so detailed return structure isn't required, and the description still summarizes it (clusters + strongest pairs). With annotations covering safety and the auth path covered in-text, the only outstanding gap is the undocumented topN parameter and the 'at most 20 wallets' constraint interaction with cohort.

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

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

Schema coverage is 50%: dex and threshold are documented inline, while topN and cohort are not. The description compensates for cohort (arg or HL_WHALE_ADDRESSES default), but topN — which appears to control how many wallets are scanned — is explained nowhere, leaving a meaningful gap for a filtering knob.

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: 'Find wallets in a cohort that hold near-identical directional exposure right now (high cosine similarity of their position vectors)' and names the interpretation (same entity, copy-bot, coordinated group). That operation is clearly distinct from sibling lookups like hl_whale_positions or hl_smart_money_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?

Gives a concrete prerequisite path — call hl_request_free_key first for a free key, or pay per call via x402 — and explains cohort sourcing (arg or HL_WHALE_ADDRESSES env var). It does not say when to prefer this over siblings like hl_whale_positions or hl_smart_money_score, so no explicit alternatives are offered.

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

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

Annotations cover the safety profile (not read-only, not idempotent, not destructive), and the description adds genuinely new behavioral facts: evaluation is asynchronous/on a schedule, firing is retrievable later, and it is premium-gated with an x402 pay-per-call or free-key path. It doesn't disclose limits on the number of standing alerts or what happens if an identical alert is re-registered.

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

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

Front-loaded with the auth/pricing banner, then the core action, then type semantics, then the retrieval pointer. Nearly every clause carries information, though the bracketed premium banner and the trailing 'not investment advice' line consume space without helping invocation.

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 7-parameter mutation with an output schema present, the description covers auth, async evaluation, retrieval, and type semantics. Missing only edge-case behavior (alert limits, symbol validation against hl_get_markets, interaction with hl_delete_alert), which are minor given the rich schema.

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

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

Schema description coverage is 86%, so the schema already carries most semantics. The description still adds value by tying each type to its relevant parameter (funding_apr→aprThreshold as |annualized funding|, price_move→movePct/window, whale_net_flip→cohort), which the bare enum in the schema lacks.

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

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

States a specific verb+resource ('Register a persistent alert the server evaluates on a schedule') and enumerates the three alert types with the exact condition each fires on. It also names hl_poll_alerts for retrieval, so an agent can distinguish it from the read-side siblings without opening any schema.

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

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

Explicitly routes the agent: call hl_request_free_key first if unauthenticated, and use hl_poll_alerts to retrieve fired events. It also gives the selection criteria among the three alert types. It stops short of stating when NOT to use it (e.g. one-off checks vs. standing watches) or any per-account alert caps.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond annotations: the PREMIUM auth requirement (hl_request_free_key or x402 pay-per-call) is a hard precondition an agent must satisfy. However, it does not state that deletion is permanent or irreversible, which matters for a destructive operation.

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

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

Two sentences with the purpose front-loaded after the premium banner. The bracketed auth note is slightly noisy but carries actionable precondition information rather than 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?

Output schema exists so return values need not be explained, and annotations cover the safety profile. The description supplies the auth prerequisite, leaving only irreversibility/confirmation semantics unaddressed.

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?

With a single parameter at 100% schema description coverage, the schema already fully documents 'id' including its source. The description adds nothing beyond 'by id,' so baseline 3 applies.

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

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

The description states a specific verb and resource: 'Delete one of your standing alerts by id.' This clearly distinguishes it from hl_create_alert and hl_list_alerts, though it does not name those siblings explicitly.

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

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

The description gives no guidance on when to use this tool versus alternatives or what preconditions exist beyond the auth note. The hint that an id comes from hl_create_alert / hl_list_alerts lives only in the schema, not the description.

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 declare destructiveHint=false and idempotentHint=true; the description earns credit by explaining WHY it isn't destructive — alerts remain retrievable via hl_poll_alerts. It doesn't address what happens when no webhook is configured (relevant to idempotency), which would have capped it at 5.

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

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

One sentence, effect first, caveat second. Nothing is superfluous and nothing essential is buried.

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

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

With an output schema present, no parameters, and annotations covering safety and idempotency, the only real behavioral question is what happens to the alerts — which the description answers. Slightly more on the post-delete state (e.g. webhook cleared vs. pending delivery) would make it fully 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?

Zero parameters, so the baseline is 4. The phrase 'this key's' usefully signals that the target webhook is scoped implicitly by the authenticated key rather than by an ID argument.

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 ('Stop POSTing') and resource (this key's webhook) with the precise effect, and distinguishes it from hl_delete_alert by clarifying that alerts themselves are not deleted. An agent can tell exactly what stops happening 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 parenthetical points to hl_poll_alerts as the alternative delivery mechanism, which implicitly answers 'when do I use this vs. keep the webhook'. It lacks an explicit 'use when the user wants to stop push delivery' framing, but the direction is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the bar is lower; the description earns credit for disclosing the premium auth flow (free key vs x402 payment) — a real invocation blocker not in the schema. It also flags that venue spreads are conditional on predictedFundings being available, which is genuine behavioral context.

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

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

One dense paragraph that front-loads the premium/API-key caveat before the functional description, which is the right ordering for an agent. It is slightly packed — the pricing and disclaimer clauses compete with the core purpose sentence — but nothing is redundant.

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

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

Output schema exists, so return values needn't be spelled out, and the description still sketches what comes back (ranked markets, sign, spreads). Auth, filtering, and the conditional-spreads caveat are covered; pagination behavior via limit/offset is the only silently assumed piece.

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?

With 50% schema coverage the description must compensate, and it does: it explains side semantics (longs-pay vs shorts-pay), the min |APR| and OI/volume filters, and what includeVenueSpreads controls. Only limit/offset go unaddressed, and those are conventional pagination defaults.

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 — 'Screen every Hyperliquid perp by annualized funding' — and enumerates the three analytical outputs (top |funding|, sign, cross-venue spreads). It is clearly distinguishable from siblings like hl_get_funding_history (history for a market) and hl_vault_screener (different resource).

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

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

Gives concrete use cases — carry candidates and delta-neutral strategies — plus the prerequisite that a key is needed (call hl_request_free_key or pay via x402). It does not name a specific alternative to use instead for, e.g., per-market funding history, so it falls short of explicit when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that it works for any public 0x address, but repeats read-only and does not add rate-limit, pagination, or dex-selection behavior beyond what the schema and 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 a single, front-loaded sentence that states the resource, lists the key return fields, and notes the read-only/public-address constraint. There is no wasted terminology.

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

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

With rich annotations, full schema description coverage, and an output schema, the description is complete enough for an agent to call the tool correctly. It also proactively lists the snapshot fields, which is useful context even though the output schema exists.

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

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

Schema description coverage is 100%, so both the address and dex parameters are already documented in the schema. The description adds context about the address being public but does not explain the dex parameter or add semantic detail beyond the schema.

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

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

The description clearly identifies the resource as a perp account snapshot and enumerates the returned fields: equity, margin usage, withdrawable, and open positions. It does not explicitly differentiate this from sibling tools such as hl_portfolio_risk or hl_whale_positions, so it falls short of the top score for sibling differentiation.

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

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

The phrase 'works for any public 0x address' gives some usage context, implying no authentication is needed for public data. However, it does not state when to use this tool instead of alternatives like hl_portfolio_risk, nor does it describe exclusions or prerequisites.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds ordering (most-recent-last) and pagination behavior, and that lookback is ignored if startTime given.

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, perfectly front-loaded with the core purpose. Every phrase adds value, no redundancy.

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

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

Covers key usage details for a 7-parameter tool. Mentions pagination but not output schema details (though output schema exists). Adequate for a data retrieval tool with good 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?

Description explains the mutual exclusivity of time range vs lookback, and specifies epoch ms for time parameters. Schema covers 57% of parameters, and description adds clarity beyond 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?

Description clearly states it retrieves OHLCV candlestick history for a coin at a given interval, using specific verbs and resource. It distinguishes from sibling tools like hl_get_orderbook and hl_get_funding_history by focusing on candles.

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?

Describes two usage modes: startTime/endTime or lookback. Provides context on pagination and ordering (most-recent-last). Does not explicitly state when to use this versus alternatives, but the use case is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read. The description adds value by detailing output (hourly rates, cumulative and average annualized) and default window. No contradictions, but it omits pagination behavior or rate limits.

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

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

The description is two sentences, front-loaded with the core action and outcome. Every sentence is meaningful: the first specifies what it does, the second gives use case and default. No wasted words.

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 5 parameters, robust annotations, and an output schema, the description covers the key aspects: data granularity (hourly), computed fields (cumulative, average annualized), default window, and use case. Missing explicit mention of pagination, but the schema provides bounds on limit/offset. Overall adequate for agent 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 60%, meaning 3 of 5 parameters have descriptions. The description adds meaning by referencing 'coin' and 'time window' (startTime/endTime) and stating the default. However, it does not cover limit/offset, so the description adds moderate value beyond the schema.

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

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

The description clearly states the tool returns 'Historical hourly funding rates for a coin over a time window, with cumulative and average annualized funding.' It specifies the verb (get rates), resource (funding history), and scope (hourly, cumulative, average). Among sibling tools, none duplicate this functionality, so differentiation is inherent.

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

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

The description explicitly says 'Use for carry analysis and funding trend,' providing clear context for when to invoke the tool. It also notes the default time window of 7 days. However, it does not mention when not to use it or provide alternative tools, but the sibling list makes it obvious that this is the sole funding history 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, openWorldHint, and destructiveHint=false, so safety and idempotency are covered structurally. The description adds the metrics returned (mark/oracle, funding periods, OI, volume), which is mildly useful context, but since an output schema exists and nothing is said about rate limits, delisted-market semantics, or pagination behavior beyond the flag, the incremental disclosure is modest.

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

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

Two sentences, front-loaded with the resource and returned metrics, then the invocation context and capabilities. No filler; every clause carries information.

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

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

With an output schema handling return shape and only optional params, the description is nearly complete for correct invocation. The notable gaps are the HIP-3 dex option and delisted-market handling, which an agent would only learn from 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?

Schema coverage is 67% and the description only broadly gestures at 'name filter, sorting, and pagination', mapping loosely to filter, sort, limit, and offset. It says nothing about the dex (HIP-3) parameter or includeDelisted, both of which are documented in the schema, so the description adds little beyond structured fields.

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

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

States a specific verb and resource (list Hyperliquid perpetual markets) and enumerates the data returned: mark/oracle price, hourly and annualized funding, open interest, 24h volume. That level of detail lets an agent distinguish it from siblings like hl_funding_screener or hl_orderbook 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?

'Use to discover valid coin symbols and scan the board' gives a clear purpose context for invocation. It does not name alternatives or exclusions (e.g., when to prefer hl_funding_screener for funding-only screening), so it falls short of explicit when/when-not guidance.

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

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

Annotations already establish that the tool is read-only, idempotent, open-world, and non-destructive. The description adds useful behavior beyond annotations by stating that results are paginated and by listing the returned order fields. It still does not mention auth needs or rate limits, but with rich annotations the added pagination detail is meaningful.

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 short and front-loaded, starting with the core resource and scope before adding behavior and usage context. The field list is somewhat redundant with the output schema, but it remains efficient overall.

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

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

Given a rich annotation set, an output schema, and a moderately documented input schema, the description is mostly complete for a read-only paginated list tool. It covers purpose, read-only behavior, pagination, and returned fields; the main omission is explicit routing guidance versus related sibling tools.

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

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

Schema coverage is only 60%, and the description does little to compensate for the undocumented parameters. It mentions the address requirement and lists 'coin' among returned fields, but does not explain the dex, limit, or offset inputs or how pagination should be controlled beyond saying 'paginated'.

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

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

The description clearly states a specific verb and resource: retrieving open resting orders for an address. It also names the fields returned, which helps an agent understand what kind of data this tool exposes. It does not explicitly distinguish itself from nearby siblings such as hl_get_orderbook or hl_get_account, so it falls short of a 5.

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

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

The phrase 'Use to inspect any wallet's live order book footprint' provides implied usage context, but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The agent can infer the basic use case, but routing between this and related orderbook/account tools is left unaddressed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds no new behavioral traits beyond what annotations provide, but does not contradict 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?

Two sentences, no waste. First sentence defines output, second gives usage guidance and alternative. Perfectly front-loaded and efficient.

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 low complexity (2 params, output schema exists, annotations present), description covers purpose, usage, and fallback. Lacks mention of real-time nature or update frequency, but overall adequate.

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

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

Schema description coverage is 100%, so baseline 3. Description does not add significant information beyond the schema's parameter 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?

Clearly states it provides Level-2 order book for a coin with specific data (top-N bid/ask levels, price, size, order count, spread, mid). Distinguishes from siblings by specifying use for microstructure and liquidity analysis.

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 when to use (microstructure, spread, near-touch liquidity) and provides an alternative action if coin is unknown (call hl_get_markets). Lacks explicit 'when not to use' but context from siblings is reasonable.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds genuinely new context: the premium paywall, the sibling call needed to get a key, the x402 alternative, and the basis-calculation side effect of spotRefs — none of which appear in structured fields.

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

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

The access/pricing condition is front-loaded in a bracketed tag, followed by purpose, then the optional basis feature, then a short disclaimer. Every sentence carries information; the trailing 'not investment advice' clause is padding but brief.

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

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

With an output schema present, return-value explanation isn't required, and the description covers access model, market scope, filtering by builder dex, and the optional basis computation. The one soft spot is no guidance on how paging behaves or when to raise `limit` toward its 200 max.

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

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

Schema coverage is 50%: `dex` and `spotRefs` are described in the schema, while `limit` and `offset` carry only type/default/bounds. The description only elaborates spotRefs marginally ('basis vs an external reference') and says nothing about dex name syntax or pagination, so it neither compensates for the gap nor adds much 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 — analytics (volume, open interest, funding, 24h change) for HIP-3 builder-deployed perp markets — and scopes it to builder dexs, which differentiates it from generic siblings like hl_get_markets and hl_funding_screener. An agent can tell what this returns without opening the schema.

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

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

Gives a concrete prerequisite and access path: needs an API key, obtainable via hl_request_free_key or paid per call through x402, and explains that spotRefs should be passed when basis vs an external reference is wanted. It does not explicitly say when to prefer this over hl_get_markets or hl_funding_screener, so it stops short of full when/when-not guidance.

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

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

Well beyond what annotations declare: it discloses the link's 15-minute expiry, that it is single-use, the 30-messages-per-hour delivery cap, and that data remains reachable via hl_poll_alerts if push is unwanted. It does not say what happens if the tool is invoked again while a link is outstanding (consistent with idempotentHint=false but unexplained), which keeps it off a 5.

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

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

Two sentences, front-loaded with the concrete artifact and its lifetime, then the follow-up action and the rate/fallback caveats. No filler; the parentheticals each carry a distinct operational fact.

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

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

An output schema exists, so the returned link needn't be described, and with no parameters there is nothing else to spec. For a zero-arg, non-destructive action gated behind a human 'press Start' step, the description gives the agent everything needed to call it and set expectations.

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

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

The tool takes zero parameters and the input schema is an empty object, so there is nothing for the description to clarify. Baseline for a 0-parameter tool applies.

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

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

States a specific verb and resource: obtain a one-time Telegram link that routes this key's standing alerts to a chat. That is unambiguous on its own, but the description never names the counterpart sibling (hl_unlink_telegram) or the alternative delivery mechanism (hl_set_webhook), so sibling differentiation is left mostly to the tool name.

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

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

Usage is implied by the operational script (get the link, open it, press Start), which tells the agent how to complete the flow once it decides to call. There is no explicit 'use this when the user wants push delivery instead of polling' framing and no exclusion against hl_set_webhook or hl_unlink_telegram, so the when/when-not decision is inferred rather than stated.

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

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

Annotations already cover read-only, idempotent, and non-destructive, so the description correctly spends its words elsewhere: it discloses the premium/API-key gating and pay-per-call option, and flags that results are an estimate over the cohort rather than exchange-wide truth. Minor gaps remain (cost magnitude, freshness/caching of the snapshot), but the value-add beyond annotations is real.

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

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

Two tight sentences: a bracketed premium/auth tag, then one dense sentence carrying purpose, output shape, scope caveat, and disclaimer. Front-loaded with the gating constraint an agent must handle before calling, with no redundant restatement of the title.

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

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

Output schema exists, so return structure needn't be explained, and the description covers the auth path, the analytic (non-advice) nature, and the estimation scope. The remaining hole is topN — an agent cannot tell what it limits (cohort size? cluster count?) from either field.

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

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

Schema coverage is 60%, and the description does illuminate bucketPct/maxDistancePct conceptually via 'bucketed by % distance from mark' and the cohort framing. However, topN has no description in either the schema or the description, and cohort membership syntax is unaddressed, so the undocumented portion is not compensated for.

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

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

Names a specific verb+resource: estimated liquidation clusters for a coin, drawn from a whale cohort's open positions, with the output shape (bucketed liq prices, notional-at-risk, nearest cascade levels) stated inline. The explicit scope caveat 'estimate over the cohort only (not exchange-wide)' separates it cleanly from exchange-wide siblings like hl_whale_positions or hl_portfolio_risk.

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

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

Gives a concrete prerequisite path — call hl_request_free_key first or pay per call via x402 — so an agent knows how to unlock access before invoking. It also states a scope boundary (cohort-only, not exchange-wide). It never explicitly says when to prefer this over hl_whale_positions or hl_coordination_scan, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by disclosing the premium access model and how to obtain or pay for a key, plus what alert fields are returned.

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

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

The description is compact and front-loads the premium access prerequisite before stating the core purpose. Every sentence contributes either access information or the list operation, with no redundant restatement of the title.

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

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

With an output schema present, the description need not explain return structure. It covers the key missing context an agent needs: premium access requirements and what the tool lists. For a zero-parameter read-only tool, this is complete enough to invoke correctly.

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

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

The tool has zero parameters, so there is no parameter semantics burden. Per the rubric, zero parameters yield a baseline of 4, and the description appropriately does not invent parameter behavior.

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

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

The description states a specific verb and resource: it lists standing alerts registered under the API key, including type, params, and last-fired time. This is clear enough for an agent to understand the operation, but it does not explicitly distinguish the tool from related siblings such as hl_poll_alerts or hl_create_alert.

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 usage by saying it lists alerts under your API key, and it provides an access prerequisite: a premium API key, or calling hl_request_free_key first, or paying via x402. However, it does not say when to choose this tool over alternatives like hl_poll_alerts, nor does it state 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?

Discloses the single most important behavior an agent needs: default is at-most-once and a lost response loses events, while reliable=true redelivers until acknowledged. This also explains the non-readOnlyHint annotation (polling mutates delivery state). It additionally notes payload signature verification via hl_signal_pubkey and the premium/API-key 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?

Front-loads the auth/pricing requirement, then delivery semantics, then mode switching, then verification. Dense but well ordered. The closing 'Call periodically to act on the market' is slightly promotional filler against an otherwise tight description.

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

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

Given a rich output schema, the description needn't describe return fields, and it correctly focuses on auth, delivery guarantees, and acknowledgement. Only the limit parameter and its pagination effect are left unaddressed.

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?

For reliable and ackThroughId the description adds real meaning beyond the schema: events redeliver until you send the highest processed event id, tying ack semantics to a concrete value. The 'limit' parameter is undocumented in both schema and description, a minor gap at 67% 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?

States a specific verb and resource ('Retrieve alert events that fired since your last poll'), scoping it to fired events since the last poll, which implicitly separates it from configuration-listing siblings like hl_list_alerts. An agent immediately knows this is the delivery-stream tool, not the alert-management tool.

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

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

Gives concrete operational guidance: call periodically, choose default mode for best-effort or reliable=true for at-least-once with ackThroughId. It clearly frames the tradeoff between the two modes. It does not explicitly contrast with hl_list_alerts or hl_set_webhook as push alternatives, so it falls short of full alternative routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds substantial context beyond them: paywall/auth path, the lognormal-diffusion modeling assumption, duplicate-listing collapsing, price-ladder consistency checks, and the notable disclosure that extreme-tail rows are flagged rather than asserted. That last point tells an agent exactly how much to trust the output.

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

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

Front-loading the PREMIUM/auth banner is correct, and every sentence carries information — methodology, edge cases, disclaimer. It is dense to the point of being a run-on list of clauses, but there is no filler to cut.

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

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

An output schema exists, so return shape needn't be restated, and the description covers auth, method, and caveats well. The remaining gap is operational: nothing on what happens with an empty result set or how many markets are scanned, which matters for a six-parameter analytics tool.

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

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

Schema coverage is 67%, and the description compensates for the gaps: 'ranked by edge' implies limit is top-N by edge, 'Optionally use perp funding as drift' maps to useFundingDrift, and 'sensitivity to the volatility input' motivates volInterval/volWindowDays. It still leaves volInterval's 1h/4h/1d trade-off and limit's cap behavior unaddressed.

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 pair: compare Polymarket price-threshold odds against Hyperliquid-implied probability, and it enumerates concrete outputs (ranked mispricings, ladder-consistency checks, dedup, sensitivity). No sibling in the list does cross-venue odds-vs-vol comparison, so it is distinguishable without opening the schema.

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

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

It gives a clear precondition ('call hl_request_free_key first... or pay per call via x402') and an implicit trigger (you want cross-market mispricing ranked by edge). However, it never names an alternative for adjacent needs — e.g. hl_score_calibration or hl_get_markets — nor states when this tool is the wrong choice.

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

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

Annotations already declare read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the premium/API-key gate, the free-key path, x402 pay-per-call, and a disclaimer that output is analytics rather than advice. It stops short of cost details or rate limits.

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

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

Front-loading the premium/access notice lets an agent resolve the paywall before reading the analytics detail, and every clause maps to actual output content. The bracketed preamble is somewhat dense but 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 an output schema present, the description needn't document return values, and it does cover the access prerequisite and analytic scope. The only gap is mild ambiguity around the 'mirror' shocks and how stress results are presented across multiple positions/dexes.

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 explains address, dex (including 'all' and HIP-3 builder dexes), and shocks. The description restates the default shock ladder (-5/-10/-20% plus mirror), which adds slight value, but says nothing about the dex parameter. Baseline 3 applies.

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

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

The description states a specific verb+resource ('Risk report for a perp address') and enumerates the exact metrics returned: liquidation distance, effective leverage, HHI concentration, stress scenarios, and Sharpe of realized PnL. It does not distinguish itself from a close sibling like hl_trader_report, leaving some ambiguity about which report to pick.

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 access requirement is well handled – it says to call hl_request_free_key first for a free key or pay per call via x402. But there is no guidance on when to use this versus hl_trader_report or hl_get_account, so the choice between risk-oriented and account/performance-oriented tools is left to inference.

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

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

Annotations show non-read-only, non-destructive. Description adds that calling again replaces the key but keeps quota, safe if lost but not a quota reset. This behavioral detail goes beyond 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?

Four well-structured sentences with no redundancy. Front-loaded with core action, then quota info, then usage hint, then repeat-call behavior. Every sentence is valuable.

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 1 optional boolean param (100% schema coverage), presence of output schema, and low complexity, the description fully covers purpose, usage, behavior, and continuation (X-API-Key header). No gaps.

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

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

Single boolean parameter 'acknowledge' with schema description covering it fully. Description does not add new meaning beyond 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 clearly states the verb 'issue' and resource 'free API key', with instant and no signup. It uniquely distinguishes from sibling tools that are all trading/data operations.

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 'call this first if a premium tool says it needs a key'. Also explains behavior on repeated calls (replaces previous key, same monthly usage). Does not state when not to use, but context is clear.

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

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

Goes well past the readOnly/idempotent annotations: names the statistic (Spearman rank correlation), the target (forward PnL over account value), the significance bar (p<0.05), the full verdict taxonomy including inverted and insufficient_data, and states that cohorts are server-selected so callers cannot steer results. That last point is a real anti-gaming disclosure an agent could not infer elsewhere.

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

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

Front-loaded with the purpose in the opening clause, then enumerates the method, verdicts, and sample-integrity caveat. Dense and slightly run-on, but every clause carries information an agent needs; nothing is filler.

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

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

An output schema exists so return structure needn't be described, yet the description still explains what the verdict labels mean and what would make the result untrustworthy (too few resolved observations). Nothing needed to interpret or trust a call is missing.

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

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

Zero parameters, so the baseline is 4; the description still usefully explains that sample composition (which cohorts) is server-controlled rather than caller-supplied, closing the question of why there is no 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?

States a specific resource (the hl_smart_money_score) and a specific operation (out-of-sample calibration: Spearman correlation of score vs. realized forward return, plus per-quartile means). It is clearly distinct from the sibling hl_smart_money_score, which produces the score itself, and from hl_signal_track_record/hl_trader_report.

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?

"Read this before treating the score as a forecast" gives an explicit trigger condition, and the framing of the tool as validation vs. production of the score implies the alternative. No explicit when-not or prerequisite/ordering statement beyond that.

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 annotations, it discloses the rate limit, public-address restriction, HMAC signing header format, and that the secret is returned only once. These are important operational details for an agent configuring alert delivery.

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

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

Three tight sentences, front-loaded with the core action and followed by the operational constraints that matter. No sentence is filler.

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

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

Given the simple one-parameter schema, present output schema, and annotations, the description covers the important behavioral context: rate limiting, signature verification, secret handling, and URL restrictions. An agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the URL parameter is already documented. The description adds meaningful constraints beyond the schema, especially that only public HTTPS addresses are accepted, though it does not explain replacement behavior for an existing webhook.

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

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

The description states a specific action and resource: posting this key's fired alerts to an HTTPS URL. It implicitly distinguishes push delivery from the sibling polling tool hl_poll_alerts and clearly connects to webhook management 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 useful scope and constraints (public HTTPS only, 30 per hour) but does not explicitly say when to choose this over polling alerts or how it relates to hl_delete_webhook. Usage is implied rather than prescribed.

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

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

The description adds significant value beyond the annotations by specifying the exact format of the returned key (SPKI DER, base64) and the canonicalization method for verification. This fully discloses the tool's behavior.

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

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

The description is very concise with two sentences, each conveying essential information without any redundancy. It is well-structured and front-loaded.

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

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

Given that an output schema exists, the description is complete. It adds the critical canonicalization detail, which is necessary for understanding the tool's return value. No gaps are present.

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

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

There are no parameters, and the schema coverage is 100%. The description does not need to add parameter information, so a baseline score of 4 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 returns the server's Ed25519 public key in SPKI DER base64 format, used for verifying signal authenticity. It distinguishes itself from sibling tools which deal with markets, orders, and accounts, making its purpose unique and specific.

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 used when one needs to verify a signal's authenticity and timestamp, but it does not explicitly state when to use it versus alternatives. However, given the uniqueness of this tool, the context is clear enough.

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, closed-world semantics, and the description adds genuinely new behavior: an auth/cost gate, the fact that signals are cryptographically signed, and an analytics-not-advice disclaimer. It does not discuss rate limits or result freshness/window, so not a 5.

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

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

One dense sentence plus a bracketed premium banner, with the access requirement front-loaded before the capability statement. Every clause carries distinct information; nothing is redundant.

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

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

Covers access, verification path, output contents, and the non-advice caveat, and an output schema already exists so return shape need not be spelled out. Remaining gap is the scoring window/horizon over which hit-rate is computed, which matters for interpreting the metrics.

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 single optional `type` parameter is fully documented in the schema at 100% coverage, including example values ('whale_net_flip', 'funding_apr'). The description adds nothing about filtering semantics, so it meets but does not exceed the baseline for high schema coverage.

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

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

Names a concrete resource and enumerates exactly what is returned: per signal type, count, scored-against-forward-price count, hit-rate, and average/median direction-adjusted return. That is far more specific than a tautology, though it never distinguishes itself from the nearby hl_score_calibration or hl_signal_pubkey tools.

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

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

Gives concrete preconditions: a premium tool that requires an API key, obtained via hl_request_free_key, or paid per call through x402. It also points at hl_signal_pubkey for verification. It stops short of saying when to pick this over hl_score_calibration, so no explicit alternatives/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 cover read-only/idempotent/non-destructive, and the description still adds real value: premium auth path (API key, hl_request_free_key, x402 pay-per-call), cohort fallback chain, and a candid disclosure that weights are judgement-based and unvalidated, pointing at the `calibration` field. That is exactly the behavioral context annotations cannot carry.

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

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

Front-loads the premium/auth gate in brackets, then the core behavior, then the caveat — a sensible order. It is dense with parentheticals and a long label list, but nearly every clause earns its place against a tool this complex.

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

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

Output schema exists so return values are covered, and the description supplies the auth model, cohort sourcing, and the calibration caveat. The remaining gap is the unexplained pagination/ranking parameters (topN/limit/offset), which is minor but real.

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 only 20% (just `cohort`), so the description must compensate — it explains cohort resolution but says nothing about topN, limit, offset, or lookbackDays. In particular the topN vs limit distinction (defaults 50 vs 25, both max 100) is left ambiguous, which is user-impacting.

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 ('Rank a cohort of wallets by a composite screening score') plus the secondary output (behavioral labels: whale, sharp, scalper, etc.). It is clearly separable from siblings like hl_trader_report (single wallet) and hl_vault_screener (vaults) without opening either schema.

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

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

Gives an explicit use case ('shortlist wallets to inspect') and an explicit anti-use ('not as a forecast'), and routes detail-seekers to hl_score_calibration and unauthenticated users to hl_request_free_key. It does not, however, say when to prefer a different screener sibling over this one.

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 annotations (readOnly/idempotent/openWorld), the description discloses key behavioral facts: the premium/pay-per-call access model with the exact onboarding tool, the 10,000-most-recent-fills cap, and the `historyTruncated` signal that flags when the window was cut short for active wallets. This is exactly the operational context annotations cannot express.

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

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

Front-loaded with the access-model tag in brackets, then the capability summary, then the truncation caveat. Dense but every sentence earns its place; the metric enumeration is long yet informative rather than filler. Minor redundancy between the bracketed premium notice and the disclaimer keeps it from a 5.

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

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

For a read-only analytics tool with an output schema, the description is complete: it covers purpose, access prerequisites, data-window limitations with a truncation indicator, and scope disclaimers. Return value structure is handled by the output schema, so no detail is missing that an agent needs 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 67%; `address` and `curvePoints` are documented in the schema, while `lookbackDays` lacks a schema description. The prose compensates by explaining that lookback is measured in days and interacts with the 10,000-fill cap, adding genuine meaning beyond the schema for the undocumented 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 and resource ('Behavioral report for any wallet from its fills') and enumerates concrete outputs: winrate, average R, realized PnL, PnL curve, holding-time style, fees, most-traded coins. This clearly distinguishes it from siblings like hl_get_account (account state) or hl_smart_money_score (abstract score) without opening a schema.

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

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

It states an explicit prerequisite ('needs an API key: call hl_request_free_key first, or pay per call via x402') and defines the analysis basis ('from fills') and scope ('Analytics only, not investment advice'). It does not explicitly contrast with sibling analytical tools such as hl_smart_money_score or hl_portfolio_risk, so no exclusions are given.

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

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

Adds real context beyond the annotations: annotations only say destructiveHint=false, while the description explains *why* — the alerts are not deleted and remain retrievable via hl_poll_alerts. It does not cover whether re-linking is possible or whether any auth/ownership scope applies, keeping it below a 5.

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

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

One sentence, front-loaded with the action, with the parenthetical carrying the non-obvious consequence. 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 zero-param mutation with an output schema and safety annotations already present, the description covers the essential agent question: what is destroyed vs. preserved. Only the reversibility path (re-link via hl_link_telegram) is left implicit.

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?

Zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies the target key is implicit in the call context rather than passed as an argument.

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 ('Stop pushing this key's alerts to Telegram') and scopes it to a single key, which cleanly separates it from hl_link_telegram and from alert-management siblings like hl_delete_alert.

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 use case is clear from the verb — call this to end Telegram delivery — and it explicitly points to hl_poll_alerts as the alternative path for still reading alerts. It stops short of naming hl_link_telegram as the reverse operation or stating any preconditions (e.g., whether a link must exist), so not quite a full when/when-not treatment.

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 the safe-read profile (readOnly, idempotent, non-destructive, open-world), yet the description adds real value beyond them: an access/cost model (API key or x402 payment), the fact that metrics are derived from vault history, and an explicit 'analytics only, not investment advice' disclaimer. It does not cover rate limits or latency, but with an output schema present the remaining gap is minor.

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 premium/auth banner is correctly front-loaded because it gates invocation, followed by purpose, inputs, and a short disclaimer. It is dense but every clause carries information; only the enumerated metric list is slightly longer than the schema warrants.

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

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

With an output schema present, return values need no explanation, and the description supplies the remaining essentials: access path, input source (explicit list vs env var), 50-vault cap context, and the basis of the metrics. An agent has enough to call it correctly on the first attempt.

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 only 33%, so the description should compensate more than it does. It explains the `vaults` input and the HL_VAULT_ADDRESSES fallback, but never mentions `minTvlUsd` or the default `sort` value, and the phrase 'screen by APR, max drawdown, Sharpe/Sortino, age, ... leader capital share' does not map cleanly onto the five sort enum values — age and leader capital share are not sortable options, which risks an agent expecting filter parameters that do not exist.

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 (screen) and resource (Hyperliquid user vaults) plus the dimensions scored: APR, drawdown, Sharpe/Sortino, age, TVL, leader capital share. This clearly separates it from siblings like hl_funding_screener and hl_hip3_analytics without the agent needing to open any schema.

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

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

The description gives one concrete operational prerequisite — obtain a key via hl_request_free_key or pay per call via x402 — which is genuinely useful before invoking. However, it never says when to pick this over the other screener/analytics siblings (hl_funding_screener, hl_portfolio_risk, hl_hip3_analytics), so selection guidance between alternatives is left implicit.

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 annotations (readOnly/idempotent/non-destructive), it discloses non-obvious behavior: it is premium-gated with two auth paths, and critically it 'seeds a baseline on first call', meaning the first invocation will not return alerts. That is exactly the kind of trait an agent would otherwise misinterpret as an empty result.

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

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

Dense but efficient: the premium/key requirement is front-loaded, then the core definition and the distinctive 'full exits' / 'baseline seeding' details. The trailing 'analytics only, not investment advice' is boilerplate but short.

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

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

With an output schema present, return-shape explanation is unnecessary, and the description covers the auth path, the baseline-seeding gotcha, and the core semantics. Minor gaps remain around topN and the dex scoping caveat that the schema documents but the description doesn't reinforce.

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 80%, so most parameters are already documented in the schema. The description adds conceptual meaning to the cohort/threshold combination ('net long/short notional shift beyond a USD threshold') but says nothing about topN or the dex='all' wallet-limit caveat, so it only marginally exceeds the schema.

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

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

The description names a concrete resource and behavior: recent net long/short notional shifts in whale cohorts beyond a USD threshold within a lookback window, with full-exit detection. This clearly separates it from a static holdings tool like hl_whale_positions (flow/change vs. position snapshot), though it does not name that sibling explicitly.

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

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

It gives a concrete prerequisite and routing instruction — call hl_request_free_key first or pay per call via x402 — and frames the use case as 'who opened/closed what in the last hour'. It stops short of explicit when-not conditions or naming the alternative tool for position snapshots.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description's added value is the paywall behavior: a key is required, and there are two acquisition routes including a free one. That is exactly the kind of gating context an agent cannot infer from structured fields. It stops short of noting rate limits or what the pay-per-call path costs.

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 gating requirement is front-loaded in a bracketed banner, then purpose, then cohort resolution, then the advisory disclaimer. Dense but every sentence carries information. The 'not investment advice' clause is arguably boilerplate, but it is short.

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

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

An output schema exists, so the metric list is redundant but harmless and return values need no further explanation. Auth path, cohort sourcing, and scope (single coin vs all coins) are all covered, leaving little an agent would need to guess.

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 would be 3. The description earns above baseline by disclosing the cohort fallback to the HL_WHALE_ADDRESSES environment variable, a default source the schema never mentions. dex, coin and topN are left entirely to the schema.

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

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

States a specific verb and resource — aggregated positioning of a whale cohort for a coin or all coins — and enumerates the exact metrics returned (long/short size & notional, wallet counts, weighted-average entry, net bias, 1h/24h change). An agent can tell this is a cohort-aggregate view rather than a per-wallet view, though no sibling (e.g. hl_smart_money_score, hl_trader_report) is named to sharpen the boundary.

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

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

Gives real prerequisites — a premium key, with hl_request_free_key or x402 pay-per-call as the paths — and explains how the cohort is resolved (cohort arg or HL_WHALE_ADDRESSES). It never says when to reach for this instead of hl_smart_money_score or hl_trader_report, so the usage guidance is 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.