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

The description goes well beyond the read-only and idempotent annotations by disclosing that the cap (plafonnement) applies only when both revenu_foyer and autres_impots_annuels are provided, otherwise the IFI is returned uncapped. It also clarifies the stateless nature (no file reading) and cites legal sources. This adds substantial behavioral context that an agent needs to predict the tool's response under different inputs.

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 efficiently organized: it opens with the tax name, then explains the key calculation rules and conditions, notes the stateless behavior, and ends with legal sources. Every sentence contributes to understanding the tool's behavior or constraints, with no redundant repetition of the schema. The front-loaded purpose and structured flow make it easy for an agent to parse.

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 covers the essential calculation logic, including the conditional cap and the debt limitation threshold, and states the stateless nature. It does not explicitly describe the return value (the computed IFI amount), but that is implicit from the purpose and the lack of an output schema. Given the tool's complexity, it would benefit from a brief note on the output format, but overall it provides sufficient context for correct invocation.

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 already has a descriptive comment. The description enriches this by providing the legal framework (articles 974, 977, 979) and the numerical thresholds (1.3M, 800k, 5M), and by explicitly connecting the cap condition to the parameters. It clarifies that patrimoine_immobilier_taxable is before debts and includes specific asset types, reinforcing the schema's definition. This adds meaningful context beyond the basic parameter 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 explicitly states the tool computes 'Impôt sur la fortune immobilière (IFI)' and details the calculation rules (debt limitation, progressive scale, discount, cap), making its purpose unmistakable. It clearly distinguishes itself from sibling fiscal tools that handle other taxes (e.g., CDHR, CEHR, income tax). The specific legal references and thresholds further cement its identity.

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 purpose is so specific that an agent can infer when to use it (any IFI calculation), and the description notes the stateless nature and the condition for the cap. However, it does not explicitly name alternatives or state when not to use it, relying instead on the tool's unique domain. Since the sibling tools are clearly distinct (e.g., fiscal_impot_revenu for income tax), the usage context is clear but not explicitly stated.

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