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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the 5-credit cost, the fact that counts include all buildings rather than only DVF-transacted ones, and the nested structure of par_usage where 'residentiel' double-counts the collectif/individuel sub-keys. It stops short of error or ambiguity behavior (e.g. what a non-unique commune name returns).

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, then the compatibility note, then grouped parameter guidance, then a worked example — every block answers a distinct question. The bulleted location options and the compact JSON example carry dense information without filler prose.

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 correctly supplies a representative return payload plus the par_usage key semantics, and it discloses cost and the DVF-independence of the counts. The remaining gaps — handling of ambiguous commune names, whether code_postal is accepted as a locator, and unit of 'pct_vieux' baseline — are minor for a read-only aggregate lookup.

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 earns above that by ranking code_commune_insee as most precise and explaining why ('no ambiguity between same-name communes') and by imposing an at-least-one-location constraint the schema does not encode (required is empty). It omits code_postal entirely from the location list even though it is a valid schema parameter, leaving one documented input without narrative guidance.

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 ('Get aggregate building stock characteristics ... from the BDNB national database') and immediately scopes it: 'Counts ALL buildings (not just those with DVF transactions).' That clause distinguishes it from the transaction-based siblings such as search_property_transactions, so an agent can pick it 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 a clear prerequisite ('REQUIRED: at least one location') and a ranked preference among the location parameters, which is real usage guidance. It does not, however, name an alternative tool or state when to prefer a sibling (e.g. get_building_characteristics for a single building, score_renovation_potential for the derived indicator), so the when-not side is left implicit.

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