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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the bar is lower, but the description adds rich behavioral context: 'latest' means newest published rather than 'now', GB uses non-comparable operational factors and is excluded by default, unknown zones are returned instead of failing, and observation-time gaps are surfaced via warnings. No contradiction with the annotations exists.

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 well-structured with a one-line purpose, use cases, data contract, dedicated GB warning, args, return shape, and examples. It is long, but the complexity of the GB comparability issue and data-currency semantics justifies the length. Minor redundancy exists because the GB caveat appears in both the data contract and the dedicated GB section.

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 description is exhaustive for the tool's complexity: it explains units, timestamps, freshness, GB exclusion logic, unknown-zone handling, observation-time gaps, attribution requirements, coverage start, and return structure. The detailed output schema relieves the need to describe return values, and the examples cover representative ranking queries.

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%, so the schema already documents every parameter in detail, including the important include_gb_in_ranking caveat. The description's Args section largely restates defaults, though the examples add practical usage context. This meets the high-coverage baseline without adding substantial new parameter-level meaning.

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 opening sentence states an exact verb and resource: 'Rank several electricity zones (or all 45) by their most recently published carbon intensity, cleanest first by default.' It also names sibling alternatives in the examples ('Don't use for: one zone (get_carbon_intensity) or a time series (get_intensity_history)'), so an agent can distinguish this tool from its siblings.

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 use cases ('where should I run this training job', 'is Sweden cleaner than Poland right now') and lists when NOT to use it, naming the sibling tools directly. It also covers a critical selection rule: use this tool for ranking multiple zones, not for single-zone queries or historical series.

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

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

Annotations already mark the tool readOnly/idempotent and non-destructive, so the description's job was to add behavioral nuance — and it does extensively. It discloses that 'latest' means newest published, not 'now', that readings carry age_minutes/age_human, that GB uses different emission factors and must not be ranked against other zones, that coverage starts on a specific date, and that attribution is a licence condition. This is exactly the kind of context annotations cannot express.

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?

Though long, the description is organized into clearly labeled sections — scope, data contract, Args, Returns, reporting guidance, examples, and errors. Every section earns its place: the data contract prevents the agent from reporting stale or non-comparable numbers as if they were current, and the reporting rules are actionable. The critical 'ONE zone' scope and sibling exclusions are front-loaded, not buried.

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 live-data tool with real-world reporting hazards, this description is complete. It covers unit semantics, time semantics, freshness interpretation, regional factor differences, coverage start, attribution obligations, error behavior, output structure, and exactly how to phrase the answer. Combined with the rich output schema and annotations, an agent has everything needed to invoke the tool and present results safely.

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%, and the schema already documents zone codes, case-insensitivity, natural-name resolution, the 'never substitute a neighbour' rule, and response_format's enum/default. The description's Args section largely restates this information rather than adding meaning beyond the schema. It does reinforce how errors behave, but the baseline of 3 is appropriate because the schema already carries the parameter documentation burden.

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 opens with a precise verb and resource: 'Return the most recently published carbon intensity for ONE electricity zone.' It clearly distinguishes this tool from siblings by explicitly saying it is not for comparing zones or getting time series, and it gives concrete example questions such as 'how clean is the German grid right now' that an agent can match against user intent.

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?

Usage context is explicit: it lists what questions this tool answers, provides example zone mappings, and states exclusions: 'Don't use for: comparing several zones (use compare_zones), or for a time series (use get_intensity_history).' It also tells the agent to call list_zones when unsure and never substitute an uncovered neighbouring zone, leaving no ambiguity about when to pick this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: the unit meaning (gCO2eq/kWh, lower is cleaner), the distinction between 'latest' (newest published) and 'now', the GB operational-factor caveat, the data-start boundary, the half-open window semantics, truncation behavior (server_truncated true means incomplete), and the rule never to interpolate missing points. This goes far beyond the annotations and is essential for correct interpretation.

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 every section is purposeful and well factored: a one-sentence purpose, examples, data contract, window semantics, args, return structure, truncation warning, and errors. It is front-loaded with the core purpose and examples, and the headings make it scannable. While it could be trimmed, no sentence is redundant; given the tool's complexity (7 parameters, return contract, error cases), the length is justified. This is strong structure, though not as lean as a two-sentence description.

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, the description is exceptionally complete. It covers parameter usage, return structure with a concrete JSON example, window semantics, truncation handling, error messages, attribution licensing, and even the caveat about missing points. It also explains the summary statistics and how to use them, and notes that max_points trimming does not affect summary statistics. The output schema is provided, but the description adds operational context (like server_truncated) that is not in the schema. Nothing an agent needs to call this tool correctly is omitted.

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 input schema has 100% description coverage, documenting each parameter's format, defaults, and constraints (e.g., 'EXCLUSIVE' for 'to', 'Ignored if from is given' for 'hours'). The description does not add meaning beyond what the schema already provides for the parameters themselves; it reiterates the same semantics. The only incremental value is clarifying the default window and the 'hours' shorthand, but those are also mentioned in the schema ('hours' description mentions 'the last N hours'). With full schema coverage, a baseline of 3 is appropriate.

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 opens with a specific verb and resource: 'Return the interval-by-interval carbon intensity history for ONE zone over a time window.' It explicitly scopes to a single zone, distinguishing it from cross-zone tools, and provides concise example queries ('how has the German grid varied today') that anchor the purpose. This is unambiguous and immediately differentiates the tool from siblings like compare_zones.

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 explicitly states when to use the tool via example intents ('what was the cleanest hour in France yesterday') and then explicitly lists exclusions: 'Don't use for: a single current value (get_carbon_intensity) or cross-zone ranking (compare_zones).' It names the sibling alternatives and the conditions that disqualify them, leaving no ambiguity about routing.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints, and the description adds substantial behavioral context beyond them: the gCO2eq/kWh unit contract, 'latest' means newest published not 'now', typical_lag_hours semantics, and the lifecycle-vs-operational factor_basis distinction. It also warns that GB numbers must not be ranked against the other 44 zones, which is critical correctness information.

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, front-loading the core purpose and then layering caveats and examples. Most sentences earn their place because they convey correctness-critical semantics. However, the GB operational-factor point is repeated in close proximity, so it could be tightened slightly without losing 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?

For a discovery/registry tool with three optional parameters and an existing output schema, the description is exceptionally complete. It covers coverage scope, unsupported regions, filter behavior, return contract, caveats about lag and factor_basis, and example invocations. An agent has everything needed to call this tool correctly and interpret its results.

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%, so the structured definitions already document all three parameters. The description adds value beyond the schema with usage examples, coverage mapping (entsoe/eia/uk-neso to regions), and the note that searching for an unsupported country returns zero rows and should be reported as not covered. This exceeds the baseline but is not exhaustive about edge-case behavior.

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 opens with a specific verb and resource: 'List every electricity zone gridcarbon covers,' and enumerates the exact attributes returned (upstream data source, reporting resolution, comparability). It also disambiguates from the sibling measurement tools by explicitly stating 'This tool returns no measurements itself,' so an agent can distinguish it from get_carbon_intensity and get_intensity_history.

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 an explicit trigger: 'Call this whenever you are not certain a zone code exists.' It explains why the data tools reject unknown codes and warns that substituting a neighboring country's grid would be a fabrication. It also gives concrete examples mapping user questions to filters, such as 'Which US grids do you cover?' -> source='eia'.

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