Carbon footprint summary

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint as true. The description reinforces these by stating 'Read-only; never mutates state.' and adds context about data sources (Agribalyse, Our World in Data). No contradictions; the description fully aligns with annotations and adds value.

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 extremely concise: two sentences plus attribution and a state disclaimer. It front-loads the core purpose and includes all essential information without redundancy. Every sentence contributes meaningfully.

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 has 4 parameters and no output schema, the description adequately covers input semantics and behavior. It explains the two input options, swap suggestions, and response format. While the return structure is not detailed, the description is sufficient for correct invocation. Could include a brief example of the output, but not necessary.

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% (all 4 parameters have descriptions). The description adds value by providing an example format (`items: [{name, grams}, ...]`) and clarifying the interaction between date and items. This helps an AI agent construct correct inputs beyond the schema alone.

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 clearly states the tool's purpose: estimating carbon footprint of a meal or a day's intake, with optional swap suggestions. It uses specific verbs ('estimate', 'compute') and accurately describes the resource (carbon footprint). No sibling tool overlaps with this functionality, so it is well-distinguished.

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 explains two usage modes: passing items for an arbitrary meal or using a date for logged intake. It also notes that items wins over date when both are provided. While it does not explicitly mention when not to use this tool, the context is clear and sufficient for an AI agent to determine correct invocation. Slight room for improvement in contrasting with other tools.

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