Get Power Availability Timeline

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

The description goes far beyond the annotations by revealing that the tool composes multiple data sources, never blends confidence classes, counts only under-construction+testing minus retirements in the derived cumulative_firm_signal_mw, and explicitly declares what is out of coverage (constraint_coverage). It also discloses the honesty limitation that generation is not deliverable load and that no delivery dates are provided. This is rich behavioral context that the annotations (readOnly, idempotent, non-destructive) do not convey.

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 dense but front-loaded with the core purpose, followed by composition details, honesty line, and routing guidance. It is longer than average because it carries a lot of behavioral transparency, but every sentence earns its place. A slight demotion for length and some redundancy in the honesty line, but overall well-structured and scannable.

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?

The tool has an output schema, so return values need not be spelled out. The description covers the tool's inputs, data sources, derivation logic, exclusions, limitations, and alternatives. Given the complexity of the tool and its sibling ecosystem, this is complete enough for an agent to call it correctly and interpret its results appropriately.

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?

Even though schema description coverage is 100%, the description adds significant meaning to the parameters: state is the timeline grain and can span ISOs, years defaults to 5, and mw is clearly labeled as 'CONTEXT ONLY' and 'never converted into an energize-by date'. The example 'state=OH' also demonstrates parameter usage. This exceeds what the schema alone provides.

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 verb ('get') and resource ('power availability timeline') and distinguishes itself from siblings by emphasizing 'WHEN' for one US state, year by year. It explicitly names what it is not (raw project list, live headroom, queue survivors, ranking) and gives concrete example queries, making it easy for an agent to select correctly.

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 description explicitly says when to use this tool ('Answers when is new capacity landing in Ohio') and lists what NOT to use it for, naming sibling tools (get_power_pipeline, get_grid_intelligence, get_refined_queue, rank_markets, ai_capacity_index) and their distinct purposes. It also provides a concrete invocation example ('Try: get_power_availability_timeline state=OH') and clearly states the tool's scope boundaries (supply-side only, no load-interconnection promises).

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