complete_draft_order

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

With no annotations, description fully discloses behavior: immediate payment capture attempt with potential failure, creation of payment-pending order, one-way transition, and returned GID.

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?

Four sentences, each essential. Main action in first sentence, followed by two payment scenarios and a final constraint. No redundancy.

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?

Complete for a conversion tool: covers payment modes, state transition, result, and limitations. No output schema but return value is described.

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 covers 100% of parameters; description adds context about default behavior and failure case for paymentPending, and rejection of non-OPEN drafts, enriching understanding.

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?

Clearly states 'Convert an OPEN draft order into a real Shopify order' with specific verb and resource. Distinguishes from creation tools (create_order) and deletion tools (delete_draft_order).

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 describes when to use (for converting drafts), differentiates between paymentPending=true/false scenarios, and notes that completed drafts cannot be reopened, guiding appropriate usage.

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