preview_pair_order

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

With no annotations supplied, the description carries the safety burden itself and does so: "Nothing is ever sent from this server" establishes the read-only, non-mutating nature. It also discloses a non-obvious behavioral trait — pricing is on Hyperliquid testnet by default, so prices can diverge from mainnet — which an agent would otherwise misreport as a live quote.

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 what the tool is, then what it returns, then the two caveats. No filler or repetition; the density is appropriate for a preview operation.

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?

There is no output schema and no annotations, so the description must cover the return shape and safety alone — it handles safety well and sketches the return values in one clause, but leaves the response structure, the derivation of the stock quantity, and the direction semantics unaddressed. Adequate but with clear gaps for a three-required-parameter 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%: asset and notionalKrw are documented in-schema, while direction has only self-describing enum values. The description adds essentially nothing about parameters beyond echoing "stock quantity" and the order payload, and does not clarify which leg is perp versus stock per direction value. Baseline 3 fits given partial schema documentation.

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?

"Preview (dry-run) of an arbitrage pair order" gives a specific verb and resource, and the follow-on clause states what the caller gets back: stock quantity plus the Hyperliquid order that would be sent. It does not name a sibling tool to contrast with in the main body (only the notionalKrw schema note references get_arbitrage), so it falls short of full 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 dry-run framing implies "call before committing," which is useful implied context, but the description never states an explicit when-to-use rule or an exclusion. The only routing hint is buried in the schema: get_arbitrage with the same notionalKrw shows fill prices, slippage and net, so the split of responsibilities between the two tools is left for the agent to infer.

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