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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely new behavioral context: history depth is gated by plan (24 h free, 31 days Pro, full history since 2026-09-27 on Bot) and the key is sourced from the X-API-Key header or the api_key parameter. It does not cover error behavior for an unknown address or whether snapshots are truncated, which keeps it short of 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?

Three sentences, front-loaded with purpose, then the returned fields, then access tiers and auth. The parenthetical field list is dense but each item earns its place by telling the agent what analysis is possible. Minor cost: the long bracketed enumeration slightly delays the access-tier information an agent needs before calling.

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

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

With no output schema, the description carries the burden of describing returns and does so explicitly (positions fields, account value, archived snapshots), plus it covers auth sourcing and plan-based history limits. Remaining gap is edge behavior — invalid or unknown address, and how many archived snapshots come back — but nothing essential for a correct 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?

Schema description coverage is 100%, and both parameters already document their format (0x address, lv_ key) and the header-vs-parameter alternative. The description reinforces that the address identifies a single Hyperliquid account but adds no syntax, validation, or defaulting detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource: fetch one Hyperliquid account by address, and enumerates exactly what comes back (live positions with size, entry, mark, liquidation distance, leverage, unrealized PnL; account value; archived snapshots). That is far more specific than a sibling like get_hl_whales or get_top_traders, but it never explicitly says how it differs from those aggregate-account tools, leaving the agent to infer that this is the single-address lookup.

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 only implied: 'One Hyperliquid account by address' signals a per-address query, and the history-depth tiers tell the agent what data is reachable at each plan level. There is no explicit when-to-use/when-not-to-use statement and no named alternative for related needs (e.g. whale lists or liquidation maps), so routing still requires inference.

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