Grid Scoreboard

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses important behavioral traits: freshness is not uniform, mix and demand have separate clocks with mix_age_hours and demand_vs_mix_lag_hours fields, some grids report no gas share, and Australia/Singapore are unranked in partial_grids. This level of caveat disclosure is exceptional and prevents the agent from misinterpreting stale or partial data.

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 and dense, but it earns its length given the complexity of the data source and the many caveats. It is front-loaded with the core scope and key data, then systematically covers freshness, exceptions, and provenance. Minor redundancy like 'Try: get_grid_scoreboard' and the very long parenthetical enumeration prevent a perfect score, but the structure is purposeful.

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 zero-parameter tool, the description is remarkably complete: it lists all regions, all metrics, freshness caveats, source attribution, unranked grids, Brazil's missing gas share, and the specific fields to check before narrating results. Given the output schema exists, this provides everything an agent needs to call and interpret the tool correctly.

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 tool has zero parameters, so the input schema is trivial and the description cannot add parameter-level meaning. The baseline for 0-param tools is 4, and the description instead enriches understanding of the returned fields (mix_period, mix_age_hours, freshness_basis, partial_grids, counts_basis), which is appropriate for this parameterless tool.

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 a concrete resource ('GLOBAL grid scoreboard') and specifies exactly what it returns: ranked grids with renewable share, gas share, fuel mix, and demand. It also distinguishes itself from sibling tools by explicitly comparing against compare_isos (pairwise) and get_grid_data (single ISO), so an agent can select it unambiguously.

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 gives explicit when-to-use guidance: 'One call answers which grid worldwide is greenest, or most gas-reliant, for siting a data center?' and explicitly contrasts with alternatives ('vs compare_isos (pairwise) or get_grid_data (single ISO)'). It also gives example queries ('which grid is cleanest right now', 'how is ERCOT doing at this moment'), leaving no ambiguity about when this tool is the right choice.

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