Deliver a draft update

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this write is irreversible and safe to retry. The description adds the dependency on growwer_upload_file, but the material consequence — that the file is consumed on delivery and cannot be reused — lives only in the fileId schema field, not the description. Nothing 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?

A single sentence, front-loaded with the usage condition and ending with the resource dependency. No filler. It could only be improved by spending a few more words on the sibling disambiguation, which would still fit comfortably.

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 three-parameter destructive write with no output schema, the definition covers the trigger and the file source but not the outcome: what happens to the order state after delivery, what the caller gets back, or how failures surface. Annotations carry the idempotency and destructiveness signals, which keeps this at minimum viable rather than inadequate.

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?

Coverage is 67%: fileId and requestId carry strong schema descriptions (allowed formats, 8 MB limit, single-use file; idempotency key semantics), so the description needn't repeat them. The `id` parameter is undocumented in both places, and the description only obliquely implies it identifies the seller order/draft being updated.

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: it delivers the new draft of a post order produced from an uploaded file, scoped to the case where the seller revised the draft at the buyer's request. This separates it from the plain delivery tool in spirit, though it never names its near-identical siblings (growwer_deliver_seller_order_draft, growwer_deliver_seller_order_update), so an agent must infer the boundary from the tool name alone.

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 trigger is explicit and conditional: use it when the seller has changed the draft as the buyer asked. That is real routing guidance, not a restatement of the name. It stops short of exclusions — it never says to use growwer_refute_seller_order_draft_update when the update is unacceptable, or growwer_deliver_seller_order_draft for a first delivery.

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