calculate_energy_savings

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

No annotations are provided, so the description carries the full burden. It transparently describes that the tool opens an external site (switchai.it), pre-fills a form, and requires user verification and double opt-in. It also states that the tool does NOT finalize the activation without user confirmation.

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 lengthy but well-structured with numbered steps (FLUSSO). Each sentence serves a purpose, explaining the workflow and GDPR requirements. It could be slightly more concise, but the detail is justified given the complexity.

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?

Despite no output schema, the description explains the return value concept (3 best offers with activation links). It covers the entire flow, including external site behavior and user communication. The only minor gap is the lack of explicit details on the exact response format.

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?

With 100% schema description coverage, the parameter semantics are already well-documented. The description adds value by explicitly stating that personal data fields are used to pre-fill the form and that the tool requires all extracted data. This contextual information goes beyond the schema.

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 compares Luce or Gas tariffs and calculates annual savings, returning the best 3 offers with activation links. This distinguishes it from siblings like parse_energy_bill (extraction) and get_available_offers (list offers).

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 provides a detailed step-by-step flow (FLUSSO) explaining exactly when to use this tool: after extracting data from a bill. It instructs to pass all extracted personal data and warns about GDPR consent. However, it does not explicitly state when not to use it or compare to alternative tools.

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