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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds substantial behavioral depth beyond those hints: confidence classes are never blended, the derived cumulative_firm_signal_mw counts only under-construction plus testing minus retirements, and the tool intentionally refuses to promise delivery dates. It also declares what is out of coverage rather than estimated, which is exactly the honesty needed for an AI agent.

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 description is long, but every sentence earns its place: scope, data composition, the derived-number definition, example queries, the honesty line, a concrete try command, and exclusions. It is front-loaded with the core purpose and uses semicolons and colons to keep dense information digestible.

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?

For a tool that answers a nuanced temporal question with blended data sources, the description is complete: it explains the inputs, the output grain ('one US state'), the derivation rule, the limitations, and the sibling alternatives. Given the output schema and annotation coverage, nothing an agent needs to decide whether and how to call this tool 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?

Schema coverage is 100%, so the baseline is 3. The description reinforces the meaning of the state and mw parameters, but it largely echoes what the schema already says — for example, 'CONTEXT ONLY' and 'never converted into an energize-by date' appear in the parameter description itself. There is no significant parameter semantics added beyond the schema.

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 deliverable — year-by-year power-availability timing for one US state — and immediately gives concrete example questions it answers. It names sibling tools it is not intended for, so an agent can distinguish it from get_power_pipeline, get_grid_intelligence, and rank_markets without inspecting schemas.

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 explicitly taught: 'Try: get_power_availability_timeline state=OH' gives a concrete invocation pattern, and the 'Do NOT use' clause lists the precise alternatives and what each is for. This is strong routing guidance with no reliance on inference.

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