cancel_all_orders

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

Annotations already flag destructiveHint and idempotentHint, but the description adds substantial behavioral context: the need for user confirmation, verified symbol filtering behavior, the Darwin REVALL/TRADOK 3002 ack quirk, and the practical advice to read the resulting order list rather than trust the ack. This goes well beyond the annotations and is genuinely useful.

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 description is front-loaded with the core purpose, then adds a critical safety note, a pointer to the existing order gate, and a concise but valuable implementation detail about the ack behavior. Every sentence earns its place and there is no fluff.

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?

Given one simple parameter, rich annotations, and an output schema, the description covers the essential context: what it does, when user confirmation is required, how it behaves relative to sibling tools, and how to correctly interpret the response. It is complete enough for an agent to select and invoke the tool correctly.

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 description coverage is 0%, but the description compensates by explaining that the symbol acts as a filter for all open orders and includes verification evidence that only the named symbol is affected. It also warns about the ack response not identifying the symbol, which adds meaning beyond the bare schema property. Since there is only one simple string parameter, this is sufficient.

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 clearly states the operation: 'Cancel every open order for a symbol.' It uses a specific verb (cancel), identifies the resource (open orders), and scopes it by symbol, which distinguishes it from the sibling cancel_order that targets a single order.

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 provides explicit usage guidance: confirm the symbol with the user first because the action may affect orders the user didn't ask about, and it references the same order gate as place_limit_order. It does not explicitly contrast with cancel_order, but the 'every open order' scope makes the intended use clear.

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