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

No annotations are provided, so the description carries the full burden. It discloses material behavioral traits: region changes the answer significantly (Wellington 34.61c vs Balclutha 48.93c), fixed charges matter, and the output includes biggest_users and a region comparison. The 'Returns:' section further explains what the tool computes. It does not explicitly address side effects, but this is a read-only calculator, so the omission is minor.

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 well-organized, with a one-line purpose, a 'Use for' list, highlighted behavioral guidance, and clearly labeled Args/Returns sections. It front-loads the core purpose and keeps related information grouped. Some details like exact regional rates add illustrative value but could be trimmed without losing essential guidance.

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?

With no output schema and no annotations, the description provides a thorough Returns section listing daily/monthly/annual costs, usage vs fixed charge separation, per-appliance costs, biggest users, and regional comparison. It also covers the main decision points for parameter usage. Minor gaps remain, such as the exact semantics of appliance_hours values and what 'the rest' includes, but overall it is sufficient for an agent to invoke the tool 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%, and the Args section compensates thoroughly. For each parameter it adds practical meaning: region accepts an 'MBIE survey town, or nz average', household_size is a range with '5 means five or more', daily_fixed_charge is 'In DOLLARS a day', custom_rate_cents is 'in cents per kWh including GST', and appliance_hours lists valid keys like heat_pump and ev_charger. This is exactly the level of detail needed when the schema provides only names and defaults.

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 opens with a specific verb and resource: 'Estimate a New Zealand household's electricity cost, by region and appliance.' It also provides concrete example queries that distinguish it from sibling calculators like nz_fuel_cost_calculator and bmi_calculator. The scope is immediately clear with no ambiguity about what the tool computes.

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?

The 'Use for:' section lists realistic user queries and gives contextual guidance like 'Ask for the town' and 'If they have their bill, pass custom_rate_cents...'. It clearly establishes when to use the tool, but it does not explicitly name alternatives or state when not to use it, 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.