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

Goes well beyond the annotations: OAuth scope store:orders:shipment:write, MANAGE_ORDERS permission, an approved owned store, and the warning that 'Tracking-correction and read grants do not authorize a first shipment.' It discloses the atomic side effects (records shipment, consumes approval, saves the original-key receipt, continues only frozen notifications), the fail-closed conditions (foreign, stale, already shipped, unapproved, expired plans, revoked grants), and recovery semantics after an indeterminate outcome. This is exactly the mutation-risk context the destructiveHint/idempotentHint annotations cannot convey.

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?

Front-loaded purpose is good, but the middle is a run of verbless fragments ('Tracking corrections, marketplace orders, label purchases, payment, refund...') that reads as an unparsed exclusion list. Requirements are duplicated verbatim in adjacent sentences ('Requires OAuth store:orders:shipment:write consent. Requires separate store:orders:shipment:write consent, current MANAGE_ORDERS permission...'), wasting space for every agent that reads it.

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 mutation with an output schema present, the definition covers prerequisites, atomicity, failure modes, notification side effects and recovery. Only the explicit naming of prepare_order_shipment as the required precursor is missing from the prose, which slightly weakens the otherwise complete picture.

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 100%, so the baseline is 3. The description reinforces idempotency behavior ('Recover the same plan and original key after uncertainty', 'Unknown email outcomes cannot be resent') but largely restates what the idempotency_key and plan_id schema descriptions already say, adding little new parameter-level meaning.

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 opening states a specific verb and resource with scope: 'Record one exact first shipment approved in SuperCatch and recover its original receipt' and 'Ship one owned pending, paid or processing website order with native verified tracking.' It also implicitly separates itself from supercatch_execute_order_tracking by listing 'Tracking corrections' as out of scope. However, it never names the sibling tools it routes away from (prepare_order_shipment, execute_order_tracking) in the description body, leaving the agent to infer them from the fragments.

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?

Usage conditions are explicit: the plan must be approved and the order owned, pending/paid/processing, and website-native, while 'marketplace orders, label purchases, payment, refund, stock changes, arbitrary messages, bulk targets or active order.updated webhook destinations' are excluded. 'Conversational approval does not replace exact native review' tells the agent when not to proceed. The gap is that no sibling tool name is offered as the correct fallback for the excluded cases.

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