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

Annotations only declare a safe, idempotent read; the description adds substantial context beyond that: data provenance (exchanges' public tables, 'estimated' where unpublished), explicit modeling assumptions (isolated margin, fees ignored so the real level is slightly nearer entry), the modeled-vs-measured distinction for leverage, the caveat that the frequency is historical not a forecast, and the full payment model (x402 $0.02, prepaid credits, key quota). This is exactly the kind of disclosure 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?

The core capability is front-loaded, which is good, but the body is one long comma-spliced enumeration that mixes outputs, assumptions, and billing in a single breath. Every element is relevant, yet the dense packaging makes it harder to parse than a short bulleted breakdown would be.

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 six-parameter analytical tool with no output schema, the description covers the returned quantities in detail, states assumptions, and explains the billing gate. Remaining gaps are minor: no error/edge behavior (e.g. venue lacking a published tier beyond 'estimated') and no note on response shape or units for the funding figure.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns more by explaining that notional_usd selects the maintenance-margin tier used for liquidation pricing and that the venue parameter governs cost (one venue free, all twelve priced). It does not add format detail for side/entry/leverage, which the schema already covers adequately.

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

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

The description names a specific computation on a specific resource: per-venue liquidation price from that venue's maintenance-margin tier at the given notional, distance to mark, modeled vs measured leverage between mark and liquidation, funding cost per day, and historical frequency of adverse moves. It is clearly a personal-position tool, distinct from the market-wide liquidation-map siblings, and an agent can tell what it 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?

Usage is implied rather than stated — the framing 'your own position' signals the case, and the pricing split (one venue free, 12-venue comparison paid) tells the agent there is a cost decision to make. However, it never explicitly says when to prefer this over get_hl_liquidation_map or get_liquidation_heatmap, nor any prerequisite beyond isolated margin.

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