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

Annotations already declare readOnly/idempotent/closed-world, so safety is covered; the description adds substantive behavior beyond that — the legal basis (art. 163 quatervicies vs 154 bis), the exact PASS reference years and floor/cap values, and the critical warning that the output is a cap rather than a tax saving. This is context an agent cannot infer from 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 core statement is front-loaded and the routing warnings follow logically, with sources last. It is dense and slightly repetitive (the cap concept is restated three times: title, first line, and the 'PAS une économie d'impôt' clause), but nearly every sentence carries decision-relevant information.

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?

For a two-parameter, annotation-covered, no-output-schema tool this is close to complete: regime selection, formula, statutory source, and exclusions are all present. The only gap is that the return shape (whether it returns a single amount or per-regime detail) is implied rather than stated.

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 coverage is 100% and both parameters are already documented, so the baseline is 3; the description nonetheless adds meaning by explaining the two regimes that the boolean 'tns' selects (10% + 15% tranche vs 10% flat) and by tying formulas to each. It does not re-explain the net-vs-gross income nuance, which the schema already handles well.

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 names a specific resource and computation — the year's PER deductible contribution cap ('Plafond de déduction PER de l'année') — and disambiguates it from fiscal_per_gain ('c'est un PLAFOND de déduction, PAS une économie d'impôt') and fiscal_tmi. An agent can tell exactly which fiscal concept this returns without opening the schema.

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?

It routes the agent explicitly to the sibling for a different question ('pour le gain d'un versement → fiscal_per_gain'), issues a concrete prohibition ('ne jamais multiplier ce plafond … par fiscal_tmi'), and scopes itself with exclusions ('version express : un seul revenu, HORS reliquats et HORS mutualisation entre conjoints'), which tells the agent when this tool is the wrong choice.

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