cancel_perp_order

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

Goes well beyond the annotations (destructive=true, idempotent=false, openWorld=true) by disclosing that `accepted` is only an application acknowledgement and that every ID must be reconciled via /futures/reconcile-order before dependent actions. It also explains partial-rejection semantics for mixed errors, unknown outcomes on malformed/timeout responses, and fail-closed replay control on nonce authority — genuinely decision-relevant behavior for a destructive call.

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 text opens with bracketed capability/tier/API metadata and an authority URL rather than the tool's purpose, and the core action sentence only appears third. Multiple dense clauses (nonce authority, replay control, error taxonomy) are packed into a single undifferentiated block with no structure, making it hard to scan.

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 destructive, non-idempotent 13-parameter tool with no output schema, the description covers auth modes, reconciliation requirements, and failure semantics well. It stops short of explaining several required inputs (coin, orderIds, nonce) and does not describe the shape of a successful response, leaving real gaps.

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?

With 0% schema description coverage and 13 parameters, the description must compensate, and it does explain the highest-risk ones: expiresAt (venue-signed expiresAfter), intentHash, accountAddress (vault/subaccount routing for delegated API wallets), signature (local venue signature required), and executionMode via the two named modes. It leaves coin, orderIds, nonce, grantId, sessionId, sessionToken, and signedAction unexplained, so coverage is partial rather than complete.

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 contains a specific verb+resource: "Cancel stale or resting Hyperliquid orders with a venue-signed expiresAfter and FarmDash intent hash." That distinguishes it from siblings like prepare_perp_order and execute_perp_order by implication, but it is buried mid-paragraph behind tier/API metadata rather than front-loaded, and no sibling is named explicitly.

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 by "cancel stale or resting orders," and the description does enumerate preconditions per execution mode (USER_SIGNED needs fresh human approval; BOUNDED_AUTONOMOUS needs futures.cancel scope, owner-signed policy, authenticated session). However it never states when *not* to use it or names an alternative path, so the agent must infer routing.

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