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

The description states 'a retry returns the first order', i.e., repeated calls with the same arguments have no additional effect, while the annotation declares idempotentHint=false. That is a direct conflict on the idempotency dimension, and the same replay claim is repeated in the schema description, so the structured hints and the prose point an agent in opposite directions about retry safety.

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?

Three short sentences, zero filler, with the action and the required preconditions front-loaded before the retry and timing notes. Every clause carries information an agent needs.

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 paid mutation with no output schema, the description covers the essentials an agent needs before calling: required confirmation, idempotency key, optional companion tools, and where timing comes from. It is slightly thin on the two undocumented parameters (resolution_id, layout_objective) for a 5-parameter tool.

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 40%, so the description must compensate. It adds real meaning for estimate_id ('from a confirmed estimate') and idempotency_key (retry/dedupe purpose, which the schema leaves undocumented), and gestures at tool_names ('library tools alongside'), but says nothing about resolution_id or layout_objective, leaving two parameters unexplained anywhere.

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 — 'Order a custom analysis built for this data' — and scopes it to a 'confirmed estimate', which separates it from the upstream estimation siblings (path_estimate, review_estimate) and from re-run/reuse siblings. The optional 'library tools alongside' qualifier maps cleanly to the tool_names parameter.

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?

Gives two concrete prerequisites: the estimate must be CONFIRMED and 'the person's yes' (human approval) is required, plus a cross-reference for cost/timing ('Time: as path_resolver quotes'). It does not explicitly name when to prefer a sibling (e.g., path_rerun for an existing build) or state exclusions, so it stops short of a 5.

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