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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses what actually gets destroyed (terminal hosted cancellation of named predecessors, post-only successors) and the partial-failure contract (a failed market never voids its neighbours). It stops short of describing the signing/proof flow or what 'one write credit' means for retries.

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, front-loaded with the scope and atomicity guarantee; every clause carries operational meaning and nothing is repeated from the schema or annotations.

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 batch write with an output schema, the description covers scope, atomicity, failure isolation, and the size limit. The remaining gap is the authorization path — walletAddress/walletSignature/proofNonce/signatureTimestamp are required but the description gives no hint about obtaining the nonce or signing sequence, which would matter before a first invocation.

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 only 50% schema description coverage, the description contributes one genuinely new constraint — the aggregate 50-order cap across all items, which is not expressible in the schema's per-item maxItems of 50. It does not explain idempotencyKey semantics (which the schema leaves undocumented) or the suspendOrderHashes field that supplies the 'named predecessors'.

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 states a specific verb and resource ('Replace hosted quote sets'), the batch scope ('across up to 10 markets in one request'), and the cost model ('one write credit'), which cleanly separates it from the single-market sibling problee_replace_quote_set.

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 batch scope implies when to reach for this tool (multiple markets in one call), but there is no explicit when-to-use/when-not guidance and no named alternative such as problee_replace_quote_set for a single market or problee_batch_place_orders for additive placement.

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