Cancel one order

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

Annotations already declare the destructive, non-idempotent, open-world nature, so the bar is lower — yet the description still adds substantive context: the auth scope required, the shared rate limit across the trade-write group, and a candid warning that the limit is not a figure to design around. That goes well beyond what the annotations 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?

The purpose and identifier semantics are front-loaded and the rate-limit caveat is placed last where it belongs. The prose is slightly editorial ('a figure to design around', the em-dash aside), which costs a bit of tightness but does not obscure the core instruction.

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 one-parameter, no-output-schema tool, the description covers scope, identifier semantics, and rate limits adequately. It omits the return value / failure behavior for a destructive operation (e.g. order already filled), which is the one remaining gap an agent might need.

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% for the single parameter, so the baseline is 3, but the description genuinely enriches the id's meaning: it is the identifier carried since filing and before the venue has responded, which clarifies the distinction from a venue-assigned order id. It adds real semantics rather than restating the schema.

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 gives a specific verb and resource ('Withdraws one resting order') and pins down the addressing scheme via clientOrderId. The singular scope implicitly separates it from the sibling cancel_orders, but that sibling is never named, so the differentiation relies on the agent noticing the plural/singular contrast.

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?

It states a precondition ('Requires the trade:write scope') and details rate-limit constraints, which is useful context for deciding whether to call it. However, it never states when to prefer this over cancel_orders or what happens if the order is already filled/cancelled, leaving the operational guidance implied rather than explicit.

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