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

Annotations already declare destructive/idempotent/openWorld, but the description adds substantial context beyond them: plans expire in nine minutes and hold up to 125 listing IDs, each call processes at most five remaining targets, rechecks authority and price policy per unfinished target, and discloses lease timing (released leases resume immediately, abandoned leases wait two minutes). It also discloses what is never returned (stored approval tokens, worker lease IDs) and that a local receipt is not provider acceptance.

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?

Content is front-loaded and every topic is on-point, but it is an undifferentiated run of short declarative sentences with visible redundancy: idempotency is restated three times and the local-vs-marketplace distinction appears twice ('Local completion does not establish marketplace prices' and 'a local receipt is not provider acceptance'). Grouping into prerequisite, idempotency, lease/expiry, and failure sections would improve scanability without losing content.

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, open-world, idempotent write tool with an output schema, this covers the essentials an agent needs: authorization, approval gating, expiry, batch limits, retry and recovery paths, and failure modes for revoked or expired grants. Minor gaps remain around concurrency between callers on the same plan and what partial progress looks like mid-batch, but nothing critical is missing.

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%, so the baseline is 3, but the description adds meaning the schema does not carry: idempotency-key reuse for a different plan conflicts, keys should be reused until terminal state, and approval refs are verified rather than conversational. The plan_id behaviour of processing a bounded number of targets per call also extends beyond the schema's 'targets cannot be replaced' note.

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: 'Execute only the persisted exact plan approved in SuperCatch', scoped to an 'exact, frozen seller price workflow'. It also draws an explicit boundary against adjacent capabilities ('No inventory, order, automation settings or listing publication changes'), which separates it from siblings like supercatch_execute_inventory_adjustment, supercatch_execute_publication, and supercatch_apply_card_price_updates.

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?

Gives concrete when-to-use conditions (an already-approved frozen plan under this connection's price-write consent), when-not (unapproved plans require web review first), and prerequisites (store:prices:write consent plus current EDIT_LISTINGS on an approved owned store). It also routes the agent to specific alternatives in the failure case: 'a lost response is recovered through supercatch_list_operations or supercatch_get_operation before any new action', and warns that status reads do not resume work.

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