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

Annotations only cover the safe-read profile (readOnly, idempotent), and the description goes well beyond: per-ISO data grain (rows are upgrades/facilities, not whole projects), per-ISO field availability, null never estimated, source and license citation per row, and as_of semantics (top-level is the OLDEST source). This is unusually rich behavioral context for a read tool.

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 trigger condition and coverage scope are front-loaded, and the do-not-use routing is last, which is a sensible order. The middle is dense and long, but nearly every clause (ISO list, grain caveat, per-ISO field gaps) carries information an agent would otherwise get wrong, so the length is largely earned rather than padding.

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 10-parameter, zero-required, dual-source tool with an output schema, the description supplies everything needed: coverage boundaries (five named ISOs, CAISO/NYISO excluded), per-source field variability, the iso label in results, and the summary/as_of structure. Return value detail is delegated appropriately to the output schema.

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 exceeds that by clarifying filter semantics not evident from the schema alone — new_since excludes the initial backfill, include_delisted returns dropped/completed projects, min_capacity only bites for gas — and by flagging that the type/state parameter help text ('Texas only') is out of date. That correction is genuine added value, though much of the rest restates 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 names the specific resource (planned/proposed gas pipeline and transmission projects) and explicitly scopes it to the forward build-out rather than the existing network. It distinguishes itself from siblings by name (get_power_pipeline, get_infrastructure, get_grid_intelligence, get_pipeline), so an agent can disambiguate without opening any schema.

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?

It opens with an explicit when-to-use trigger, gives three representative user questions, and closes with an explicit 'Do NOT use for...' list mapping each excluded case to the correct alternative tool. Nothing about when/when-not is left to inference.

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