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

Annotations already cover safety (readOnly, idempotent, closed-world, non-destructive), so the description correctly spends its budget elsewhere: it discloses the rules applied to the computation (barème de l'impôt sur le revenu, prélèvements sociaux, abattements) and the output shape (net amount per source). It also warns that the calculation is not covered by Marcel's reference datasets so the result is indicative – a genuine trust signal not present in 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?

Sentences are dense and every one carries information, but the ordering is inverted: four sentences of negative routing precede any statement of what the tool computes. An agent scanning for purpose must read past the exclusions first. Front-loading the calculation sentence would materially improve it without lengthening the text.

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 annotations already declare the safety profile and the description covers scope, rules applied, output form and the indicative-result caveat, the definition is largely complete for a read-only calculation tool. The residual gap is parameter-level meaning for the nested objects, which is left entirely to the schema and the schema says nothing.

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 0% across five nested parameters, so the description must carry the burden, and it largely does not. It lists the sources (PER, LMNP, assurance-vie, SCPI) which loosely maps to parameter names, but says nothing about how pension.monthlyNet is consumed, or what yearsOfDrawdown, yearsOfFractionation or taxableIncomeAtRetirement do. Worse, 'Entrées : profil et actifs' does not correspond to any actual parameter, adding noise rather than meaning.

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 does state a specific verb and resource: 'Calcule le revenu mensuel net à la retraite en agrégeant une pension déjà connue et d'autres sources patrimoniales : PER, LMNP, assurance-vie, SCPI.' The four source types make it clearly distinguishable from pension estimation or transmission tools. The main flaw is placement – the actual purpose appears only in the fifth sentence, after a block of exclusions.

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?

Routing is explicit and multi-directional: pension estimation belongs to marcel_estimate_pension, donation/démembrement scenarios to optimiser_patrimoine, gap-versus-target to marcel_find_gap, chronological projection to marcel_financial_twin. It also carves out what the tool does NOT do ('ne calcule pas la pension'), which is exactly the when-not guidance an agent needs.

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