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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses access-tier behavior: live book is public and keyless, while computed history and the full fill trail require a developer plan. It also clarifies that 'Descriptive market data only' indicates non-actionable data. Additionally, the parameter description (in the schema, integrated here) explains keyless calls receive only 3 fills regardless of request, which is a concrete behavioral trait. There is no contradiction with annotations.

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

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

The description is two sentences, front-loaded with the core function and data fields, followed by access-tier and data-type context. Every clause contributes meaningful information ('Descriptive market data only' adds a clarity caveat). It is efficient without being terse.

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

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

The tool has an output schema, so return formats are documented separately. The description covers the main payload components (positions, equity, PnL, fills), the access-tier distinction (keyless vs. developer plan), and the data's descriptive nature. It also leverages the parameter descriptions to clarify edge cases. This is complete for the tool's complexity.

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

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

The input schema description coverage is 100%, and both parameters have detailed descriptions in the schema itself (e.g., address format, limit defaults/ceiling, keyless behavior, tracked:false semantics). The tool's description text does not add significant parameter-level information beyond what the schema already provides, so a baseline of 3 is appropriate when schema carries the load.

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

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

The description opens with 'One Hyperliquid account' and enumerates the exact data provided: live positions, equity, leverage, net bias, unrealized PnL, and recent whale-sized fills. This clearly identifies the resource and scope, distinguishing it from sibling tools like hl_whales that likely cover multiple accounts. The purpose is specific and immediately understandable.

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

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

The description gives clear context on access tiers ('The live book is public on Hyperliquid so it stays keyless; computed history ... and the full fill trail need a developer plan'), which helps users know what to expect. However, it does not explicitly name alternative tools or state when not to use this tool. The 'One Hyperliquid account' phrasing implies use for single-account queries, but an explicit alternative (e.g., hl_whales for many wallets) is missing.

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