get_prices

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

With no annotations, the description carries real weight and does it well: it discloses the 409 failure mode when no Amber account is linked, the resolution-to-horizon caps (30 → 24 h, 5 → 4 h), the GST-inclusive currency units, and a host-dependent UI side effect (card rendering). It stops short of stating auth requirements or whether the call is purely read-only, which is only implied by the 'get' prefix.

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?

Dense and front-loaded — the resource and payload lead, then constraints, then failure mode, then UI note. Every sentence carries information, though the trailing 'Hosts that support cards render a price chart' is the least load-bearing and could be trimmed without hurting selection.

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?

An output schema exists, so return-value detail is rightly omitted, and the description instead spends its budget on units, horizons, and the 409 condition — the things an agent cannot get from structured fields. The remaining gap is the meaning/source of site_id and an explicit bound on 'hours', which matter for correct invocation.

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 coverage is 0%, so the description must compensate, and it partially does: 'resolution 30 (up to 24 h) or 5 (up to 4 h)' documents the accepted values and their constraint on the forecast horizon, which the schema exposes only as a bare integer with default 30. 'hours' is never explicitly named or bounded beyond that implication, and site_id's origin (presumably from list_sites) is left unstated.

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?

States a specific verb+resource ('Amber Electric prices for the site') and enumerates the returned content: current interval, forecast, import price and feed-in earn, plus cheapest/dearest summary. Units (c/kWh incl. GST) further pin it down and distinguish it from siblings like get_earnings and get_curve, which the description does not overlap with.

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?

Usage is implied by 'current interval and the forecast' — an agent can infer this is the tool for live/forward price lookups — but there is no explicit when-to-use framing and no named alternative (e.g. get_curve for historical price series). The resolution limits hint at how to pick a time window but are not stated as selection guidance.

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