Get latest grid carbon intensity for a zone

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.