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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety bar is low. The description still adds real context: the underlying data source is 'this week's EIA average' (recency and external dependency), heat contents come from EIA, and default behaviors are stated (state defaults to US, efficiency defaults to 100 meaning fuel energy only). It does not mention rate limits, caching, or failure behavior for unknown states, which keeps it from a 5.

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?

Three sentences, front-loaded with the primary output and the formula, then optional inputs. Dense but nearly every clause earns its place. The parenthetical and stacked clauses make the first sentence slightly heavy, but there is no filler or repetition of the title.

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, the description must describe returns, and it does: delivery cost, cost per million Btu, and an oil-vs-propane per-MMBtu comparison, plus optional electricity/natural gas comparisons. The main remaining gap is output units and shape (e.g., what currency/units the comparison figures take, whether results are per-delivery or annualized), which an agent would still have to discover.

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 86%, so the schema already carries most parameter meaning and the baseline is 3. The description adds the arithmetic relationship between gallons and price, clarifies that efficiency is applied on top of the fuel-energy cost ('fuel energy only' default), and frames electricity and natural gas rates as comparison-only inputs. That is meaningful semantics beyond the field descriptions.

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 the specific computation: cost of a heating oil or propane delivery computed as gallons times this week's EIA state average (or a user price), plus cost per million Btu and an oil-vs-propane comparison. That is clearly a cost calculator rather than a price lookup, which implicitly separates it from get_heating_oil_propane_prices and get_heating_fuel_price_history. It never names those siblings, so the differentiation is inferred rather than stated.

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 only usage guidance is conditional on optional inputs: add an electricity rate or natural gas rate 'to compare.' There is no statement of when to choose this tool over the two price-lookup siblings, and no exclusions or prerequisites. Usage is implied by the purpose sentence but not routed explicitly.

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