Compare ISO Regions

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context: it highlights that avg_time_to_power_months and avg_queue_wait_months are DIFFERENT measurements and warns the agent to use the exact metric name, preventing misinterpretation. It also clarifies the tool aggregates multiple ISOs in one call. This goes beyond the structured fields, though it could further explain data sources or freshness, so a 4 is appropriate.

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 appropriately sized for the tool's complexity: every sentence earns its place, starting with a clear usage directive, followed by an example, parameter details, return shape, a critical metric distinction, and exclusions. It is well-organized and front-loaded with the most actionable information.

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?

The output schema already documents the return structure, so the description doesn't need to repeat it. Beyond that, it covers the tool's scope (2-4 ISOs), the specific metrics compared, the key metric ambiguity, and exclusions relative to siblings. Given the complexity of a multi-ISO comparison tool, no significant gaps remain. It even includes a realistic usage example.

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 description coverage is 100% (the only parameter 'isos' is fully documented with valid codes). The description adds critical extra semantics: the comma-separated format, the 2-4 ISO limit, and that these come from the 7 live US ISOs. It also gives a complete worked example, which clarifies usage beyond the schema's plain list of values.

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 clearly states it compares 2-4 ISO grids on specific metrics (fuel mix, demand, renewable/gas share, etc.) in a single call, using the verb 'compare' with the resource 'ISO grids'. It also explicitly distinguishes itself from sequential get_grid_intelligence calls and other sibling tools like get_grid_scoreboard, making its purpose unmistakable.

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 opens with 'Use when a user wants a side-by-side of 2-4 ISO grids' and provides a concrete example. It explicitly states when NOT to use it: not for global ranking (use get_grid_scoreboard) and not for single-ISO deep briefs (use get_grid_intelligence), giving clear alternatives.

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