Grid Intelligence

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

Annotations carry the safety profile (readOnlyHint, idempotentHint, destructiveHint all safe), so the bar is lower and the description earns full credit for context beyond them. It discloses three critical behavioral traits: market names resolve to their ISO via the DCPI row with a resolved_from block, balancing authorities return only live generation mix while other metrics stay ISO-level, and the two time metrics are non-interchangeable with the queue-wait derivation formula (12 + 0.6 months/GW, clipped 12-66). These are exactly the traps that would corrupt an agent's output. No contradiction with annotations.

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?

Information-dense but long (roughly 280 words). It is front-loaded with the trigger use case and example, and every clause earns its place — the alias list, BA caveat, metric warning, and sibling routing are all high-value. The return-field enumeration is partially redundant with the output schema, but it anchors the essential time-to-power vs queue-wait warning, so the length is largely justified.

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 high-complexity tool (4 params, three input modes, a counterintuitive resolution quirk, and a metric disambiguation), the description covers the critical decision points: valid inputs, market resolution behavior, BA data-scope limits, metric non-interchangeability, and when-not-to-use. Gaps are minor: no error behavior for invalid regions, and the schema's '0 required params' label sits awkwardly against the description's implication that a region or market is needed.

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 baseline is 3, but the description adds real value beyond the schema: it groups iso/region/region_id as aliases, enumerates the full 7-ISO valid set plus 40+ balancing-authority examples, documents the special PJM-DOM zone for Ashburn, and clarifies that market is not an alias but a name resolved to a larger ISO. The only reason it isn't a 5 is that the schema already covers much of the same ground.

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 names a specific verb+resource+scope: 'the flagship grid-headroom + interconnection-queue brief for one ISO', anchored to a concrete trigger question ('can I get N MW of power in <ISO> and how long will it take?') and a worked example call. It distinguishes itself from siblings by name ('Do NOT use to compare 2+ ISOs side-by-side (use compare_isos) or for the global greenest-first ranking (use get_grid_scoreboard)').

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?

Explicit when-to-use guidance is given as a verbatim user-intent trigger, and explicit when-not-to-use exclusions name the exact sibling alternatives (compare_isos, get_grid_scoreboard). The market-vs-ISO edge case is also covered with a warning that the figures describe the ISO, which is larger than the market named — leaving no ambiguity about interpretation.

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