AI Footprint

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond them: it discloses the output categories and a methodological caveat that lifecycle footprints are 'not like-for-like.' This is useful framing an agent would not get from annotations alone.

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?

A single front-loaded sentence leading with the verb and required unit, followed by the output categories. The long enumerations are dense but each maps to a real return value; only slightly wordy.

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?

With no output schema, the description must convey what comes back, and it does — the comparison categories plus the AI-prompt count and the like-for-like caveat. For a one-parameter read-only conversion tool, nothing needed to invoke it correctly 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 description coverage is 0% and the sole parameter title is a bare 'Water Ml', so the description carries the burden. It explicitly names the unit ('a volume of water (mL)'), resolving the only semantic ambiguity for the required input.

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?

States a specific verb+resource ('Convert a volume of water (mL) into everyday comparisons') and enumerates the exact comparison categories returned. The scope (mL input, everyday-context output) is distinct from the estimate_* siblings, so an agent can tell them apart without opening schemas.

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 is implied by the purpose (you have a water volume and want it in relatable terms), but the description never says when to choose this over estimate_ai_footprint, especially since it also returns 'number of typical AI text prompts' — an overlap that could route an agent to the wrong sibling. No explicit when/when-not guidance.

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 establish readOnly/idempotent/non-destructive, so the description sensibly spends its words elsewhere: it discloses the return payload (per-prompt, per-day, totals, everyday equivalents, assumptions, source link) and the interpretive difference between 'onsite' (as vendors report) and 'comprehensive' (wider researcher boundary). That framing is real added context an agent cannot get from the annotations.

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?

Front-loads the purpose, then parameters, returns, and routing — no filler sentences. It runs as a single dense prose block rather than separating parameter notes from output notes, which slightly slows scanning, but every clause carries 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?

Although there is no output schema, the description enumerates the return contents (per-prompt, per-day and total figures, equivalents, assumptions, source link), covers all four parameters at 0% schema coverage, and routes to the correct sibling. Nothing needed to call it correctly 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 description coverage is 0%, so the description carries the full documentation burden and meets it: queries_per_day (prompts per day), days (e.g. 250 workdays, 365), usage with concrete Wh/prompt values per enum, and boundary with each enum's meaning. It supplies numeric magnitude for enums that the schema only names.

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?

Opens with a specific verb and resource ('Estimate the water (mL) and energy (Wh) used by chat-style AI prompts') and explicitly names the sibling it is not (estimate_session_footprint) for agentic/coding sessions. An agent can distinguish it from estimate_session_footprint without opening either schema.

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?

Gives the use context (chat-style prompts from ChatGPT/Claude/Gemini), an explicit exclusion and redirect ('For agentic/coding sessions use estimate_session_footprint instead'), and the trade-off behind each enum choice. When-to-use and when-not are both stated rather than inferred.

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 this as a safe, idempotent, closed-world read, so the bar is lower; the description still adds substantive context beyond them — it discloses the return shape (central estimate plus a 0.3x–3x range), states the estimate is order-of-magnitude and calibrated to published figures, and explicitly warns it is 'not a measurement'. That accuracy caveat is exactly the kind of trait an agent needs before presenting numbers to a user.

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?

Front-loads the purpose, then moves efficiently through per-parameter guidance and the return-shape caveat in three dense sentences with no filler. It is slightly long within a single sentence, but every clause carries 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?

With no output schema, the description correctly compensates by describing the return value (central estimate plus range) and its uncertainty. Combined with the annotation coverage of the safety profile, the only real hole is the undocumented 'boundary' parameter and the lack of any routing hint versus estimate_ai_footprint.

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 0%, so the description must carry the load, and it largely does: input_tokens is defined as uncached prompt tokens, output_tokens as including reasoning/thinking tokens, cached_input_tokens as prompt-cache reads, and model_class values are glossed (small = Haiku/mini/Flash-class). Only the 'boundary' parameter (onsite vs comprehensive) is left entirely unexplained.

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?

States a specific verb and resource — estimate water and energy of an AI session from token usage — and scopes the input to 'an agent or coding-assistant run'. It is clear against siblings like get_methodology or compare_water_use, but it never explicitly distinguishes itself from the very similar estimate_ai_footprint.

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?

Gives real invocation guidance ('pass the SUM across all model calls') and clarifies which token stream belongs where, which is genuinely useful. However it offers no when-to-use/when-not-to-use framing and never mentions the near-identical sibling estimate_ai_footprint, leaving the agent to infer which tool to pick.

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, closed-world, and non-destructive, so the safety profile is covered. With no output schema, the description usefully enumerates what is actually returned (figures, boundaries, sources, limitations, citation line, divergence reasons), adding real value; it does not mention auth or freshness, but those are minor for a static read-only reference tool.

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?

Two sentences with zero waste: the first front-loads the full return payload, the second states the use case. Every clause earns its place, including the concrete 0.3–50 mL range that signals the tool's scope.

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, read-only reference tool with no output schema, the description compensates by fully enumerating the return contents and the reason the tool exists. Nothing an agent needs in order to select and call it correctly 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a no-param tool applies, and the description correctly adds no spurious parameter discussion.

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?

States a specific verb ('Return') and a well-defined resource: per-prompt energy/water figures, accounting boundaries, sources, limitations, citation line, and the ~100x divergence explanation. It is clearly distinguishable from the estimation siblings (compare/estimate) because this one retrieves methodology rather than computing a footprint.

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?

'Use it to explain or check a published AI water or energy figure' gives a concrete use context that separates it from the estimate_* and compare_* siblings. It stops short of explicitly naming an alternative tool or stating when NOT to use it, so it lands just below the top band.

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