Custom order (Claude order)

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

The description adds a lot beyond the annotations: the order lands in the admin panel as a pending 'Claude order' with photos attached, custom prices are confirmed by the team before dispatch, there is an Rs 150 MCP fee, and the first call returns a non-committal quote. However, nothing explains what happens if the order fails after confirmation, whether retrying is safe given the non-idempotent annotations, or the delivery charge rules beyond the latitude note. It adds real context but leaves the failure/retry surface opaque.

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?

It is front-loaded with the core verb and resource, and each sentence carries a distinct obligation (store rule, outcome, auth modes, confirm flow, payment). The paragraphs are dense run-ons, and some parenthetical detail could be tightened, but almost nothing is filler.

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 16-parameter mutation tool with no output schema, the description covers the critical gaps: what the first call returns (quote with items, delivery charge, fee, total, warnings), how auth modes work, how custom vs catalogue items are built, and that the order is pending admin confirmation rather than finalised. An agent has enough to call it correctly without guessing.

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 81%, so the schema already carries most parameter meaning; the description usefully adds the mode split (session_key for customers vs staff_session + customer_name/phone for staff) and the item construction rule (item_id for catalogue, name + estimated_price_rs for custom). It does not explain the interaction between address and address_id, or what images/confirm do beyond what the schema already states, so it is a moderate increment rather than a full semantic layer.

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 a specific verb and resource ('Create a Foran order') plus the input shapes it accepts (product names, shopping list, photos). It explicitly distinguishes itself from the catalogue-only path by explaining that custom items (name + estimated_price_rs) can be mixed with catalogue items (item_id), which is what separates it from foran_place_order and foran_cart_add.

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?

It names the alternative tools to call while preparing the order (foran_list_stores / foran_search_products) and states the selection rule: one store, nearest open, most items. It also gives the mandatory two-step flow (first call without confirm for a quote, then repeat with confirm=true after an explicit yes) and states the payment method (cash on delivery).

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