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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuine behavior beyond them: the exact metrics returned and the important limitation that it 'reports past movement and does not forecast'. With no output schema present, this return-value disclosure carries real weight. It omits data freshness/update cadence, which matters for a price tool an agent may present as current.

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 trigger condition before the payload description. Every clause earns its place: triggers, return contents, the no-forecast caveat, and the hand-off to tankful_tank_plan.

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?

A no-parameter, read-only tool with no output schema needs the description to say what comes back and what it cannot do — both are covered, including the explicit 'does not forecast' boundary and the escalation path to tankful_tank_plan. Nothing an agent needs to invoke it correctly is missing.

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?

The tool takes zero parameters, so there is no parameter meaning to add; the baseline for a 0-param schema is 4. The description correctly implies the scope is fixed to national-level Irish figures with no filtering options, which is the only parameter-adjacent fact worth knowing.

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 states a specific resource (Irish heating oil prices) and a specific output shape (national 500-litre midpoint, 4- and 12-week change, year-ago price, announced tax changes), which separates it from the snapshot-style siblings like tankful_national_prices and tankful_uk_prices. The opening clause frames it as a trend/direction tool rather than a lookup, so an agent can route on intent.

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 concrete trigger intents ('going up or down', 'compare with last month or last year', 'tax change is coming', 'buy now or wait') and explicitly names the companion call tankful_tank_plan for the buy-or-wait case. It stops short of stating when NOT to use it — notably it never distinguishes itself from the national-prices snapshot sibling, which is the most likely mis-route.

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