Create Draft Order

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

No annotations are provided, so the description must disclose behavioral traits. It states that the tool validates without creating a payable checkout, but it does not clarify whether a draft order is persisted, if the operation is idempotent, or what side effects (e.g., state changes) occur. The name suggests creation, but the description avoids confirming persistence.

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 description is a single sentence, front-loading the core action. It is concise but under-specified given the tool's complexity (9 parameters, nested objects). The brevity leaves gaps, but it avoids unnecessary words.

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?

With 9 parameters, nested objects, no output schema, and no annotations, the description is too brief. It fails to explain what a draft order is, how validation works, what the response contains, or how to integrate with other Ninja tools (e.g., using it before ninja_create_checkout). The tool's complexity demands richer context.

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 0%, yet the description adds no parameter explanations beyond the schema's own descriptions. It does not elaborate on required fields like addressId or lineItems, nor does it clarify complex parameters like pharmacy, restaurant, or toppings. The schema provides some inline descriptions (e.g., for itemId), but the description fails to add semantic value.

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 description clearly states the tool's purpose: 'Validate a cart and pricing without creating a payable checkout.' The verb 'validate' and the resource 'cart and pricing' are specific, and the exclusion of 'payable checkout' distinguishes it from related tools like ninja_create_checkout.

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 mentions supported verticals (retail, pharmacy, beauty, restaurant) and line item types, providing context for when to use the tool. However, it does not explicitly state when not to use it or mention alternative tools like ninja_create_checkout, so it lacks explicit exclusion guidance.

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