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

Goes well past the readOnly/non-destructive annotations: discloses a 10-credit cost, that Apartment requests are returned uncharged, that output is aggregate-only with no addresses or owners, and that the 24-month window is anchored to the latest DVF mutation in the commune. It also explains the matching methodology (cadastral section + plan first, conservative address/surface fallback), which tells the agent how much confidence to place in results.

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 the one-line purpose, then splits required/optional parameters into labeled blocks, then methodology, then returns and cost; a reader can stop after the first line or drill down. A few sentences duplicate schema text (the code_insee example, the Appartement behavior) and the methodology paragraph could be tighter, so it is efficient but not maximally lean.

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 carries the return-value burden and does so, enumerating flip rate, median gross margin, median margin percentage, median holding period, and matching-method counts. Cost, scope, geographic anchoring, and privacy limits are all covered; the only nit is that the schema has no required array while the description declares code_insee required, a harmless tightening rather than a 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 coverage is already 100%, so the baseline is 3; the description earns an extra point by explaining the reason behind the Appartement restriction (DVF parcel/address matching cannot separate flats in one building) rather than merely restating the enum. It also clarifies that code_commune is a compatibility alias rather than a DVF raw commune fragment, adding semantics the pattern 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 verb and resource: 'Detects short-hold resales ("flips") in one French commune', then defines the operationally exact criterion (clean DVF sale plus resale of the same house 18-24 months later). An agent can distinguish this from siblings like search_property_transactions or analyze_market_activity 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?

Gives clear operating context: one commune per call, houses only by default, and the explicit note that type_local='Appartement' yields available:false and is not charged, which pre-empts a wasted call. It does not name a sibling tool to use for apartment-level or per-transaction analysis, so alternatives are left implicit rather than routed.

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