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

Annotations already establish a safe, read-only, idempotent computation, so the bar is lower. The description adds real value beyond them: the legal floor (greater of price and assessed value), the Quebec/NB vs. elsewhere computation model, the covered municipalities, and the disclaimer that the municipality's bill and notary confirm the exact amount, signalling this is an estimate.

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 purpose is front-loaded in the first sentence, followed by the supporting legal detail. It is dense and leans on statutory citations that an agent does not need, but every sentence still contributes to understanding the calculation or its limits.

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 still conveys the computation basis and the caveat that the authoritative amount comes from the municipality/notary. Combined with annotations covering safety, an agent has enough to invoke it correctly, though it never describes the response shape or whether a breakdown is returned.

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 only 20% (only prix is documented), so the description must compensate. It does so partially: province is tied to the legal regime (Quebec/NB vs. elsewhere), municipalite to the 2026 municipal rates for named cities, and adresse to the open roll/assessed value. The lang enum and the accepted province values are never explained.

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 first sentence states a specific verb and resource: compute the land transfer tax ("taxe de bienvenue") for a purchase at a SPECIFIC address. The "SPECIFIC address" scope implies the distinction from the generic sibling taxe_mutation, but it never names that alternative explicitly, so the differentiation is left 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?

"Call this for the land transfer tax on a purchase at a SPECIFIC address" gives a clear triggering condition. However, it never says when NOT to use it (e.g. vs. taxe_mutation for a general estimate) nor names any alternative, so routing guidance is only implied.

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