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

With no annotations provided, the description carries the full burden and delivers substantive disclosures: it warns that l/100km must be converted from MPG or km/L 'or the answer will be confidently wrong,' states that weekly_km=0 returns zero for weekly/monthly/annual figures 'rather than an error,' and reveals the monthly_cost quirk ('a twelfth of the annual figure, not weekly x 4.33'). These are exactly the behavioral traits an agent needs.

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 long but every section earns its place: purpose is front-loaded, the IMPORTANT paragraph isolates the single dangerous unit-conversion trap, and Args/Returns/scope are cleanly separated. There is no filler, redundancy is minimal, and the structure makes the critical warnings easy to locate.

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 calculator with no annotations and no output schema, the description is fully self-sufficient: it covers tool selection, all parameter semantics, the return value set (litres used, trip cost, cost per km, cost per 100 km, periodic costs), the key comparison figure (cost_per_100km), and scope exclusions. An agent has everything needed to invoke it 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 description coverage is 0%, so the description must compensate — and it does exhaustively. The Args section gives units for all four parameters (kilometres, litres per 100 km, NZD per litre), a realistic price band (2.60–3.00 for petrol in 2026) with guidance to ask the user rather than guess, and the sentinel semantics of weekly_km=0 for one-off trips. This far exceeds the bare 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?

Opens with a specific verb+resource: 'Work out the fuel cost of a trip, and of regular driving, in New Zealand.' Concrete use cases ('what does it cost to drive Auckland to Wellington', 'is a 6L/100km car worth it over an 9L/100km one') pin down the scope, and the final paragraph distinguishes it from sibling calculators by explicitly carving out road user charges, servicing, tyres, insurance and depreciation.

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?

States an explicit when-to-use rule: 'Use this for ANY question about what fuel costs: a road trip, a commute, the running cost of a car, or comparing two vehicles.' Also gives when-not-to-use via the scope exclusions, critically 'Not road user charges, which diesel and electric vehicles pay by the kilometre,' which routes the agent toward the sibling nz_road_user_charges_calculator without ambiguity.

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