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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not restate that. It adds behavioral value by disclosing an internal 'contrôle de vraisemblance intégré (anti-erreur de sous-régime)' – a sanity check that guards against selecting the wrong sub-regime – and by naming the exact formula (points × valeur de service 2026 × coefficient). It also cites its data sources, which informs trust and versioning. No contradictions with 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 dense but well-organized: it front-loads the purpose and formula, then covers the regime coverage, then the routing logic, and finally the sources. Every sentence serves a purpose – identifying scope, giving the formula, naming contingencies, and citing references. It is not bloated; the length reflects the genuine complexity of regime routing. A minor deduction because it repeats the list of regimes in both the coverage sentence and the enum, but it's necessary for clarity.

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's complexity – 7 parameters, a 28-item enum, multiple regime families, and the need to route among several sibling tools – the description is remarkably complete. It covers the calculation, the coverage scope, the routing exclusions, the internal sanity check, and the data sources. There is no output schema, but the tool's purpose (computing a pension amount) is implicit, and the description gives the formula so the agent knows what to expect. The only minor gap is the lack of an explicit statement of the return value format (e.g., euros, annual vs monthly), but it is a model output of the pension, so it's acceptable.

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 every parameter already has a clear description in the schema. The tool description adds marginal semantic value by explaining the 'points × valeur de service 2026 × coefficient' formula, which clarifies how the 'points' parameter feeds the computation, and by noting that 'trimestres' parameters apply only to CNAVPL bases. This is a slight enhancement beyond the schema, so a baseline 3 is appropriate.

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 opens with a precise statement: it computes the gross pension for a single points-based regime using the formula points × 2026 service value × coefficient. It immediately enumerates the exact regime families covered (Agirc-Arrco, Ircantec, RCI, RAFP, the 10 liberal CNAVPL bases, and complementary/ASV) and explicitly routes other cases to sibling tools. This is a complete specification, far beyond a vague verb+resource.

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 is explicit about when to use this tool: 'À utiliser UNIQUEMENT pour un régime en POINTS.' It then names the exact alternatives for non-points regimes (annuities-based → retraite_pension_annuites, CNAV → retraite_estimation, full career multiple regimes → retraite_pension_totale) and warns against summing multiple regimes manually. This gives the agent decisive routing guidance with no ambiguity.

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