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

With no annotations, the description carries the full burden. It usefully discloses that this is public on-chain data readable for any address (implying no auth and read-only), and it previews the returned fields including 'raw open positions'. But it does not state read-only status explicitly, nor address rate limits, caching, or error behavior for invalid addresses.

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 front-loaded sentences: the first names the resource and enumerates outputs, the second covers input scope. No filler, though the field enumeration is long and the second sentence spends words on decorative examples ('a counterparty's, or a whale's').

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

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

No output schema exists and no annotations, so the description's field enumeration is genuinely valuable in lieu of a return schema. However, ambiguity among the three undocumented input parameters is unresolved, which is a real gap for correct invocation.

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

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

Three parameters exist (user, wallet, address) with 0% schema description coverage, so the description must compensate. It only addresses the 'address' concept ('pass any 0x address') and never explains whether user/wallet/address are aliases or which to use, leaving two of three params semantically unexplained in both schema and description.

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 ('Hyperliquid perpetual account state for any address') and enumerates exactly what it returns (account value, notional, margin used, maintenance margin, withdrawable balance, raw open positions). This clearly distinguishes it from the market-data siblings like x402-hyperliquid-book/candles/mids, which return order book and price data rather than per-account state.

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: 'pass any 0x address you want to inspect, including your own, a counterparty's, or a whale's' tells the agent the accepted input and the read-only inspection intent. However, it names no alternatives (e.g., x402-wallet-balance, x402-hyperliquid-perps) and gives no explicit when-to-use/when-not guidance, leaving the agent to infer selection.

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