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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuine behavioral value: the criteria='ai_ready' buildability-vs-build-out distinction ('the most-built-out markets are frequently AVOID for new load'), the latency comparison, and the 300+ market scope. No contradiction with annotations. Only minor redundancy with the output schema prevents a 5.

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?

Long but front-loaded with the most critical routing decision, and every block (routing rule, latency trade, example, param summary, ai_ready trap, return shape, exclusion list) serves a distinct purpose. Minor redundancy exists where the return shape and param list restate what the output schema and input schema already document.

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?

Given the tool's complexity, routing to four sibling tools, the drill-in path, and the ai_ready trap are all fully covered, and the output schema handles return-value details. The only meaningful gap is the absence of prose guidance for fields and projection, though their schema descriptions compensate adequately.

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 meaningfully exceeds it by layering on the ai_ready semantic, all enum defaults, the min_capacity_mw 'filter floor' meaning, and a full example (criteria=fastest_growing region=us limit=10 min_capacity_mw=100). The fields and projection parameters receive no prose guidance, but their schema descriptions are self-sufficient.

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?

States the verb and resource precisely: 'the top N markets for X — one ranked list across the 300+ market set.' It actively distinguishes itself from execute_plan (siting questions), get_market_intel (deep read on one market), and analyze_site (lat/lon scoring), so an agent can tell it apart from siblings without opening their schemas.

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?

Provides an explicit routing rule: siting questions go to execute_plan, ranked-list-only questions stay here, with a quantified trade ('3 steps and roughly 4x latency') justifying the split. It also names exclusions for deep single-market reads (get_market_intel), site scoring (analyze_site), and siting-with-verdict (execute_plan), plus the drill-in path via get_market_dcpi_rank. A worked example maps a natural-language question directly to parameters.

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