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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses the crucial non-obvious traits: it persists an expiring plan that does not change stock, plans expire after nine minutes, separate store:inventory:write consent plus EDIT_LISTINGS permission are required, and execution accepts only a plan ID, idempotency key and native approval reference. It also enumerates failure modes (foreign or stale listings, changed reservations, revoked consent, mismatched plans, reused keys) and the uncertain-response recovery rule. Nothing here contradicts the annotations.

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 content is dense and mostly front-loaded with the action, but it arrives as an unstructured block of run-on sentences. There is visible redundancy, notably the back-to-back 'Requires OAuth store:inventory:write consent. Requires separate store:inventory:write consent and current EDIT_LISTINGS permission', which repeats the same scope and forces re-parsing.

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 mutation-adjacent prepare tool with an output schema, the description supplies everything an agent needs: the prepare-then-approve-then-execute flow, consent requirements, plan expiry, return shapes (inventory.adjust plan, durable operation receipt, bounded history page), privacy guarantees, and a recovery path for uncertain responses. Return-value detail is appropriately delegated to the output schema.

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 schema already documents listing_id, expected_version, quantity/delta and reason in detail; the baseline would be 3. The description adds meaning beyond the schema by constraining scope ('One exact listing per plan'), clarifying that listing IDs must come from SuperCatch's native surface, and explaining what execution will subsequently accept. It does not explain the absolute_count vs delta mode choice, which keeps it from a 5.

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 chain and resource: freeze one exact owned listing's version, quantity adjustment and reason, then inspect a reservation-aware plan and approve before execution. This clearly separates it from supercatch_execute_inventory_adjustment, which it references as the later step. It loses a point only because the two-phase prepare/execute relationship and the distinction from supercatch_get_inventory_plan are implied rather than named.

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 gives concrete usage context: 'Use the exact owned listing ID and version from SuperCatch's native listing surface' and 'Inventory changes require a separately approved native plan,' which tells the agent this is the prerequisite to execution. It does not explicitly name a sibling alternative or state when not to use this path (e.g., non-inventory changes), so it stops short of full routing guidance.

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