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

Goes well beyond the annotations: it explains that cancellation is terminal and occurs at the hosted layer rather than on-chain (no broadcast, no gas), and it discloses the important edge case that orders with committed taker reservations are suspended rather than immediately killed, terminalizing when the fill settles or releases. It also flags paging and the wallet-proof requirement. What it omits is idempotency behavior (annotations say idempotentHint=false while the schema requires an idempotencyKey) and what a partial failure looks like mid-page.

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 dense sentences with the destructive terminal semantics front-loaded and the caveat about reserved orders following immediately. Nearly every clause earns its place, though 'on the page' and the em-dash aside are slightly awkward and could be tightened without losing information.

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 annotations already declare destructiveHint and openWorldHint and an output schema exists, the description covers the essentials: terminality, no gas, reservation suspension, market scoping, paging, and proof requirement. Remaining gaps are the afterOrderHash cursor meaning and how idempotencyKey interacts with a non-idempotent bulk cancel, which the agent would need to call correctly on retries.

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 78%, so the baseline is 3, and the description adds only modest value: it confirms market scoping is optional and that a wallet proof is mandatory. It says nothing about 'paged', leaving the agent to connect that to limit/afterOrderHash, and afterOrderHash has no schema description at all. The required auth bundle (signatureTimestamp, proofNonce) is only gestured at.

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?

States a specific verb and resource with scope: cancel every open order at the hosted layer, optionally market-filtered. The phrase 'at the hosted layer — terminal, nothing to broadcast, no gas owed' distinguishes it from on-chain cancellation, but it never names its nearest siblings (kellian_cancel_order, kellian_cancel_orders, kellian_confirm_order_cancel), so the agent must infer the difference from scope wording alone. The stray phrase 'on the page' is ambiguous and slightly muddies the statement.

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?

There is implicit usage (bulk cancel of everything open, or narrowed by market), but no explicit when-to-use versus the three sibling cancel tools, and no stated exclusions or sequencing (e.g., whether kellian_confirm_order_cancel is needed afterward). 'Requires wallet proof' is the only precondition given. For a name that overlaps heavily with kellian_cancel_orders, the absence of disambiguation is a real routing risk.

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