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

Beyond the readOnly/idempotent annotations, the description discloses substantial behavioral detail: the exact calculation rules for both salarié and TNS/BNC regimes, the PASS values and floors/maxima, and the critical interpretation that it returns a deduction ceiling, not a tax saving (“PAS une économie d'impôt”). This goes well beyond the annotations and helps the agent avoid misusing the result.

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 it stays well-structured: purpose statement, then the two regimes in separate clauses, then scope caveats, then the misuse warning, then sources. Every sentence carries substantive information; however, the source citations and exact PASS figures add length beyond what is strictly needed for invocation, so it is not as lean as the most efficient descriptions.

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 (two legal regimes, specific formulas, explicit exclusions) and the absence of an output schema, the description is thorough: it explains what the result represents, the scope limits (no carryovers, no spousal pooling), the alternative tool for tax gain, and the legal sources. Nothing an agent needs to call it correctly is missing.

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%, so the baseline is 3. The description adds meaningful operational detail for both parameters: exactly how revenu_professionnel feeds into the 10% (and 15% for TNS) formulas, and how the boolean tns switches between art. 163 quatervicies and art. 154 bis with distinct PASS values. The schema already names these semantics, so the description's contribution is concrete numeric precision rather than new conceptual 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 immediately states the precise purpose: "Plafond de déduction PER de l'année" / "Plafond de versement PER déductible du revenu de l'année". It also distinguishes itself from sibling tools by explicitly routing the tax-gain use case to fiscal_per_gain and warning not to multiply by fiscal_tmi, so an agent can tell exactly what this tool computes versus its siblings.

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 gives explicit guidance on when to use this tool and when not to: "pour le gain d'un versement → fiscal_per_gain" and the clear scope marker "Version « express » : un seul revenu, HORS reliquats et HORS mutualisation entre conjoints". It also instructs the agent to never combine this ceiling with fiscal_tmi, which is a concrete usage constraint.

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