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

Annotations only declare the generic write/non-destructive/non-open-world profile. The description adds real behavior: the estimate is recomputed from the file saved with the original quote (no re-upload), the result is persisted, a new private link is issued, and the earlier link keeps serving the earlier quote. The last point is a non-obvious versioning guarantee the agent cannot infer from 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?

Four sentences, all load-bearing, with the trigger condition front-loaded before the mechanics and the exclusions. No restatement of the title and no 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 mutation tool with an output schema already covering return shape, the description supplies everything else: the eligibility condition, what is and is not accepted, the recompute-from-saved-file behavior, and the link-versioning outcome. Nothing an agent needs to call it correctly is missing.

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 coverage is 100%, so per-parameter text is already handled and the baseline is 3. The description adds provenance semantics the schema does not stress — the link must come from one of our quotes — and clarifies that color changes apply to the same material. Small but genuine value over the schema.

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 ('Update a 3D print quote') and immediately narrows scope to changing quantity or color on a quote that already exists. An agent can distinguish this from get_print_quote (create a new quote) without opening either schema.

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?

Explicit trigger ('when someone wants a different quantity or color on a quote... already gave them') plus explicit exclusions: no new file, no different material, no link that did not come from one of our quotes. The negatives route the agent away from unsupported requests instead of leaving it to guess.

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