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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, covering the safety profile. The description adds genuine behavioral value beyond annotations: 'PAS de total sommé (les leviers ne s'additionnent pas naïvement)' discloses the deliberate non-summing behavior, and 'Chaque montant porte sa confiance et sa source' explains the confidence/source attribution per figure. This is useful context that annotations do not provide. No contradiction with 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?

The description is a dense, single run-on block of text with heavy em-dash and semicolon use. It front-loads the purpose well, but the legal citations (CSS articles, Circulaire CNAV 2026-04, Service-Public references) are appended as a large tail that adds bulk. It is information-rich and every element arguably earns its place, but the lack of sentence structuring hurts readability.

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?

This is a high-complexity tool (17 parameters, aggregating 7+ levers) with no output schema, so the description must carry the return-value burden. It does explain the output conceptually (ranked menu with gain/ROI/confiance/sources, no summed total) and the legal grounding. The precise output structure is not fully specified, but for the complexity involved the description covers the key aspects an agent needs.

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 76% — moderately high. Four parameters (parts, trimestres_acquis, trimestres_requis, pension_complementaire_annuelle) lack schema descriptions, and the tool description does not compensate for these. However, the schema itself carries strong semantics, notably the tmi warning about fraction vs. percentage and the activation conditions ('active les gains chiffrés'). The description adds little parameter-level meaning beyond what the schema provides, warranting the baseline 3.

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 states a specific verb ('renvoie') and resource ('le MENU CLASSÉ des leviers d'optimisation retraite'), enumerating the exact levers covered (rachat de trimestres, surcote parentale, retraite progressive, âge de départ, cumul emploi-retraite, optimisation du SAM, PER). It clearly distinguishes itself from the sibling lever-specific tools (retraite_rachat, retraite_surcote_parentale, retraite_progressive) by being the aggregated ranking view rather than a single-lever calculator.

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 implies usage — it takes a full situation (âge, trimestres, SAM, statut, enfants) and returns a ranked menu — which suggests it is the overview tool versus the granular siblings. However, it never explicitly states 'use this for a comprehensive comparison; use retraite_rachat for detailed single-lever analysis' or provides any when-not conditions. The routing to siblings is left to inference.

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