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

With no annotations, the description carries the full burden and does so well: it discloses the free-tier truncation to the most recent 30 days per series, the Pro requirement for older data, that values are exact-as-published with unit/date/source URL, that incomplete days are flagged rather than filled, and the licensing terms (non-commercial with attribution; commercial needs Pro). These are exactly the access, data-quality, and legal traits an agent cannot get from the schema.

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 but front-loaded: resource and scope first, then fuel codes, then the alternative product, then access tiers, then data-quality and licensing. Nearly every clause carries information, with minor redundancy between the opening 'Free (no key or free key)' and the closing licensing sentence.

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?

No output schema and no annotations, so the description must carry a lot, and it covers access tiers, units, data provenance, and licensing. It does not describe the shape of a returned row beyond 'unit, date and original source URL', and never explains limit/offset behavior, leaving a small gap for a 6-parameter data tool.

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 83%, so the baseline is 3, but the description adds meaning beyond the schema: it expands the fuel codes (NG = gas, COW = coal, SUN = utility-scale solar only) and fixes the unit (thousand MWh = GWh), plus the geographic scope of 'state'. It says nothing about limit/offset pagination semantics, which the schema handles.

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 resource with verb-like framing: 'Net electricity generation by state and fuel from the EIA,' plus scope (50 states, DC, U.S.; monthly since 2001) and unit convention (thousand MWh = GWh). This clearly separates it from demand, price, or retail siblings, though it never explicitly contrasts itself with market_grid_demand or market_wholesale_prices.

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?

Given an explicit alternative for one case ('For 12-month shares use data product us-electricity-generation') and clear access-tier conditions (free = latest 30 days; Pro key = full history). No exclusions or routing guidance relative to the other 20+ market_* siblings, so it falls 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.