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

Annotations only declare readOnlyHint=false, so the description carries most of the burden and does it well: it discloses destructive semantics of 'replace' (open lines absent from rows are deleted), that history is untouched, the 2000-row cap, and the OWNER role / OAuth requirement. It does not cover failure modes or how partial validation errors are returned, which keeps it short of a 5.

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 with the deprecation notice, then the ladder position, then the operational rules — the ordering is sensible. It is dense and repeats some merge/replace semantics already in the schema, so it is longer than strictly necessary, but no sentence is purely filler.

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?

No output schema exists, yet the description explains what the preview returns (warnings, per-region diff, confirmationToken) and what the commit consumes. Combined with the permissions note and row cap, an agent has what it needs to sequence the call correctly.

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 83%, so the schema already documents mode, status, reference and expectedAt, and the description largely restates them. It still adds meaning the schema does not: the 'fifth rung of the ladder' framing, which downstream fields the open lines feed, and the guarantee that re-sending unreferenced lines never doubles them.

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, then pins down the exact scope: the seller's own purchase orders on its supplier, per product × stock region, explicitly not Amazon Vendor POs. It also names its successor (import_supply_chain) and the query tool that surfaces the result (query_inventory as onOrderUnits / nextExpectedAt), so an agent can place it among siblings immediately.

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?

Explicitly says this tool is deprecated in favor of import_supply_chain and for whom it remains. It spells out the mandatory two-step flow (preview, show user, commit with confirmationToken) and which mode to use, including the re-send-with-status-'received' case, leaving little to inference.

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