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

Annotations already declare read-only/idempotent/non-destructive behavior, and the description adds useful runtime behavior: default UTC interpretation, inclusive start vs exclusive end, and timezone override semantics. It does not directly state whether this endpoint paginates or caps rows, though the get_derivation contrast implies it may.

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 organized into three focused sections—definition, time-boundary semantics, and alternative routing—with no filler. Each sentence adds necessary call or selection information, and the core metric is stated first.

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 output schema covers return shape, and the description covers the subtle time-window behavior and the most important alternative endpoint. The remaining gaps are the values/behavior for aggregation and psr_types, which are meaningful but partially inferable or discoverable via sibling tools like list_psr_types.

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?

With zero schema description coverage, the description compensates only partially: it explains start/end/tz in detail, but leaves psr_types and aggregation undefined in terms of accepted values or effect. zone is self-explanatory, and 'per production type' hints at psr_types, but aggregation remains ambiguous.

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 opening line names the returned metric—aggregated generation in MW per production type—and the title supplies the verb, so an agent can tell this is a generation-query endpoint. It differentiates from get_derivation for price-metric work, but it does not explicitly contrast with other generation-adjacent siblings such as get_load or get_series.

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 gives concrete conditions: use a UTC or tz-interpreted window, remember end is exclusive, set end to the next month's first day for a full calendar month, and route generation-weighted price metrics to get_derivation with the capture_price slug. This is explicit when-to-use and when-not-to-use guidance with a named alternative.

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