shopify_create_draft_order

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

Annotations already communicate read/write, idempotent, open-world, and destructive hints, and the description adds meaningful behavioral context beyond them: it returns a customer-payable invoice_url, requires one presentment currency for priced lines, and explains Spring's effect verification. No description statement directly 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?

The core action and return value are front-loaded, and the parameter block is compact and scannable. The length is justified because the schema supplies no descriptions, though a single additional sentence naming sibling alternatives would improve it further.

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 an 11-parameter mutation tool with an empty schema, the description covers every parameter, marks line_items as required, explains currency and customer constraints, and identifies the main return value. Since an output schema exists, not detailing the full return envelope is acceptable; only the lack of explicit sibling routing and side-effect clarification keeps this from a 5.

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?

With 0% schema description coverage, the description carries the full parameter-semantics burden and mostly succeeds: it defines the line_items JSON shape, required fields, currency fallback, customer_id-vs-email relationship, and all platform-level refs. One deduction is that line_items is described as a list of objects while the schema types it as an array of strings, creating a mild ambiguity.

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 first sentence states the exact action and resource ('Create a Shopify draft order') and the key return value ('invoice_url — an instant payment link'). The use-case sentence ('services, custom quotes, or any sellable without a fixed product variant') clearly distinguishes this from read-only Shopify tools and from invoice-sending tools.

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 description explicitly says when to use the tool: for services, custom quotes, or sellables without a fixed product variant. It also gives practical line-item construction rules, but it does not explicitly name or exclude sibling alternatives such as shopify_send_draft_order_invoice, so it stops short of full when-not-to-use routing.

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