Rank Markets

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that rank_markets returns only the ranked list without attached verdict/grid-check, and elaborates the ai_ready criterion's unique semantics — ranking by DCPI buildability rather than installed capacity, with the caveat that built-out markets are often AVOID for new AI load. It also exposes the return payload and data_source/methodology fields.

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 well-organized with clear sections (routing, example, params, ai_ready caveat, return format, exclusions). Some redundancy exists — the execute_plan routing is explained both in the front door check and later — and the text could be slightly trimmed, but every section serves a purpose.

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 ranking tool with a full output schema, annotations, and sibling context, the description is complete: it covers routing logic, all parameters, return fields, special-case criteria behavior, and explicit non-use cases. No significant gaps remain; the only blemish is the limit range discrepancy.

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 description adds a fully worked example (criteria=fastest_growing region=us limit=10 min_capacity_mw=100), explains all criteria values including the ai_ready special case, and clarifies defaults. However, it states limit is 1-50 while the schema allows up to 500, creating a minor inconsistency that slightly undermines parameter clarity.

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 explicitly states the tool ranks markets by specified criteria and returns a ranked list across a 300+ market set. It distinguishes itself from execute_plan, get_market_intel, analyze_site, and get_market_dcpi_rank with clear 'use this for' and 'do not use for' guidance.

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?

A 'FRONT DOOR CHECK' explicitly tells the agent when to call execute_plan instead, when rank_markets is the correct choice, and why (latency trade-off). It also lists exclusions such as deep single-market reads (get_market_intel), lat/lon scoring (analyze_site), and siting questions needing verdicts/grid check (execute_plan).

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