execute_perp_order

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

Annotations already flag destructive/non-idempotent/openWorld, and the description adds substantial detail beyond them: market_ioc is a price-protected IOC limit with a 100 bps adverse cap and is 'never an unbounded market order', fill outcomes distinguish full/partial/zero, a resting IOC response is treated as unknown/inconsistent, agentAddress mismatches are rejected, maxBuilderFee is preflighted, and replay control fails closed before submission. This is exactly the kind of safety-critical context annotations cannot convey.

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?

Dense run-on sentences with no separation of purpose, authorization, signing, and fee rules; the most agent-relevant fact (it submits a signed perp order) is buried mid-paragraph. Substantial text is spent on internal capability/tier bookkeeping that does not help an agent decide or invoke.

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 19-param financial execution tool with no output schema, the description does cover auth paths, builder fee, fill semantics, and replay protection, which is above average. It still omits what a successful call returns (order id? receipt handle for get_receipt?) and how the required intentHash/grantId/sessionId are obtained, which an agent needs before calling.

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 19 parameters at 5% schema description coverage, the description must carry the load and only partly does: it explains executionMode, accountAddress (venue-verified equity owner for delegated wallets), signedAction (builder term f=1), expiresAt (venue-signed as expiresAfter), nonce scoping, and agentAddress validation. Coin, size, price, signature, intentHash, grantId, sessionId, sessionToken, reduceOnly, leverage, and executionTrialId remain undocumented in both places.

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 actual operation — 'submit a pre-signed EIP-712 Hyperliquid order' — is stated, but only in the third sentence, behind a '[Capability: available_with_tier_gate; tier: ...]' preamble that reads like internal metadata rather than purpose. It never names the sibling it must follow (prepare_perp_order) or contrasts with cancel_perp_order, so the agent must infer the workflow position.

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 two executionMode values are given real conditions: USER_SIGNED 'requires fresh human approval', BOUNDED_AUTONOMOUS needs an owner-signed futures policy, authenticated session, and per-action wallet signature, with rollout 'preparation_only'. That is genuine mode selection guidance, but there is no routing to sibling tools (policy_check_intent, request_human_approval, prepare_perp_order, simulate_intent) that obviously precede this destructive call.

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