tax-retirement

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

With annotations already declaring readOnlyHint=true, idempotentHint=true, and openWorldHint=false, the description adds substantial behavioral context: it is stateless, computes an additional amount due on top of IR and CEHR, and details the internal calculation components (PFU, CEHR, majorations, décote). It does not contradict the annotations and enriches the agent's understanding of the tool's behavior.

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 front-loaded: it starts with the tool's identity and formula before moving to distinctions and practical usage. Every part contributes useful information for a complex tax calculation, though the single long sentence format sacrifices scannability slightly.

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 an 11-parameter tax calculation tool with no output schema, the description supplies the legal references, formula, interaction with sibling tools, and stateless nature. It implies the return is an amount due but does not explicitly describe the output format (e.g., a number or breakdown), which is a minor gap given the tool's complexity.

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 is already documented in the input schema, including defaults, constraints, and detailed French explanations. The main description adds formula-level context but does not provide meaning beyond the schema for individual parameters, so the baseline score of 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 immediately names the tool's subject (CDHR), states the exact legal basis (art. 224 CGI), and gives the core calculation formula (20% minimum on adjusted RFR minus effective taxation). It explicitly distinguishes itself from the CEHR and IR, so an agent can tell what this tool does and what it does not do 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 names the sibling alternatives (fiscal_cehr, fiscal_impot_revenu) and gives a clear integration rule: the amount is ADDITIONAL and must be added to, not substituted for, those other taxes. This is explicit when-to-use and how-to-combine guidance, leaving no ambiguity for tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds domain context (legal article, BOFiP source, stacking behavior with IR/CDHR) but says nothing about the computed output or edge cases, and with no output schema that would have been useful.

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?

A single dense sentence with the resource and legal basis front-loaded, followed by sibling disambiguation. The parenthetical source citation is defensible for a tax tool but is the least load-bearing element.

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 read-only calculator whose annotations cover the safety profile and whose schema fully documents all four parameters, the description supplies the missing domain framing (legal basis, sibling relationships). Only the return shape is unaddressed, which is a minor gap given no output schema exists.

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%, and the schema itself documents the RFR smoothing mechanism (rfr_n1/rfr_n2) and the single/couple thresholds. The description only names the required RFR input, adding no semantics beyond what the schema already provides. Baseline 3 applies.

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?

States a specific tax computation (CEHR) on a specific base (revenu fiscal de référence), cites its legal basis (art. 223 sexies CGI), and explicitly distinguishes it from the two siblings it is most likely to be confused with (fiscal_cdhr and fiscal_impot_revenu). An agent can route to it without opening any 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 explicitly states the relationship to alternatives: it is distinct from CDHR, it is added on top of the barème IR (fiscal_impot_revenu), and CDHR (fiscal_cdhr) may stack on top of it. That is close to when-to-use guidance, though it never states a negative condition such as 'do not use for the CDHR itself' in imperative form.

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

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

Annotations already mark it as read-only, idempotent, and closed-world. The description adds useful behavioral context beyond annotations by stating it is stateless and by specifying the calculation rules, applicable rates, and legal references.

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 front-loads the core comparison and tax outcome before adding legal details. The parenthetical source list is long, but the complexity of the domain justifies most of the length.

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 complex tax calculation tool with no output schema, the description explains what is compared, the relevant rates, and the stateless behavior. It could be more explicit about the exact return structure, but the core invocation needs are well covered by the schema and annotations.

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 context beyond the schema by explaining that PS rates depend on the nature of the income and by referencing the 2OP option, the 40% dividend allowance, and deductible CSG.

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 comparison: PFU flat tax versus barème progressif for capital income, and says it determines the more favorable option. It also specifies the tax scope and rates, making it clearly distinguishable from sibling fiscal tools such as fiscal_tmi or fiscal_prelevements_sociaux.

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 clearly indicates the context of use: comparing the taxation of a capital income under PFU versus the barème option. However, it does not explicitly name alternative tools or state when not to use this tool versus related fiscal simulations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, covering safety and determinism. The description adds meaningful behavioral context: the result is the total household tax delta (IR + 17.2% social levies), not a simple loyers × TMI multiplication, and it cites the exact legal basis. It does not describe output format or edge cases, so it stops short of the highest bar.

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 single dense paragraph that front-loads the core arbitrage purpose before drilling into calculation details, thresholds, alternatives, and sources. Every sentence contributes necessary context for a complex tax tool, with no wasted filler.

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 a 10-parameter tool with no output schema and high complexity, the description covers purpose, usage, alternatives, threshold rules, and calculation basis. It even hints at the return value ('Gain = Δ d'impôt TOTAL...'), but it does not specify the output structure or all returned fields, leaving a minor gap for an agent expecting to interpret results.

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 each parameter has a detailed legal description, so the baseline is 3. The description adds parameter-relevant meaning by tying the loyers parameter to the 15,000 € micro-foncier threshold and the mandatory réel regime beyond it, and by summarizing how charges, intérêts, and déficit are used in the réel calculation. This goes beyond what the schema alone states.

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 and resource: 'Arbitrage du régime des revenus fonciers d'une location NUE : micro-foncier ... vs régime réel.' It explicitly distinguishes from the sibling fiscal_lmnp_regime for furnished rentals, so an agent can identify the tool's scope 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 gives explicit when-to-use ('micro-foncier ... vs régime réel'), when-not ('Au-delà de 15 000 € de loyers, le réel est obligatoire : pas d'arbitrage'), and the alternative for a different case ('Pour une location MEUBLÉE, utiliser fiscal_lmnp_regime'). This is complete routing guidance.

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

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

Annotations already cover readOnly/idempotent/openWorld, so the bar is lower; the description adds genuine behavioral detail — statelessness, the conditional plafonnement gating, and the fact that the 800k€ barème starts below the 1.3M€ threshold. It does not describe the exact output shape, but the logic disclosures go beyond 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?

Front-loaded with the purpose and legal framework, and every clause carries substantive information (thresholds, conditional capping, stateless note). It is dense with CGI citations but not padded, so length is justified for a rules-heavy tax calculation.

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?

No output schema exists, so the description must explain return behavior; it does so by clarifying that the IFI is returned pre-plafonnement when revenu_foyer is absent. Combined with full schema coverage, this is nearly complete for an agent to call it correctly, with only the exact result fields unspecified.

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 the schema already documents dettes, revenu_foyer, residence_principale, etc. The description references the base and dettes as inputs and explains the plafonnement trigger, but this largely duplicates what is already in the parameter descriptions — baseline 3 applies.

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?

States a specific verb (compute) and resource (IFI tax) with the exact legal basis (CGI art. 964, 977, 974, 979) and scope. Sibling tools like fiscal_impot_revenu or fiscal_prelevements_sociaux are clearly distinct from this real-estate-wealth tax 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?

Explicitly states the condition under which the art. 979 plafonnement is applied (revenu_foyer and autres_impots_annuels supplied) versus when IFI is returned before capping. It also clarifies the stateless model (inputs, no dossier read), though it does not name sibling tools or when to prefer them.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false). The description adds real behavioral context beyond that: the result is IR 'brut' at the barème only, excludes CEHR and CDHR, uses 2025 revenues against the 2026 barème, and incorporates décote and QF capping. It does not describe the return object, but no output schema exists to lean on.

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?

Front-loads purpose then routing, in a single dense block with no filler. The trailing source citations add provenance but are arguably clutter rather than invocation aid.

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 seven-parameter calculation tool with no output schema, the description conveys what the returned value represents (gross barème IR, net of nothing, to be combined with CEHR/CDHR and PER gain). It stops short of describing the response shape, which would be useful given no output schema exists.

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%, and the schema documents all seven parameters in detail, including CGI references and capping rules. The description adds no parameter-level syntax but reinforces concepts (QF plafonné, décote) that map to the schema; baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb+resource: computes gross IR on the 2026 progressive barème for a household (quotient familial plafonné, décote). It explicitly distinguishes itself from siblings by declaring it is barème SEUL, excluding CEHR/CDHR, and by routing PER calculations to fiscal_per_gain.

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?

Gives explicit when-to-use routing: for high-income households add fiscal_cehr then fiscal_cdhr, noting the differential complement is already net of IR and CEHR and must be summed, not substituted. It also names fiscal_per_gain for PER savings, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it is stateless, the calculation is grounded in statutory text rather than doctrine ('BOFiP dédié attendu S2 2026'), and it discloses that a theoretical-maximum assumption is flagged via hypothese_economie when inputs are missing.

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 purpose and scope are front-loaded, but the text is dense with overlapping parentheticals and a truncated sources list at the end that repeats the LF 2026 art. 47 reference already stated earlier. Several clauses restate the same legal basis, diluting an otherwise informative definition.

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?

With no output schema and 10 parameters, the description must describe returns, and it does: the annual amortization, the year-one and 9-year tax saving, and the hypothese_economie signal. Combined with the 100 % schema coverage and the caveat about the pending BOFiP, an agent has enough to invoke the tool correctly; only the absence of an explicit alternative-tool pointer keeps it short of 5.

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 the schema already documents all 10 parameters in detail. The description reinforces a few semantics (TMI supplied or derived from revenu_net_imposable, base = 80 % of price, déficit cap of 10 700 €) but adds little the schema does not already carry, so the baseline 3 applies.

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 French tax device (Jeanbrun, LF 2026 art. 47) and states precisely what it computes: annual amortization retained and the tax saving (year and over 9 years). It positions the tool against the sibling regime tools by noting it succeeds Pinel and defines its own legal window, so an agent can tell it apart from fiscal_foncier_regime or fiscal_lmnp_regime.

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 gives the eligibility window (21/02/2026 → 31/12/2028) and the 80 % base rule, which implies when the tool applies, but there is no explicit when-to-use/when-not-to-use statement nor a pointer to the alternative sibling tool for other rental regimes. Usage is inferable rather than directed.

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

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

Annotations only declare readOnly/idempotent/closedWorld, so the description carries real weight: it discloses the computation basis (Δ of TOTAL household tax, IR barème + 18.6% social levies) and a secondary output (verdict on resale horizon / amortization reintegration, loi Le Meur). The caveat that the réel path is not quantified without valeur_bien is a genuinely useful behavioral trait. It stops short of describing result structure in detail, which is acceptable given no output schema.

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?

One dense but well front-loaded paragraph: the arbitrage purpose and gain definition come first, and the sibling routing clause is placed before the trailing legal citations. The parenthetical CGI source list is somewhat heavy but justified for a tax-calculation tool where the rule basis matters.

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 13-parameter calculator with no output schema, the description does the needed work: it explains what is returned (total tax delta plus a resale-horizon verdict), the degradation path when valeur_bien is absent, the alternative tool, and the legal basis. Remaining gaps are minor and mostly covered by 100% schema documentation.

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, but the description adds domain meaning the schema does not: the 50%/30% micro-BIC abattement, the art. 39 C amortization cap, and the tourisme_non_classe linkage to loi Le Meur. This helps the agent understand what regime and tourisme_non_classe actually drive.

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 precise verb and resource ('Arbitrage du régime d'une location MEUBLÉE non professionnelle : micro-BIC vs régime réel') and explicitly distinguishes the tool from the sibling fiscal_foncier_regime for unfurnished rentals. An agent can identify the tool's exact scope without reading 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 names the alternative ('Pour une location NUE, utiliser fiscal_foncier_regime') and a precondition for meaningful output ('Sans valeur de bien, le réel n'est pas chiffré'). Both the when-to-use and when-not-to-use routing is explicit.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. Beyond that, the description adds real behavioral context: the 10 000 €/18 000 € cap, the SOFICA/Girardin/Pinel Outre-Mer uplift, and which niches are explicitly excluded (dons Coluche, Malraux, déficit foncier, PER). It does not state what the response contains, which is a remaining gap.

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 rule (global cap plus its two rates) is front-loaded, followed by the exclusion list and the input note. It is dense but well ordered; the trailing legal-citation parenthetical is skippable but not a serious defect.

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 computation tool with no output schema, the description thoroughly explains the domain rules but never says what it returns (e.g., the effective reduction, remaining headroom, or per-niche breakdown). Given the absence of an output schema, that omission leaves the agent guessing about the result shape.

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 each of the five parameters is already documented in the schema (including variante, nb_enfants, nb_personnes). The description only confirms that the niche list is the input, adding little beyond structured data – the baseline 3 applies.

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 the resource clearly (plafonnement global des niches fiscales) and states the governing rule (art. 200-0 A CGI) with concrete thresholds, so an agent knows this tool computes/caps the aggregate tax-niche advantage. It does not explicitly differentiate itself from siblings like fiscal_impot_revenu or fiscal_per_plafond, leaving overlap to inference.

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?

There is no statement of when to call this tool versus alternatives such as fiscal_per_plafond or fiscal_impot_revenu, nor any exclusions. The only usage hint is 'La liste des niches est fournie en entrée', which is input format rather than invocation guidance.

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

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

Annotations already establish readOnly/idempotent/openWorld=false, so the safety profile is covered; the description goes further by disclosing the internal method (full recalculation, not TMI × versement) and that it is the stateless version. It stops short of stating boundary behavior, e.g. whether a versement above the deductible ceiling is clamped or errors out.

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?

Front-loaded with the core computation and the anti-pattern warning (never TMI × versement) before the routing hint and source list. Dense and somewhat run-on, and the legal-source tail is long, but every clause carries domain value rather than filler.

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 10-parameter, no-output-schema tool in a complex tax domain, the description covers what is computed and how, plus the sibling boundary. It omits what the response actually looks like (a euro amount, presumably) since no output schema exists to carry that, and does not say how the many optional parameters influence the result.

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% and the schema itself is unusually detailed (per-parameter legal citations, plafonds, case T handling), so the description's job here is minimal. It adds the note that the payment reduces the RFR, but no syntax, units or constraint information beyond what the schema already supplies.

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?

States a specific computed quantity (tax gain from a deductible PER payment) and even gives the formula it implements, Δ(IR barème + CEHR + CDHR). It explicitly distinguishes itself from the closest sibling, fiscal_per_plafond, so an agent can route between them without opening either 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?

Names the alternative tool (fiscal_per_plafond) and the exact condition that selects it (when the user wants the maximum deductible amount rather than the tax gain). It also flags the case where the naive approach misleads (CDHR-capped households where marginal gain is ~20% rather than the TMI).

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

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.

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

Annotations already establish read-only, idempotent, closed-world behavior. The description adds rich context beyond that: it computes total tax, each component and net vendeur, applies abattements with exoneration thresholds (IR 22 ans, PS 30 ans), reintegrates LMNP amortissements per 2025 reform, and handles specific exonérations. This is well beyond what annotations convey.

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?

Front-loaded with the core purpose and scope. However, it is a dense, single-paragraph run-on that includes extensive legal citations and parenthetical detail, which makes it less scannable than ideal. Every sentence is relevant, but structure could be improved.

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?

Despite lacking an output schema, the description explicitly states what is returned (impôt total, chaque composante, net vendeur). It covers exonérations, abattements, and the LMNP reform. With 100% schema coverage and annotations present, the definition is complete for an agent to call the tool correctly.

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 the schema already documents all 13 parameters thoroughly. The description adds some overarching context (abattements, LMNP reintégration, exonérations) but does not provide additional syntax, format, or meaning for individual parameters beyond what the schema states. 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?

States a specific verb (calculer/rendre) and resource (impôt total sur plus-value de cession immobilière) with precise scope (hors résidence principale, IR + PS + surtaxe, après abattements). Explicitly distinguishes itself from the sibling fiscal_surtaxe_pv_immobiliere by noting the surtaxe is already included.

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?

Provides explicit when-to-use guidance: 'Point d'entrée pour une cession complète' and a clear when-not by naming fiscal_surtaxe_pv_immobiliere as reserved for surtaxe seule. Also notes that exonérations are handled, reducing ambiguity.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description only needs to add context. It discloses the exact return format (fraction 0-1 plus a percentage field), the two possible rate values, and legal sources. No contradictions.

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 every sentence earns its place: purpose, return format, unit distinction, scope, alternative routing, and sources. It is front-loaded with the core purpose and avoids fluff.

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 simple read-only lookup with one enum parameter, the description covers return format, units, scope, alternatives, and legal basis. Nothing an agent needs to invoke 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%, with the enum and a descriptive example already provided. The description reinforces that the parameter selects the nature of capital income but adds no new syntax or format details beyond the schema.

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?

States a specific purpose: returns the social levy rate (17.2% or 18.6%) for capital income by income type. It explicitly distinguishes itself from tmi and retraite_ps_pension, so an agent can tell it apart from siblings without opening schemas.

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?

Explicitly scopes the tool to capital income only and directs pension/retraite cases to retraite_ps_pension. It also contrasts with tmi on return units (fraction vs percentage points), providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the description is free to add domain behavior — and it does, disclosing the per-enfant application of the 777 barème, the 779 I abattement, the 15-year rappel rule and the parents=2 moiety split. Return format is not described, but the calculation semantics are unusually well exposed.

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?

Front-loaded with the purpose, but it is a single dense run-on paragraph mixing formula, article citations and exclusions. Every clause carries information, yet the wall-of-text form makes it harder to scan than a structured two-or-three sentence version.

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?

No output schema exists, so the description must convey what is returned — and it does (droits dus par enfant, droits évités par donation, tranche marginale sur 100 000 €, plus the article sources). Only the exact return shape/field names are left unspecified.

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 the schema already documents all three params, so baseline is 3. The description goes further by explaining the operational consequence of parents=2 (two successions, each on half the assets, 100 000 € abattement per parent per child), which the enum alone does not convey.

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?

Names a specific computation: droits de succession en ligne directe plus the donation savings (art. 784), with the exact tax base (actif net transmissible, per-child abattement). An agent can distinguish this from fiscal_ifi or fiscal_tmi 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?

Gives clear context (direct-line succession, children heirs) and an explicit scope exclusion: 'Hors assurance-vie (art. 990 I / 757 B)' and 'Même calcul que l'étude patrimoniale (cTR)'. It does not however name a sibling tool to use for the excluded assurance-vie case.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds useful behavioral context: the surtax-only scope, the input precondition, the €50,000 trigger, and a warning not to add this to the sibling tool. It does not describe the exact response format, but that is minor for a one-parameter calculation tool.

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 compact and front-loaded: it establishes the standalone surtax scope, gives the input condition and threshold, routes to the sibling for total tax, warns against double-counting, and cites the legal source. Every element earns its place.

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 read-only calculation tool with one required parameter and no output schema, the description is complete. It provides input semantics, threshold, relation to the sibling tool, a misuse warning, and the legal source, leaving no critical ambiguity for an agent deciding whether and how to call it.

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?

Although the schema documents the parameter at 100%, the description adds decisive meaning beyond the label 'Plus-value nette imposable (€)'. It clarifies that the value must already be net of holding-period allowances and that the €50,000 threshold determines applicability.

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 clearly identifies the tool as computing the standalone additional surtax on a net taxable real-estate capital gain above €50,000, using a bracketed scale. It explicitly contrasts this with the sibling fiscal_plus_value_immobiliere, so an agent can tell them apart immediately.

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 states exactly when to use this tool: when the net taxable gain is already computed after holding-period deductions. It also gives an explicit alternative for the total disposal tax and warns against double-counting, which is strong usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the output is in percentage points (unit PERCENT, e.g. 30 = 30%), it is a marginal rate only, and it explicitly enumerates what the value excludes (changement de tranche, décote, CEHR, CDHR).

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?

Front-loaded with the definition and unit before the misuse warning and source citation, so the agent gets the essential facts first. It is dense and fairly long, but every clause (unit contrast, misuse warning, cross-tool routing) carries information; only the inline legal sourcing is arguably expendable.

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?

No output schema exists, and the description still conveys the return value's unit and scale, along with its semantic limits and the sibling tools to use for adjacent questions. For a read-only rate calculator that is complete.

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 the schema already documents all seven parameters including the intricate plafonnement rules for parent_isole, demi_parts_195_abe and residence_alternee. The description adds no per-parameter meaning beyond that, which is the appropriate baseline when the schema does the heavy lifting.

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?

States a precise verb+resource (taux marginal d'imposition du foyer au barème 2026) with the computation basis (plafonnement du quotient familial). It distinguishes itself from fiscal_prelevements_sociaux by naming the sibling and the different unit it returns.

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?

Explicit when-to-use and when-NOT-to-use: the agent is told not to multiply this rate to size a tax saving (PER versement, déduction) because TMI ignores tranche change, décote, CEHR and CDHR, and is routed to fiscal_per_gain or fiscal_impot_revenu instead. That is a real anti-misuse instruction, not implied guidance.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds useful context: it performs no calculation and cites source files. However, it does not describe the return structure or failure behavior, so it only partially supplements 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 compact and front-loaded: core purpose first, then the critical 'Ne calcule rien', then source references. Every sentence contributes and there is no redundant filler.

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 zero-parameter, read-only planning map, the description adequately covers purpose, usage timing, and data provenance. The output format is not specified, but the intended use is clear enough for an agent to invoke it correctly.

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?

The tool has zero parameters, so the baseline is 4. The description appropriately notes it calculates nothing, and there are no parameter meanings to clarify beyond the schema.

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 clearly identifies the tool as a capabilities/planning map for the Qotien engine, specifying what it exposes (what the engine can do and its reliability by domain). It also distinguishes itself from calculation siblings by explicitly stating 'Ne calcule rien'.

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 timing: call it BEFORE choosing another tool, for planning and deciding when to hedge. It implies it should not be used for calculations, though it does not name a specific alternative tool.

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

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

Les annotations indiquent déjà readOnlyHint=true et idempotentHint=true, et la description ajoute des informations comportementales utiles : le résultat est un résumé par clé (valeur, libellé, fiabilité), pas le détail complet, et la source est versionnée (references_officielles.json v0.8.6). Cela va au-delà de ce que les annotations fournissent.

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?

La description est courte, va à l'essentiel et place l'action en tête. Chaque élément apporte une information utile : action, filtres, type de retour, alternative et source. Aucun mot superflu.

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?

Pour un outil de recherche simple avec deux paramètres optionnels, aucune sortie structurée et des annotations couvrant la sécurité, la description est suffisante : elle précise le contenu du résumé, le nom de l'outil alternatif pour les détails et la version de la source. L'agent dispose de tout le nécessaire pour appeler ou non l'outil.

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?

La couverture du schéma est de 100 %, donc le schéma documente déjà q et domaine. La description répète l'idée de recherche par mot-clé et de filtre par domaine, sans apporter de détails supplémentaires sur les formats ou comportements. Le baseline 3 est donc approprié, avec une légère perte car la mention « fiscal/retraite » omet la valeur successor présente dans l'enum du schéma.

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?

La description identifie clairement l'action (lister des clés publiques), la ressource (le référentiel), les filtres disponibles (domaine, mot-clé) et le type de résultat (résumé par clé). Elle distingue explicitement l'outil de referentiel_valeur, ce qui lève toute ambiguïté entre les deux outils.

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?

La description indique clairement quand utiliser cet outil (recherche/liste de clés publiques avec résumé) et redirige explicitement vers referentiel_valeur lorsque le détail sourcé complet est nécessaire. L'alternative est nommée et le critère de choix est précis.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral value beyond annotations: 'Jamais un chiffre nu' promises a provenance-rich response, and the list of returned fields (source primaire, référence légale, date de vérification, niveau de fiabilité) tells the agent what to expect. It also implies unknown-key handling via redirection to referentiel_recherche.

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?

Four sentences, each earning its place: purpose, return characteristics, fallback guidance, and data source. The opening phrase 'Valeur du référentiel (sourcée + datée)' duplicates the annotation title, a small redundancy, but the rest is compact and front-loaded with the core behavior.

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 single-parameter lookup tool with no output schema, the description compensates reasonably: it enumerates the provenance fields returned and gives the fallback tool for invalid keys. It does not spell out the exact JSON envelope or error codes, but an agent has enough to call it correctly and interpret the response.

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 the parameter description already provides stable-key semantics, examples, and a pointer to referentiel_recherche. The tool description adds minor context ('2026', 'constante fiscale ou retraite') but no new parameter-level meaning beyond what the schema already states, so the 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?

States a specific verb+resource: returns the sourced and dated 2026 value of a fiscal or retirement constant by its stable public key, with source, legal reference, verification date, and reliability level. It also distinguishes itself from the search sibling by adding 'Clé inconnue → referentiel_recherche', making the lookup-vs-search split explicit.

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?

Gives an explicit alternative condition: unknown key → referentiel_recherche to list available keys. This is clear guidance for the main decision an agent faces. It does not mention referentiel_versions for historical/versioned lookups, but the 2026 framing and the named fallback cover the common case.

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

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

Annotations already carry readOnlyHint=true and idempotentHint=true, so the safety profile is established. The description adds valuable context beyond that by enumerating exactly what the tool reveals — version history, cadence, next review date, and reliability levels — and even cites the underlying source file. No contradiction 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?

A single front-loaded sentence that leads with the core purpose, uses em dashes to enumerate content compactly, and closes with a concrete use case. The parenthetical source citation adds provenance without bloat. Every element earns its place.

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 zero-parameter metadata tool with no output schema, the description fully carries the burden of explaining return content. It lists the information categories an agent can expect — current vintage, history, cadence, next global review, reliability levels — which is complete for someone deciding whether this tool answers a freshness question.

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?

The tool takes zero parameters, so the baseline of 4 applies. There is nothing to document, and the description sensibly spends no space on parameters.

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 purpose: it provides version and freshness metadata for the referentiel (current vintage, version history, cadence, next global review, reliability levels). It clearly differentiates itself from the sibling tools referentiel_recherche and referentiel_valeur, which query actual values, whereas this tool reports on the data's provenance and currency.

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 closing clause 'pour savoir de quand datent les valeurs et quand elles seront re-vérifiées' gives an explicit use case for when to invoke this tool. It doesn't name alternatives or exclusions explicitly, but the purpose is distinct enough from the value/recherche siblings that an agent can infer when to call it. Lacks an explicit 'use X instead' routing.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true; the description adds the crucial approximation nature, the output shape (point central, fourchette, niveau de confiance), and that it substitutes for a missing RIS rather than the reverse. No contradiction with annotations. A small gap: it doesn't state whether results vary across calls or detail the confidence computation, but the safety profile is covered by 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 purpose is front-loaded before the caveat and routing. It is somewhat long, but every clause earns its place: purpose, the critical 'not certain' caveat, sibling routing, and source citations. No filler or repetition of schema content.

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 7-parameter, 3-required estimation tool with no output schema, the description covers the method, the return value shape, the substitution caveat, and the sibling alternatives. It explains why a fourchette/confidence level is returned rather than an exact value. Minor omissions (precise confidence definition, traitement_indiciaire handling for fonctionnaires) are partially covered by schema, so the package is adequate.

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 the schema already documents all 7 parameters, their defaults, minimums, and the accepted statut values. The description adds some semantic color (SAM plafonné au PASS, décote, and how trimestres_acquis/annee_debut_carriere tighten the range) but that mostly restates what the schema param descriptions already convey. Baseline 3 is appropriate since the schema carries the load.

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?

States a specific verb ('estimation'), resource (pension), and the exact inputs (statut, revenu, âge, âge de départ) with the method (SAM plafonné au PASS, décote). Explicitly distinguishes itself from the exact-calc siblings by declaring it is 'PAS un calcul certain' and naming the alternatives, so an agent can tell it apart without opening schemas.

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?

Gives explicit when-to-use (relevé de carrière RIS manquant) and when-not-to (relevé connu → prefer exact), then maps each condition to a named sibling: régime en points → retraite_pension_regime, fonction publique/IEG → retraite_pension_annuites, multi-régimes → retraite_pension_totale. Nothing 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.

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.

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

Annotations already mark the tool read-only and idempotent, so the safety profile is covered. The description adds meaningful behavioral context: the formula, the default no-decote behavior, the 1.25%/quarter decote cap, and the authoritative sources (golden-tested formulas). Slight lack of explicit output-shape detail, but the formula and 'pension brute' imply the result type.

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 and front-loaded, opening with the core formula and coverage, then routing rulesainer. Every sentence carries essential information (scope, exclusions, sources), though the parenthetical lists make it somewhat long. It remains purposeful rather than padded.

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 complex tool with no output schema, the description is complete: it names the covered regimes, gives the formula, explains routing to siblings, identifies the source files, and all parameters are documented in the schema. Missing details like exact return formatting are inferred easily from the highly specific formula and 'pension brute' framing.

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 the baseline is 3. The description adds relational meaning by mapping the formula terms (salaire de référence, trimestres liquidables ÷ requis, décote) directly to parameters)Skip. It also clarifies that salaire_reference is the reference salary/treatment, complementing but not merely repeating the schema descriptions.

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 precise verb+resource: computes the gross pension for a single annuity-based regime, with the exact formula and the list of covered schemes (fonction publique, régimes spéciaux, IEG). It explicitly distinguishes itself from point-based regimes and the CNAV general scheme, making sibling differentiation immediate.

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 says 'À utiliser UNIQUEMENT pour ces régimes en ANNUITÉS' and then names alternatives with exact routing: points-based regimes go to retraite_pension_regime, CNAV to retraite_estimation, and multi-regime totals to retraite_pension_totale via pensions_fournies. This is explicit when/when-not guidance with named sibling tools.

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

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.

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses the computation layer: splitting base/complémentaire, applying the 1% maladie only on the complementary part, the gross-to-net activation via rfr, and the confidence model ('Chaque jambe est vraisemblance-vérifiée ; la confiance globale suit la jambe la plus faible'). It also cites sources for traceability. No contradiction 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 each sentence carries distinct information: purpose, non-point routing, confidence behavior, entry-point warning, and sources. The key warning about double-counting is placed prominently. No filler; structure is coherent, though slightly long.

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 multi-regime pension calculator with no output schema, the description covers input strategy, routing, net calculation, and confidence aggregation. It does not specify the exact output fields (e.g., total_brut vs total_net vs detail), which is a minor gap given the absence of an output schema, but the confidence and non-point handling are explained.

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 semantic context beyond the schema by explaining that pensions_fournies are legs not computed by the tool and are 'additionnées telles quelles, flaggées « fourni »', and that rfr activates the net calculation. This extra context helps the agent understand parameter intent, so a 4 is warranted.

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 specific verb and resource: 'Somme les régimes EN POINTS d'un relevé', and explicitly distinguishes from siblings by calling itself 'Point d'ENTRÉE pour une carrière multi-régimes' and warning against adding results of retraite_pension_regime. This makes the tool's role unmistakable.

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 states the primary use case ('Point d'ENTRÉE pour une carrière multi-régimes'), provides explicit routing for non-point regimes via pensions_fournies and names alternative tools (retraite_pension_annuites for fonction publique, retraite_estimation for CNAV), and includes a direct exclusion: 'ne pas y ajouter ensuite les résultats de retraite_pension_regime'. This gives an agent clear when-to-use and when-not-to guidance.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, and the description does not contradict them. It adds useful behavioral context: the tool computes a fraction of pension, continues acquiring rights, and applies changed eligibility rules after 01/09/2025. This goes beyond what the annotations alone convey.

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 single dense paragraph with the key mechanism and conditions front-loaded. The legal article references and source list add verifiability but also length; the core functional information could be more compact without losing value. Still, no sentence is purely filler.

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 tool with 10 parameters and no output schema, the description covers eligibility, the fraction formula, and statut-specific rules, which is substantial. However, it never explains what the tool returns, how optional parameters like rfr and parts affect the calculation, or how the result should be interpreted. There is enough information for basic use but a noticeable gap remains for a complex legal calculator.

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 80%, so the baseline is 3. The description adds real value by explaining the formula, linking statut to quotité ranges (salarié 40–80%, fonction publique 50–90%, TNS 20–60% via diminution_revenus), and reinforcing the 150-trimestres requirement. However, it does not clarify the role of rfr or parts, which remain opaque.

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 clearly identifies a progressive-retirement calculator—'Retraite progressive (fraction de pension + temps partiel)'—and states the core computation: Fraction = 100% − quotité travaillée. It also distinguishes itself from sibling retirement tools by focusing specifically on the fractional pension with part-time work, though it lacks an explicit imperative verb like 'calcule'.

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 provides meaningful eligibility context: accessible from age 60 since 01/09/2025, requiring 150 trimestres, with statut-specific quotité ranges. However, it does not explicitly tell the agent when to choose this tool over alternatives such as retraite_estimation or retraite_optimisation, leaving the comparison implicit.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds substantial behavioral context beyond that: the 2026 barème with 2024 RFR thresholds, the tranche-selection logic tied to RFR and parts, the conditional 1% maladie on the complementary portion, and the output set. It also cites legal sources (CSS L136-8, L131-2, circulaire CNAV) for verifiability. This is rich, useful behavioral disclosure.

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 purpose ('Prélèvements sociaux sur une pension (brut → net)') is front-loaded, followed by the calculation detail, outputs, version, exclusion, and sources. It is dense but every clause carries information — the legal citations and barème version earn their place for a tax tool with a dated rate table. Slightly long, but justified by the tool's complexity.

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 complex, multi-rate French tax computation with no output schema, the description compensates well by stating the three return values (pension nette, tranche CSG, taux effectif), the applicable barème year, and the RFR reference year. The schema supplies parameter-level fallback behavior (RFR proxy → 'estimée'). Minor gaps remain — no edge-case behavior (e.g., zero pension) — but nothing an agent needs to invoke 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 description coverage is 100%, so the baseline is 3 — the schema already documents rfr (including the proxy/estimation behavior when absent), parts (linear interpolation), montant_complementaire (affected regimes), and pension_annuelle_brute. The description adds genuine value on top by linking the CSG rate tiers to the RFR/parts parameters and explicitly tying the 1% maladie surcharge to montant_complementaire, which the schema's wording implies but does not state as a rate consequence.

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 computation — prélèvements sociaux on a pension (brut → net) — and enumerates the exact components (CSG at 0/3.8/6.6/8.3%, CRDS, CASA, 1% maladie on complementary pension). It states the outputs (pension nette, tranche CSG, taux effectif) and explicitly scopes itself to 'Pensions de retraite uniquement', distinguishing it from fiscal_prelevements_sociaux. An agent can identify this tool 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?

The description gives an explicit when-to-use (retirement pension income) and when-not-to-use ('pour un revenu du capital → fiscal_prelevements_sociaux'), naming the alternative tool directly. This routing guidance is unambiguous and leaves nothing to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description builds on that by adding key constraints: max 12 trimestres, abattement ≤40 for études, stage at 12% PMSS, and the two option modes. It clarifies the deductibility and ROI calculation. It doesn't contradict the annotations and provides useful behavioral context beyond the structured hints.

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 single dense paragraph, but it is well-organized: it starts with the main purpose, then details the computation basis, options, legal limits, and sources. Every sentence carries meaningful information. Though lengthy, the complexity of the domain justifies the size, and it is front-loaded with the core purpose.

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?

Without an output schema, the description names the key outputs (coût, gain, ROI) and covers legal thresholds and sources. It does not specify the exact response structure but gives enough for an agent to know what to expect. Combined with the schema-validated parameters, it is reasonably complete for a tool of this complexity.

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?

The description adds critical parameter context: it explicitly warns that tmi must be a fraction (0-1) and not a percentage (contrasting with the sibling tool fiscal_tmi), explains the two option values, and states the legal maximum trimestres. This goes beyond the schema's terse descriptions and helps the agent avoid common pitfalls.

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 clearly identifies the tool's purpose: computing the cost and profitability of buying retirement quarters (rachat de trimestres). It specifies the legal article (L351-14-1), names the two options (taux seul / taux et durée), and the outputs (coût, gain, ROI). It distinguishes itself from sibling tools like retraite_estimation or retraite_optimisation by focusing on the buyback scenario, making it unambiguous what this tool does.

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 for rachat de trimestres (buyback) but does not explicitly state when to prefer this tool over alternatives such as retraite_estimation or retraite_optimisation. It describes the domain and constraints but lacks explicit 'use this when' or 'use alternative X when' guidance, leaving the agent to infer based on the topic.

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

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

The annotations already mark this read-only and idempotent. On top of that, the description adds useful behavioral context: it returns specific fields, can be filtered by family, and cites the unique source file and the fixed count of 47 caisses. No contradiction 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 compact and front-loaded with the main action, then the returned fields, then the data sources. It contains useful detail without padding, though a few field names like 'machine' and 'étage' remain terse.

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 simple read-only discovery tool with no required parameters and no output schema, the description is sufficient: it enumerates the returned fields, states the source and cardinality, and indicates the optional filter. A more explicit statement of the unfiltered default would be nice, but the schema already marks the parameter optional.

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%: the optional famille parameter is already fully documented in the input schema, including its enum values. The description only repeats 'Filtrable par famille' without adding new semantic meaning, so the baseline of 3 applies.

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 action and resource: it lists the point-based retirement regimes and says it returns them for discovery. It also distinguishes itself from sibling tools by explicitly tying the result set to what is calculable via retraite_pension_regime.

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 'Découverte' label and the phrase 'calculables via retraite_pension_regime' give clear context: this is the discovery/list tool for point-based regimes. It does not explicitly say when not to use it, but the intended role is clear without leaving it to inference.

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

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

Beyond readOnlyHint and idempotentHint, it discloses the exact rate, the cap at 4 quarters/5%, eligibility conditions, and that it handles the LFSS 2026 freeze. It does not describe the return format or behavior when eligibility fails, but annotations already cover safety.

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 front-loaded with the formula and cap, followed by conditions and legal sources. Legal citations add useful authority but slightly lengthen it; still, each sentence contributes significant 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 an 11-parameter tool with no output schema, the description covers formula, eligibility, and LFSS 2026 handling, but it does not specify the return value/format or the role of fiscal parameters such as rfr and parts. Some param semantics are left to the schema, so the description is adequate but not fully complete.

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?

The description gives meaning to key parameters: the 1.25% per quarter in the window maps to trimestres_cotises_fenetre, 'gain en €' relates to pension_brute_annuelle, and the MDA condition ties to mda_parentale and nb_enfants. However, parameters like rfr, parts, age, trimestres_acquis, and trimestres_requis are not explained, leaving a gap at 55% schema coverage.

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 clearly states that the tool computes the 'surcote parentale' pension increase for parents at full-rate one year before legal age, with formula and cap. It does not explicitly contrast itself with sibling retraite_* tools, but the specific term and legal reference make its purpose distinct.

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 provides explicit eligibility conditions: legal age >= 63, required duration reached, and at least one MDA quarter, so an agent can decide when this tool applies. It does not name alternatives or exclusions, but the stated conditions are clear context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the crucial caveat 'Résultat ESTIMÉ' and specifies that hypotheses (rendement/durée) are provided by the caller, and cites the calculation method. This enriches behavioral transparency beyond the annotations without contradiction.

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 front-loaded with the title and purpose, then lists the strategies and outputs. It is a single paragraph with a clear structure, but it includes some redundancy (repeating the title) and could be slightly more concise. Still, every sentence adds value, so it is appropriately sized.

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 absence of an output schema, the description explicitly states what the tool returns: 'Rend l'effort mensuel et le patrimoine/flux de trésorerie à terme de chaque stratégie.' It also notes the estimation nature and the source of assumptions, covering the essential context an agent needs to call it correctly. No missing critical information.

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 parameters are already described. The description adds semantic mapping by naming the three strategies ('tout apporter', 'apport minimal + placement d'un bien secondaire', 'apport minimal + placement financier') which correspond to the nested objects (unique, secondaire, financier). This helps the agent understand which object to populate for each strategy, going beyond the terse schema text.

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 clearly states the tool compares three financing strategies for a real estate project, naming each strategy explicitly. It uses a specific verb 'Compare' and identifies the resource (financing of a real estate project), and it is distinct from sibling tools like simulateurs_scpi or fiscal_*.

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 context: it is for comparing financing options for a real estate project. It does not name alternatives or provide explicit when-not guidance, but the scope is clear enough that an agent would know when to select it among the many simulateurs_* tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds key behavior: no income during démembrement, full ownership recovery at term, usufruct income net of IR and amortization, reliance on Qotien's cIR, and that the result is ESTIMATED. No contradiction 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 a dense single paragraph: it front-loads the purpose, then behavior, routing, and sources. Each clause carries information, but the source list and multiple clauses make it slightly heavier than strictly necessary.

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 7-parameter simulator with no output schema, the description explains the model and inputs but does not describe the shape or units of the projected result, leaving an agent to infer what the tool returns. It also omits edge-case behavior and expected output metrics.

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 the baseline is 3. The description adds model context (nue-propriété vs usufruit, market hypotheses provided by caller) but doesn't add parameter-level semantics beyond what the schema already provides.

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 precise action ('Projette un investissement en nue-propriété de SCPI et l'usufruit correspondant'), identifies the asset class and structure, and differentiates from siblings by explicitly routing full-ownership cash/credit cases to simulateurs_scpi and simulateurs_scpi_credit.

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 gives explicit routing: 'Pleine propriété au comptant → simulateurs_scpi ; à crédit → simulateurs_scpi_credit,' which tells the agent not to use this tool for those cases. It also clearly implies this tool is for démembrement specifically, meeting the when/when-not/alternatives criterion.

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

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

Annotations already establish readOnlyHint=true and idempotentHint=true, so the description's job is lighter. It adds useful behavioral context: the result is ESTIMÉ, it depends on the rétrocession rate supplied by the caller, and it references the legal source (CGI art. 199 undecies B). This goes beyond the annotations without contradicting them.

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 compact and front-loaded with the tool's purpose, followed by output specifics and a caveat. The source citation at the end is a minor extra but provides context for the legal basis; the structure earns a 4 rather than 5 because the title is partly repeated and the long parenthetical run-on could be slightly cleaner.

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?

With no output schema, the description does enumerate the main computed values, which is essential. It also conveys estimation uncertainty and legal grounding. It does not spell out return formatting or edge cases, but for a 6-parameter estimation tool with full schema documentation and safe read-only/idempotent annotations, the coverage is reasonably complete.

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 only modest parameter insight, such as linking revenu_net_imposable to the cIR and noting that the rétrocession rate is caller-supplied, but it does not materially explain individual parameters beyond the schema's own descriptions.

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 'Estime la réduction d'impôt d'un investissement Girardin industriel' and then lists the exact outputs: impôt de référence, montant remboursé, and montant maximal investissable. The tool's specific object — Girardin industriel — distinguishes it clearly from the many fiscal_* and simulateurs_* 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 makes clear when the tool applies: estimating the one-shot tax reduction for a Girardin industriel investment, with the caveat that the result depends on the provided rétrocession rate. It does not explicitly name alternatives or exclusions, but the unique tax niche and the reference to the cIR de Qotien give sufficient context for an agent to route to it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description does not contradict them. It adds valuable context by labeling the result as 'ESTIMÉ' and noting the theoretical schedule and default échéancier, plus the methodology (courbe en J, XIRR). This goes beyond the annotations to set expectations about the nature of the output.

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 single, dense paragraph with no wasted filler, but it repeats the title phrase 'Private Equity — échéancier appels/distributions (courbe en J)' at the start, which is redundant. It is structured with semicolons and flows well, but could be tightened. Overall it is efficient and front-loaded with the key verb and scope.

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 read-only simulator with three well-documented parameters and no output schema, the description covers the essential purpose, the default schedule, the outputs, and the estimation caveat. It does not explain the exact calculation logic or return format, but that is not required given the absence of an output schema. The description is sufficient for an agent to call it correctly.

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 the schema already documents each parameter (multiple, date_debut, montant_initial) clearly. The tool description does not add parameter-specific meaning beyond what the schema provides; it only references outputs, not how inputs map. 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 states a specific verb ('Projette') and a precise resource ('un fonds de Private Equity sur un échéancier type (8 appels de capital puis 10 distributions)'), and lists concrete outputs (total appelé, total distribué, DPI/TVPI, TRI/XIRR). This clearly distinguishes it from sibling tools covering fiscal, retraite, or other simulateurs (SCPI, etc.).

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 by stating it projects a Private Equity fund, so an agent can infer when to use it. However, it does not explicitly mention alternatives or provide when-not-to-use guidance. Among siblings, the context is clear enough for a specialized simulator, but explicit exclusion or alternative naming is absent.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful context by stating 'Résultat ESTIMÉ' and citing the standard financial method (TRI/XIRR vs CAGR) and that assumptions are caller-provided. This goes beyond the annotations and clarifies the nature of the output.

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 about three sentences and front-loads the core purpose. It repeats the title but uses a dash to integrate it. It is efficient and free of fluff, though slightly verbose in explaining the TRI/CAGR distinction. Overall well-structured for quick reading.

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 read-only, idempotent annotations and the 100% parameter schema coverage, the description is mostly complete. It specifies the returned value (true TRI) and the estimation nature. However, it does not describe the exact output format (e.g., whether only a number or an object with additional fields), but for a calculator tool this is a minor gap.

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% (each parameter has a French description). The description adds no parameter-specific details beyond what the schema already provides, such as 'versements programmés' which is implied by the parameter names. Baseline 3 is appropriate because the schema does the heavy lifting.

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 clearly states the verb 'Calcule' and the resource 'rentabilité d'un placement à versements programmés', and explicitly distinguishes the true TRI (weighted by timing) from CAGR. It also specifies the returned value is the true TRI, making the purpose unambiguous and differentiating it from simple CAGR calculations.

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 provides no guidance on when to use this tool versus sibling simulators (e.g., simulateurs_scpi, simulateurs_private_equity). It does not mention alternatives, exclusions, or prerequisites. An agent would have to infer that it applies to general scheduled-payment investments, but no explicit routing is given.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context beyond that: it explicitly states 'Résultat ESTIMÉ' (a quality caveat), notes the life-expectancy bound (60–80), and cites legal/source references (CGI art. 158-6, INSEE table). These enrich the behavioral understanding without contradicting 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 single, dense sentence that front-loads the core purpose and then details the computation steps. Every clause earns its place: it covers inputs, outputs, estimation caveat, and sources without redundancy. The parenthetical source list is compact and useful.

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 read-only estimator with no output schema, the description is complete: it lists all computed outputs (rente brute, part imposable, surcoût d'IR, rente nette mensuelle), states the input scope (age 60–80, capital, fiscal parameters), and flags that results are estimates. It also references the underlying legal/statistical sources, giving an agent confidence in the tool's domain. No critical information 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how parameters feed into the calculation: e.g., 'part imposable selon l'âge d'entrée en jouissance' and 'via le cIR de Qotien' clarify the role of revenu_net_imposable and parts. This extra context helps an agent understand the tax logic, though it does not describe formatting or units for any parameter.

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 precise verb ('Estime') and resource ('rente viagère servie contre l'aliénation d'un capital'), and enumerates the computed components (rente brute, part imposable, surcoût d'IR, rente nette). This clearly distinguishes it from fiscal and retraite siblings, which focus on taxes or pension income rather than annuity estimation.

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 provides no guidance on when to use this tool versus alternatives. It does not mention any sibling tools, conditions for use, or exclusions. An agent would have to infer suitability purely from the tool name and description, which is insufficient for correct routing.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: the result is ESTIMÉ, non garanti, and the hypotheses (rendement, revalorisation, fiscalité) are provided by the caller. It also names the underlying method (actualisation de flux, TRI). This goes beyond the annotations without contradicting them.

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 compact and front-loaded with the core purpose, then lists outputs, then states the estimated nature, then routes to alternatives. The parenthetical source note is slightly extra but useful. No wasted words.

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 read-only projection tool with 100% schema coverage and no output schema, the description covers the purpose, the key outputs, the estimated nature, and the alternatives. It does not describe the exact return shape, but since there is no output schema and the tool is a projection, the description is reasonably complete. A small gap is the lack of detail on how versement_mensuel and reinvest_dividendes interact, but the schema covers their existence.

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 the schema already documents all 8 parameters. The description adds context about the overall hypothesis set (rendement, revalorisation, fiscalité) but does not add per-parameter meaning beyond the schema. 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 states a specific verb ('Projette'), a specific resource ('un investissement en SCPI au comptant'), and the key outputs (valeur brute/nette de revente, revenus distribués, TRI). It also explicitly distinguishes itself from sibling tools simulateurs_scpi_credit and simulateurs_demembrement_scpi, making it easy for an agent to select the right tool.

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 explicitly says when to use this tool (SCPI au comptant) and when not to: 'Achat à crédit → simulateurs_scpi_credit ; nue-propriété ou usufruit → simulateurs_demembrement_scpi.' This is clear routing guidance with named alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds context beyond those: the result is ESTIMÉ based on yield/revaluation/rate hypotheses and interest+insurance are deductibleches. It also names the financial method (tableau d'amortissement, TRI de flux), which helps the agent understand the calculation nature without contradicting 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?

Three compact sentences: the first states the purpose and outputs, the second adds the critical estimation caveat, the third routes to sibling tools and cites sources. No fluff or redundancy; every sentence earns its place and is front-loaded.

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?

The description is complete for an 8-parameter calculator: it names expected outputs (mensualité, effort d'épargne, fonds propres, TRI) even without an output schema, states the estimation nature, and gives usage alternatives. The only minor gap is not explaining what 'fonds propres' or 'effort d'épargne' mean, but that is domain vocabulary an agent would infer from the schema and context.

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% (all 8 parameters have descriptions), so the schema already carries full parametric meaning. The description does not add extra semantics about parameter syntax or relationships; it mentions deductible interest and TRI but does not link them to specific fields. 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 states a specific action ('Projette une SCPI financée à crédit') and lists concrete outputs (mensualité, effort d'épargne, fonds propres, TRI). It distinguishes itself from sibling tools by explicitly naming the cash-purchase and démembrement alternatives, so an agent can tell them apart without opening their schemas.

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 conditional routing: 'Achat au comptant → simulateurs_scpi; nue-propriété ou usufruit → simulateurs_demembrement_scpi.' This is a clear when-to-use vs. when-not-to instruction naming exact alternatives, leaving nothing to inference.

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