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

Annotations already declare this a safe, idempotent, non-destructive, closed-world read, so the description's job is to add method and outcome context — and it does: it discloses the demand formula (45 l/day per N, N = max(bedrooms+1, occupants)), the reheat-time relationship (volume × ΔT / (14.3 × kW)), and the three outputs returned (BS 6700 minimum, rounded recommended size, reheat time). It also flags the coil-size caveat that a heat pump cylinder needs a larger coil than a boiler cylinder.

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 purpose and the demand rule are front-loaded, and the paragraph structure maps sensibly onto method, sizing logic, and caveats. It is longer than strictly needed for invocation — the coil-size paragraph is explanatory rather than operational — but no sentence is 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?

With an output schema present the description need not enumerate return fields, yet it still describes what the result contains. For a six-parameter engineering calculator with a formula-based method, the description supplies the standard reference, the core equation, default behaviour, and the professional disclaimer, leaving nothing an agent needs in order to call 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 100%, so a baseline of 3 applies, but the description goes further by explaining the interaction between parameters: occupancy defaults to bedrooms-plus-one logic for new builds, and a larger heat pump means a smaller cylinder because reheat time falls with kW. It also contextualises storageTemp by noting the separate weekly pasteurisation cycle above 60.

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: working out daily hot water demand for a dwelling and the cylinder volume a heat pump requires, citing MIS 3005-D 3.5.2 and BS 6700/MGD 007. This is clearly distinguishable from siblings like heat_pump_size, room_heat_loss or radiator_flow_temperature, which address different calculations.

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?

It gives a clear usage frame: 'for understanding a system and checking a quotation', and warns that installed work still needs a design and site survey from a certified installer. It stops short of routing the agent between alternatives (e.g. when to use heat_pump_size instead), so it is clear context without exclusions.

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