Approve an order's draft

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond them by naming the downstream consequence — the seller publishes the order — which explains why the call is destructive. It does not mention permission requirements or what happens on an invalid or rejected draft state.

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?

One sentence with no filler, leading with the usage trigger and following with the effect. The phrasing 'a post order that waits for their review' is slightly awkward but not wasteful. Nothing is repeated from structured fields.

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 two-parameter destructive mutation with no output schema, the description covers the when and the consequence, which is the core need. It stops short of clarifying the id parameter's referent and does not indicate what the caller gets back or what error conditions (e.g., draft not in review state) to expect.

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 only 50%: requestId is thoroughly documented in-schema, but id carries no description and the tool description never says what it identifies (order id? draft id?). With half the parameters undocumented and no compensating text, an agent must guess the meaning of the required id argument.

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: approving the draft of a post order, with the resulting effect that the seller publishes it. An agent can grasp the operation without opening the schema. However, it does not differentiate from the near-identical sibling growwer_approve_order (non-draft approval), so the agent must infer which of the two applies.

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 precondition-based: use it when the user has read the draft awaiting their review and accepts it. That is clear positive guidance. No exclusions or alternatives are offered, so nothing tells the agent when to prefer growwer_approve_order, growwer_request_order_draft_update, or growwer_refute_seller_order_draft_update instead.

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