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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description adds genuinely new behavior beyond that — the legal-entity-only restriction and the fact that a code_insee query returns the top 3 fiches rather than all matches. It does not mention rate limits or pagination behavior, but the added eligibility and result-count context is substantive.

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 dense sentences with the purpose, the output payload, the input forms and the audience restriction front-loaded; no filler. The colon-separated enumeration keeps it compact given the amount of information carried.

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 output schema means return values need not be spelled out, and the description does name the primary inputs. For a 16-parameter tool with two operating modes (fiche vs dents_creuses) and geo-search options, the description leaves mode selection and most tuning parameters unexplained, which is a real gap 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?

With 16 parameters and only 44% schema description coverage, the description compensates for a few key ones (code_insee, section, numero_parcelle, adresse) and clarifies the '3 best fiches' result semantics. It says nothing about mode's two values, limite, curseur, lat/lon, rayon_m, or the several surface/emprise tuning parameters, so roughly half the surface remains undocumented in both places.

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 and resource ('Trouver les parcelles sous-exploitées') and enumerates the outputs it returns (emprise vs PLU, logements en hypothèse, rang, verdict), so the agent knows what it gets. It does not explicitly distinguish itself from the sibling toise_parcelles, leaving that differentiation to 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?

Two input paths are described (code_insee returning '3 meilleures fiches', or a single parcel via section + numero_parcelle / adresse), which implies when each is appropriate, and 'Personnes morales seulement' is a useful eligibility constraint. However, no sibling tool is named and there are no explicit when-not-to-use exclusions.

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