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

Annotations already declare this a safe, idempotent read, so the description is free to add the higher-value context it does provide: the simulation methodology, that the premium is a benchmark not a quote, that a reportUrl must always be surfaced, how to phrase results (statistical estimate, no advice, no 'model recommends'), and widget-mode behavior where the text reply should be short. That is behavior an agent could not infer from 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 opening and exclusions are front-loaded well, but the 'when to use' clause is substantially restated mid-paragraph ('Use when a user asks whether pet insurance is worth it for their dog, how much vet care or insurance costs for a breed...'), which duplicates the first sentence. The presentation/advice guidance is worth keeping; the redundancy is not.

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 4-parameter simulation tool with no output schema, the description covers the return contents, the mandatory reportUrl hand-off, the estimate-vs-quote framing, the advice boundary, and the widget display case. An agent has everything needed to call it and present results correctly.

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 the baseline is 3, but the description earns extra by tying parameters to their model effect: ZIP 'adjusts to local vet prices' and emergency_savings_usd drives 'the chance of a year with bills above the owner's emergency savings'. Breed and age are used but not elaborated beyond what the schema already says.

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 names a specific verb and resource ('runs TheDogs.app's cost simulation'), the exact inputs it consumes (breed, age, ZIP), and the concrete outputs (expected vet costs, risk-of-exceeding-savings, plan structure under 5%, modeled premium). It is clearly distinguishable from siblings like get_breed_profile or compare_dog_breeds, which cover traits rather than simulated costs.

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 triggering conditions are given ('when the user asks what a specific dog breed will cost at the vet, whether pet insurance is worth it'), plus hard exclusions: no symptoms/emergencies/treatment (refer to a veterinarian), no training/behavior how-tos, and no non-U.S. cost questions. This is close to a complete when/when-not routing statement.

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