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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, yet the description still adds real substance: the calculation model (U·S·dT plus a 1.2 restart margin), catalogue ranges and COPs, 1600 equivalent hours, 50 L/occupant DHW rule and the 0.85x/3x undersizing-oversizing thresholds. The important caveat that output is indicative and needs a signed CVC note is disclosed. It does not say what happens with an empty call even though 0 parameters are required.

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 trigger condition is front-loaded and the sentence is dense with concrete numbers rather than filler. However, it re-lists the entire scene schema inline, which is redundant at 100% schema coverage and lengthens an already run-on paragraph.

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 readOnly annotations and no output schema, the description implicitly conveys what is returned (required power, chosen device, annual consumption, tank size, oversizing/undersizing verdict) and warns about the non-contractual nature of the result. Remaining gap: the two action modes and the all-optional, zero-required-parameter call behaviour are not addressed.

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 baseline is 3. The description restates the scene fields (parois, delta_t_dim_c, chauffage, occupants, ballon_ecs_litres) with some added rationale — why occupants matters (50 L/occupant) and what puissance_kw is checked against — but adds nothing about action or type_gen beyond what the schema already says.

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 precise verb+resource: sizing the CVC generator, covering heating power, catalogue device selection, DHW tank and verification of declared capacities. This scope is narrow enough to be told apart from generic siblings such as cao_bim_mep_dimensionnement or cao_energie, though no sibling is named as a contrast.

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?

"Appelez quand vous devez dimensionner le GENERATEUR CVC" gives an explicit activation condition, and "Indicatif — note CVC signee obligatoire" sets the boundary that this is not a final design. It never states when to prefer this over neighbours like cao_bim_mep_dimensionnement or cao_energie, nor when to use action=verifier vs action=choisir.

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