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. The description adds important behavioral nuance by warning that avg_time_to_power_months and avg_queue_wait_months are different measurements and must be quoted by name — a subtle trap that the schema alone would not reveal.

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 front-loaded with the primary use case and every sentence carries value — example, parameter guidance, return shape, metric warning, and exclusions. It loses one point because some content duplicates the input schema's valid-value list and the output schema's field list.

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 comparison tool with a single parameter, annotations, and an output schema, the description is complete: it states when to use, provides a concrete example, explains the difference between two confusing metrics, and explicitly routes the agent away from inappropriate uses. Nothing needed for correct invocation is missing.

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% and already lists the valid ISO values and the 2-4 range. The description repeats this information and adds an example call, but does not add meaningful semantics beyond the schema. This meets the baseline for full schema coverage.

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 states a specific verb and resource: 'side-by-side of 2-4 ISO grids' with the exact comparison dimensions listed. It clearly distinguishes from siblings by naming get_grid_intelligence and get_grid_scoreboard as the alternatives for different use cases.

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?

Explicitly says when to use: when a user wants a side-by-side in one call instead of N sequential get_grid_intelligence calls. It also provides explicit do-not-use conditions with named alternatives: do not use for global ranking (use get_grid_scoreboard) or single-ISO deep briefs (use get_grid_intelligence).

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