Parcellaire — cadastre, DVF & DPE

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

Annotations already cover the read-only, idempotent, non-destructive behavior, so the description does not need to restate that. It adds meaningful behavioral detail beyond annotations: the estimate is based on recent DVF transactions and a national statistical model, returns a price range, and includes explanatory factors. This helps the agent understand the nature and limitations of the result without claiming precision.

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 two compact sentences that front-load the purpose, then present the two localization alternatives, then enumerate the return contents. Every clause adds information; there is no tautology or restatement of the title.

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?

There is no output schema, so the description usefully enumerates the returned items: total price, range, price per m², and explanatory factors. It also explains the data source and the main input alternatives. It does not discuss what happens if both address and lat/lng are supplied, but given the schema and annotations, the description is sufficient for correct invocation in most cases.

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 description coverage is 78%, so most parameters are already documented in the schema. The description adds critical non-schema semantics by encoding the exclusive localization modes: address OR lat + lng + code_insee. This constraint is not expressed in the JSON Schema and is essential for making a valid call.

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 opens with a specific verb ('Estime') and a precisely defined resource: the sale price of a house or apartment in France. It names the data sources (recent DVF transactions, national statistical model) and distinguishes itself from siblings like search_ventes_dvf by estimating rather than returning raw transaction data. The stated outputs (total price, range, price per m², explanatory factors) make the tool's role unmistakable.

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 description gives clear usage context: use it to get a property price estimate rather than transaction listings. It also spells out the two accepted localization modes (address or lat + lng + code_insee). It does not explicitly name sibling alternatives or exclusion conditions, but the contrast with the sibling set is clear enough for an agent to select this tool correctly.

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

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

Annotations already communicate readOnly, idempotent, and non-destructive behavior. The description adds the geocoding source (Base Adresse Nationale), the return of one or more parcels with IDU, and the follow-up call to get_parcelle, which is useful behavioral context beyond the annotations. It does not say how ambiguity or no-match geocoding is handled.

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 short sentences carry the entire message: purpose, output and downstream use, and input guidance. There is no filler and the most important information is front-loaded.

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?

For a one-parameter, read-only tool with rich annotations, the description covers the input format, expected output (parcels with IDU), and the next tool in the chain. It omits explicit failure or empty-result behavior, but that is a minor gap for such a simple tool.

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?

The schema fully documents the single 'address' parameter with an example, so the baseline is 3. The description adds value by recommending the most complete address format (numéro, rue, commune), which improves geocoding precision.

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 gives a specific action and resource: geocode a French postal address with the Base Adresse Nationale and return the corresponding cadastral parcels with their IDU. It is clear and distinct from get_parcelle because it points to get_parcelle as a later step, but it does not explicitly contrast itself with sibling tools like find_parcelles_by_criteria or search_parcelles.

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?

It establishes a clear use case: an agent with a postal address should call this tool to obtain cadastral parcels and the IDU. It also instructs the caller to provide the most complete address possible (numéro, rue, commune). It lacks explicit when-not-to-use or alternative routing, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds value by disclosing the return cap ('jusqu'à 10 candidates triées par score') and the precision scaling with DPE criteria. This goes beyond what annotations alone provide, covering key behavioral aspects like output limit and result ordering.

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 three sentences, each adding value: the main purpose, the equivalence to geolocate_listing, and the precision/return behavior. It is front-loaded with the core action. While compact, it is slightly dense but does not waste words. The structured flow makes it easy 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?

With 11 optional parameters and no output schema, the description gives essential context: returns up to 10 candidates sorted by score. It also hints at the source data (DPE/DVF). However, it does not describe the structure of each candidate parcel (e.g., identifiers, fields), nor error conditions. Given the complexity, this is a notable gap; an agent might not know what to do with the 'candidates' output without further detail.

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 description coverage is low (45%), so the description must compensate. It lists categories of criteria (commune, surface, classe et consommation DPE, GES, date, année de construction, terrain) but does not map them to exact parameter names or formats. It does mention that more DPE criteria (consumption, GES, date) improve precision, giving some semantic context. However, it leaves many parameters (e.g., type_bien, classe_ges, anne_construction) unexplained, so the compensation is partial.

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 clearly states the verb 'Identifie' and the resource 'parcelles candidates d'un bien immobilier'. It explains the input is property characteristics from an ad, and it cross-references DPE and DVF data. It differentiates from siblings like geolocate_listing by noting it's equivalent without URL or quota, and implies a distinction from address-based search tools.

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 description provides usage context: when you have property characteristics (commune, surface, DPE, etc.) and want to find candidate parcels. It explicitly notes it's an alternative to geolocate_listing without URL/quota. However, it does not contrast with find_parcelles_by_address or search_parcelles, so the when-not-to-use guidance is incomplete. Still, the intended scenario is clear.

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

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

The annotations already mark the tool as read-only and idempotent, and the description adds valuable behavioral context beyond that: the global rate limit of 10 analyses per hour, the specific 429 error, and explicit guidance not to retry immediately. This is exactly the kind of operational disclosure that helps an agent avoid failure.

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 compact and front-loaded: the first sentence establishes the action and expected output, and the second delivers essential rate-limit and retry guidance. Every clause earns its place, with no filler or repetition of the schema.

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 explains the full workflow and the nature of the result (extracted characteristics and candidate cadastral parcels), which is adequate given that no output schema exists. It could be more precise about the exact return structure, but the rate-limit warning and supported portal context make it sufficiently complete for a single-parameter, read-only tool.

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?

The schema already fully documents the single required 'url' parameter with 100% coverage. The description adds extra meaning by enumerating accepted sources (SeLoger, PAP, Bien'ici, Le Figaro Immobilier) and implying that the URL must be complete, which goes beyond the schema's terse 'URL complète de l'annonce immobilière'.

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 names a specific verb and resource: it analyzes a French real-estate listing URL, extracts property characteristics, and identifies candidate cadastral parcels by cross-referencing the DPE database. This clearly distinguishes it from sibling tools that work from an address or criteria, since it is URL-driven and includes a multi-step pipeline.

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 use case is clear: this tool should be used when the agent has a full URL from a recognized French listing portal. It does not explicitly name alternative sibling tools or state when not to use them, but the URL-based input and listed portals make the intended context unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds the behavioral nuance that insee_id is 'fiable' (reliable) and that commune can be name or postal code, which is useful context. It does not disclose any rate limits, error conditions, or output format, but given the annotations, this is acceptable.

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 two sentences with no filler. The core purpose is front-loaded, and the identification instructions are compact. Every sentence adds value.

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 lists a wide range of returned statistics, which gives the agent a good idea of what to expect. Parameters are clearly explained. It does not mention edge cases like ambiguous commune names or empty results, but for a stats endpoint this is likely sufficient.

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% with descriptions for both parameters. The description restates the parameter usage but adds a small value hint ('fiable' for insee_id) beyond the schema's 'prioritaire si fourni'. This is a minor addition, so baseline 3 is appropriate.

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 states a specific verb ('Retourne') and resource ('statistiques d'une commune française'), listing concrete data types (parcelles, bâtiments, prix au m², volumes DVF, DPE, etc.). This clearly distinguishes it from sibling tools that handle individual properties, DPE queries, or searches.

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 description clearly implies this is for commune-level aggregate statistics and explains how to identify the commune (by insee_id or name/postal code). However, it does not explicitly mention when not to use it or name alternative tools for specific sub-queries, so guidance is strong but not exhaustive.

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

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

Les annotations couvrent déjà readOnlyHint et idempotentHint, et la description est cohérente. Elle ajoute une information comportementale clé : l'estimation de prix n'est retournée que 'quand elle est possible', ce qui gère l'attente de l'agent. Aucune contradiction avec les annotations.

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?

Une phrase unique, dense, sans informations superflues. L'action, l'entrée, la provenance et la sortie sont toutes présentes et bien ordonnées.

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?

Pas de output schema, donc la description doit lister les champs retournés, ce qu'elle fait (classe, GES, surface, type, localisation, prix conditionnel). Elle ne détaille pas les types ou unités, mais pour un outil de résumé simple avec un seul paramètre, c'est suffisant. L'absence de gestion explicite d'erreur (numéro invalide) est mineure.

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?

Le schéma couvre 100% du paramètre (description et exemple). La description ajoute la longueur exacte (13 caractères) et la localisation du numéro sur les documents immobiliers, ce qui enrichit la sémantique au-delà du schéma.

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?

Énonce un verbe spécifique ('Retourne'), un objet précis ('résumé d'un DPE') et le critère d'entrée (numéro ADEME), avec une liste détaillée des données retournées. La distinction avec le sibling 'search_dpe' est implicite via la mention 'à partir de son numéro', ce qui rend l'outil immédiatement identifiable.

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?

La description précise le contexte d'usage : nécessite un numéro ADEME de 13 caractères, trouvé sur les annonces et diagnostics. Elle n'explicite pas le cas où l'on n'a pas le numéro (préférer search_dpe), mais le contexte est suffisant pour décider que cet outil est à utiliser avec un identifiant déjà connu.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it enumerates the returned sections (surface, address, adjacent parcels with details) and explains that the 'include' parameter controls which optional datasets are returned.

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 a single sentence that front-loads the core action and then compactly lists the include options. The list is partly redundant with the schema enum, but it serves as a useful quick summary; splitting it into shorter sentences would improve readability.

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?

For a read-only lookup tool with three parameters and no output schema, the description is sufficiently complete: it specifies the required IDU, the optional include sections, and the main output categories. It does not describe output formatting, but the schema covers parameters and annotations cover side effects.

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 description coverage is 100%, so the schema already documents all three parameters. The description adds context for parcelle_id and lists the include options, but it adds no additional meaning for max_items beyond what the schema provides.

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 states a specific verb ('Retourne') and resource ('une parcelle cadastrale') and identifies the exact lookup key (IDU). This makes the tool's scope clear and distinguishes it from sibling search tools like search_parcelles or find_parcelles_by_address.

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 description implies the tool is for retrieving a single parcel's details when the IDU is already known, but it does not explicitly state when to prefer it over alternatives such as search_parcelles or get_parcelle_context. No exclusions or alternative routing are provided.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable context beyond annotations: data comes from public sources and, critically, no environment data is returned unless at least one section is set to true. No contradiction with annotations.

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?

Two sentences, with the purpose front-loaded and the key usage warning immediately after. Every sentence earns its place with no filler.

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?

For a 13-parameter tool with 100% schema coverage and rich annotations, the description covers the core purpose, the input constraint, and the critical all-false behavior. It does not describe the output shape, but no output schema exists and the invocation path is clear.

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?

The schema fully documents all 13 parameters, so the baseline is 3. The description adds meaning beyond the schema by instructing the agent to set only useful sections to true and by clarifying the empty-result behavior when none are set.

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 clearly states the action ('Retourne'), the resource ('l'environnement d'une parcelle cadastrale'), and the required IDU format. It is specific enough to separate environment data from basic parcel lookup, though it does not explicitly name a sibling tool as the alternative.

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?

It gives explicit operational guidance for the boolean sections ('Passer à true uniquement les sections utiles') and warns that an all-false call returns nothing. However, it does not say when to prefer this tool over siblings such as get_parcelle or search_parcelles.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety. It adds value by disclosing that the cadastre URL is returned 'quand elle existe' (when it exists), a conditional behavior, and by stating the precedence ('use first'). This enriches the agent's understanding beyond the annotations.

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 two sentences, front-loaded with the action and input, and every phrase earns its place. It includes the return fields, the conditional URL, and the usage context with zero fluff.

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?

For a simple one-parameter search tool with no output schema, the description covers the input method, the output fields, and the usage context. It does not mention potential multiple matches or error handling, but given the tool's simplicity and the annotations covering safety, it is sufficiently complete for an agent to invoke correctly.

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 description coverage is 100%, and the schema already describes the 'query' parameter with an example. The description reiterates 'par nom ou code postal' but does not add new syntax or format details beyond the schema. Per the rubric, baseline 3 is appropriate when the schema fully documents parameters and the description provides no extra semantics.

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 clearly states a specific verb ('Recherche'), the resource ('commune française'), and the input method ('par nom ou code postal'). It also lists the output (INSEE code, coordinates, cadastre URL) and explicitly differentiates it from siblings by noting that the INSEE code is required for get_commune_stats. This is a precise, non-tautological purpose.

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 description includes explicit guidance: 'À utiliser en premier quand on ne connaît que le nom d'une ville' (use first when only the name is known). It also implicitly advises that the returned INSEE code feeds into get_commune_stats, indicating a typical workflow. However, it does not explicitly mention when not to use it (e.g., if the INSEE code is already known), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context: results are sorted newest to oldest, paginated with limit/offset, and the 'address' mode returns exact matches. It doesn't mention rate limits or response format, but the annotations cover the main safety aspects.

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 concise and well-structured: it states the core function, lists filters, highlights special behavior for 'address', and mentions sorting and pagination. Every sentence adds value without redundancy.

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?

For a read-only search tool with 17 parameters and no output schema, the description covers the main usage modes, filters, sorting, and pagination. It doesn't explain the response structure (since no output schema exists), but the description is sufficient for an agent to invoke the tool correctly. Minor gaps: no mention of how to combine parameters or what happens with conflicting modes (e.g., address vs commune).

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 description coverage is 59%, so the description partially compensates. It explains the meaning of key parameters (address, commune, rayon_m, type_batiment, date_dpe_min/max) and adds context like 'immeuble' meaning whole building DPE. However, some parameters like surface_min_m2, surface_max_m2, annee_construction_min/max, offset, classe_dpe, classe_ges lack description-level detail, though their names are fairly self-explanatory.

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 clearly states the tool's purpose: listing DPE diagnostics in a zone, with specific search modes (address, parcel, point with radius, commune) and filters. It distinguishes itself from sibling tools like get_dpe (which likely retrieves a single DPE) by emphasizing the zone-based search and listing behavior.

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 description explains the different search modes (address, parcel, point, commune) and notes that 'commune' ignores 'rayon_m', and that 'address' returns exact matches. However, it doesn't explicitly state when to prefer this over siblings like search_parcelles or get_dpe, nor does it mention exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description is consistent with a pure read operation — no contradiction. The description adds genuinely useful behavioral context beyond annotations: pagination mechanics (nb_parcelles is total, only 'limit' rows detailed), the zone-too-large aggregation fallback by commune, and the viewport height constraint (≤20 km for parcel-level detail).

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 a single well-structured paragraph, front-loaded with purpose, then zone selection, filter semantics, return value, pagination, and edge case. It is moderately long but every clause earns its place given the 24-parameter complexity and the absence of an output schema. Slightly dense but not wasteful.

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 compensates by specifying return values (total count, a page of detailed results, interactive map link) and documenting the critical pagination fields (limit, offset, pagination.has_more, pagination.next_offset). It also handles the over-large-zone edge case. For a 24-parameter read tool with no output schema, this is fairly complete, though it could name the result record fields.

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 description coverage is 100% and the schema itself is exceptionally rich (exact/range/min/max formats, quasi-exact integer rounding guidance, no-array warnings for surface_parcelle_m2). The description adds the zone-selection logic and the global filter semantics (empty/null = no filter), but per-parameter meaning is already fully carried by the schema, so baseline 3 is appropriate.

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 states a precise verb+resource ('Recherche des parcelles cadastrales dans une zone') and enumerates the filter dimensions (surfaces, DPE, ventes DVF, année de construction, piscines, permis de construire, copropriétés, propriétaires personnes morales). This clearly differentiates it from siblings like search_dpe (DPE data), search_ventes_dvf (sales), and find_parcelles_by_address (address lookup) — this one is the multi-criteria spatial search.

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?

Provides explicit usage context: how to define the zone (commune/departement/region OR viewport), the Region+SIREN special case, the 'omit unused filters; empty/null = no filter' semantic, and a step-by-step pagination workflow (check pagination.has_more, relaunch with next_offset). It does not explicitly route the agent to alternatives among the many sibling search tools, but given the 24-parameter complexity the guidance is strong.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: one row per sale with listed fields, the conditional price-per-m² field when the sale involves a single dwelling, a median price-per-m² summary, and the coverage limitation since 2021. No contradiction with annotations.

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 efficient: five sentences, each adding meaningful information—scope, output shape, summary metric, coverage limitation, and a filtering tip. The main action and use case are front-loaded, with no filler words.

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?

For a read-only search tool with no output schema, the description covers the core answer: row-level fields, median metric, geographic modes, time coverage, and filter guidance. It does not mention pagination or limit/offset behavior, and it omits some filter semantics, but those are partially present in the schema and the description carries most of the decision-relevant context.

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 63%, so the schema already documents a majority of parameters. The description adds practical framing for the main selectors (address, parcelle, rayon, commune) and a useful note about type_bien, but it does not clarify the price, surface, date, or pagination parameters beyond what the schema provides. Helpful but not a full compensation for the remaining undocumented fields.

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 states a specific verb and resource: 'Liste les ventes immobilières (DVF) d'une zone', and immediately enumerates the geographic modes (address, parcelle, point/rayon, whole commune). This clearly distinguishes it from sibling tools like search_dpe, search_parcelles, or estimate_property_price.

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?

It names the intended use case, 'idéal pour trouver des biens comparables', and gives a concrete selection tip: filter by type_bien for comparable price per m². It also states an important exclusion—only geolocalized sales since 2021. It does not explicitly name sibling alternatives, but the guidance is sufficient for an agent to choose this tool.

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