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

The description reveals key behavioral details beyond annotations: the lifecycle selector parameter (operating/planned/retired/canceled) and the fact that there is no status/status_group parameter (a common confusion). It also notes the return format (JSON aggregates with citations, optional generator-level records) and explicitly states what it does not compute. Annotations already declare read-only/idempotent, so this adds context without contradicting.

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 each part serves a purpose: core purpose, usage criteria, scope exclusions, and alternative tools. It is front-loaded and structured, with no filler words or repetitive content.

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?

Despite the minimal schema, the description provides enough to correctly invoke the tool: it explains the params pattern, the lifecycle default, and the optional records flag. The output schema likely covers return structure. It also situates the tool among siblings, making it complete for an agent to select and use.

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?

The input schema only has a generic params object with no property definitions (0% coverage). The description compensates by enumerating acceptable filter keys (state, county FIPS, balancing authority, fuel, prime mover, technology, lifecycle, year) and mentions include_records. It also clarifies the default lifecycle value. However, it doesn't provide detailed value formats or the full set of possible keys, so while it's strong, it falls short of exhaustive.

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 opens with a specific, multi-faceted statement: 'Query verified U.S. generator-level operating, planned, retired, or canceled power capacity from EIA-860M.' This clearly identifies the action (query), resource (generator-level power capacity), and scope (U.S., lifecycle status). It also lists distinguishing filter dimensions (state, county FIPS, balancing authority, fuel, etc.) that separate it from sibling tools like generation or interconnection queue.

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 states 'Use this for capacity questions...' and then provides a clear list of exclusions ('Does not determine electricity supplied, generation MWh, real-time dispatch, capacity factor...'). It also names specific alternative tools for interconnection queue queries. This is textbook when/when-not guidance with alternatives.

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