france-data-mcp

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by stating that at least one of nom, codePostal, or code is required, which is a key behavioral constraint not fully captured in the input schema (no required parameters).

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 long, front-loaded with purpose and source, then constraints, then aliases. Every sentence adds value with no redundancy or 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?

The description covers purpose, constraints, and aliases well, but with no output schema, it could mention what the tool returns (e.g., a list of communes with basic fields). This omission slightly reduces completeness for a tool with 5 parameters.

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 baseline is 3. The description adds semantic value beyond the schema by providing aliases (e.g., q/query → nom) and explicitly stating the requirement for at least one parameter. The schema also includes examples, but the description's aliases enhance discoverability.

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 searches French communes by name, postal code, or INSEE code, and is ideal for autocomplete. It is specific but does not explicitly differentiate from sibling get_commune_by_code, which might be more appropriate for exact code lookup.

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 minimal usage guidance: it notes the tool is ideal for autocomplete and mentions the data source. However, it does not specify when to use this tool over siblings like get_commune_by_code, nor does it state when not to use it.

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral context beyond those: discriminated LookupResult with found true/false, the exact not_found payload shape, the CNAM weekly sync latency, data source attribution, and the optional freshness metadata behavior. This goes well beyond what annotations alone communicate.

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 well-organized and front-loaded. The core purpose and differentiator appear in the first sentence, followed by structured payload details, edge cases, source attribution, routing advice, and aliases. Every section earns its place and the formatting makes it easy for an agent 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?

Context is complete for a lookup tool. It covers purpose, scope, edge cases, source, freshness behavior, aliases, and explicitly routes the caller to the correct sibling for non-CDS structures. The output schema exists, so the description does not need to re-document the return type, and the found true/false branches are already explained in prose.

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?

Even though the input schema has 100% description coverage, the description adds meaningful parameter semantics: accepted aliases for num_finess ('numFiness'/'finess'/'etab_finess') and a detailed explanation of include_freshness, including what fields it adds, the distinction between last_success_at and last_data_change_at, and the opt-in performance rationale. This is valuable information not fully captured by the schema.

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 and resource: 'Récupère le détail d'un Centre de Santé (CDS) par son numéro FINESS.' It immediately distinguishes itself from the sibling etablissement_by_finess by naming the differentiating fields (carte_vitale, APCV, spécialités), so an agent can unambiguously identify the tool's 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 explicitly states when to use this tool versus the alternative: 'Pour les structures non-CDS, utiliser etablissement_by_finess.' It also explains the edge cases where a valid FINESS number returns not_found, such as non-CDS structures or recent CDS registrations with CNAM latency, giving clear guidance on expected resolution outcomes.

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 readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: data source (Ameli, sync hebefamadaire CNAM), legal mention, coarseness caveat (centroid commune ~3 km mean), match any-of semantics, deprecated type 125, and the note that hour/tarifs were removed post-2025. 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 every section earns its place: source/legal, differentiator, filter semantics, limitation, exclusions, aliases. It is well-structured with clear line breaks, though slightly longer than strictly necessary. Still, no filler or redundancy — a strong 4.

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 an 8-parameter tool nested among 35 siblings, it covers purpose, sibling alternatives, filter behavior, data coarseness, freshness semantics, exclusions, and aliases. Return details are covered by the output schema, so nothing critical is missing.

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%, but the description goes well beyond: it explains that `specialite_codes` matches any-of, that `accepte_carte_vitale=false` is mainly useful for audits, that `type_etab_codes` includes a deprecated CNAM code, and it lists accepted aliases (`radius`, `radius_meters`, `lat`, `lon`). This materially helps agents build correct calls.

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 precise verb+resource+scope: 'Recherche des Centres de Santé (CDS) dans un rayon géographique'. It further differentiates from the sibling `etablissements_finess_in_radius` by listing the exclusive fields (carte_vitale, APCV, spécialités sur place), so an agent can confidently identify what this tool uniquely provides.

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 explicitly names the sibling alternative (`etablissements_finess_in_radius`) and states when this tool is the better choice du to CDS-specific fields. It also routes to `etablissement_by_finess` for precise address-level data and clearly lists exclusions (no hour/tarifs/secteur 1-2). This gives an agent actionable when-to-use versus when-not-to-use guidance.

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 destructiveHint=false, so the tool is known safe. Description adds detailed behavior: returns two addresses, score_dice (with null case), statut with four cases explaining divergence, and handles not_found for non-CDS. No contradictions.

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?

Description is long but well-structured with bullet points for statut cases and clear examples. Could be slightly more concise, but the detail is justified given the tool's complexity.

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?

Given output schema exists and the tool has multiple status cases, description fully explains each statut, score_dice behavior, and the not_found scenario with alternative guidance. Very complete.

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?

Only one parameter num_finess, with schema description covering format. Description adds semantics that the finess must correspond to a CDS, which is not in the schema, enriching understanding.

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?

Description clearly states it compares addresses from CNAM vs FINESS for a given num_finess, and distinguishes itself by noting it is the 'equivalent côté centre de santé de compare_raison_sociale_finess_vs_rpps'.

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?

Explicitly says when to use (signal a move propagated by one source but not the other), provides an example, and states when not to use (non-CDS finess) with an alternative tool (etablissement_by_finess).

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 set readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds detailed behavioral context: it returns two labels and a comparison status, describes the three possible statut values ('exact_match', 'divergent_after_normalization', 'rpps_absent'), and explains the not_found case. No contradictions.

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 well-structured with a clear introductory sentence, bullet-pointed statut explanations, and no redundant text. It could be slightly more concise, but each 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?

Given the presence of an output schema, the description still covers all essential aspects: use case, return format, edge cases (not found), and statut details. It is complete for a simple tool with one parameter.

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 input schema has 100% coverage with a clear description for num_finess ('exact 9-digit number'). The description does not add new parameter information beyond that, but schema coverage is high, so baseline score of 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 clearly states the tool compares 'raison sociale' between FINESS DREES and RPPS/Annuaire Santé ANS for a given num_finess. It uses a specific verb ('compare') and resource, and distinguishes itself from sibling tools like compare_adresse_cnam_vs_finess by focusing on name comparison.

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 explicitly states it is a 'primitive brute SANS interprétation métier' and explains when to use it (e.g., to detect rebranding after M&A). It also clarifies what it does not do (does not indicate acquisitions) and provides alternative context.

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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral detail: the data source (DGFiP DVF actual geolocated sales), that it returns quartiles and volume, the exclusion of commercial properties, and the proxy nature for professional premises. 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 well-structured: first sentence defines main output, then exclusions, then source, then proxy note, then usage caveat. It is slightly long but every sentence adds value. Front-loaded with the core function and key constraints.

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?

Given the tool returns multiple statistics (median, quartiles, volume) and has an output schema, the description sufficiently covers what the tool does, its limitations, source, and appropriate usage. It is complete for an AI agent to select and 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?

The input schema already has 100% description coverage for all parameters (lat, lon, rayon_km). The description does not add new parameter-specific information; it only describes the overall output. Baseline score of 3 is appropriate as the schema does the heavy lifting.

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 returns median residential property price per m², quartiles, sales volume, and period for a given point and radius. It explicitly distinguishes itself by specifying 'RÉSIDENTIEL bâti — maisons + appartements UNIQUEMENT, PAS les locaux commerciaux/professionnels', differentiating from tools that might return commercial prices or other real estate data. The verb 'coût du foncier' plus 'prix médian au m²' is specific and unambiguous.

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 clear context: it is for business case implantation but warns not to integrate into an attractiveness note. It also notes that for professional premises, the residential price is a proxy. However, it does not explicitly mention when to use this tool over siblings like 'dynamique_immobiliere' or others, though the exclusion of commercial properties implicitly guides usage.

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 mark the tool read-only and non-destructive, and the description goes much further: it clarifies the semantic difference between `data_age_days` and `staleness_days`, the meaning of `null`, the 5-minute server cache, and the worst-case SQL cost of 1 SELECT. 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?

Although long, the description is dense and well-structured: purpose first, then source cadences, field definitions, a concrete alert rule, a historical caveat, exclusions, and cache/cost. Every sentence carries operational value and none is redundant.

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 zero-parameter tool, the description fully covers purpose, return-field semantics, the correct metric to judge freshness, the alert threshold rule, cavats from real incidents, excluded sources, and performance characteristics. The output schema exists and the description complements it with rich operational 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?

The tool has zero parameters, so the input schema is trivially fully covered and the baseline is 4. The description adds no parameter docs because none are needed, but compensates by thoroughly documenting the meaning of every returned field.

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 precise verb and object: 'Retourne la fraîcheur des dumps de données ingérés côté serveur', then enumerates the exact data sources and fields returned. This clearly distinguishes the tool from all sibling data-lookup and geospatial tools by framing it as a metadata/freshness query.

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 explicitly states when to call the tool ('avant un audit territorial ou une analyse temporelle'), defines the alert rule, warns against misusing `staleness_days`, and explicitly lists which sources are excluded (LIVE APIs). This gives the agent both positive and negative usage guidance.

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 read-only, idempotent, and non-destructive. The description adds significant behavioral details: no automatic business interpretation, empty results without error if ANS/Ameli codes are confused, default category (Civil), and the source data license. This provides a clear operational 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 long but well-structured with sections for different targets and warnings. It is front-loaded with the core purpose and uses bold for emphasis on critical points. Every sentence adds value given the tool's complexity, though it is not minimal.

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?

Given the tool's complexity (11 parameters, no output schema), the description covers input semantics, constraints, and data sources. However, it does not describe the output structure (e.g., fields in the response, whether it returns density value, population, raw counts). This is a gap as the agent cannot infer the return format from the lack of output schema.

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 82% schema description coverage, the baseline is 3, but the description substantially enriches parameter semantics. It explains conditional logic (code_dept alone vs with nom_commune), unsupported codes for Paris/Marseille/Lyon, aliases for parameter names, and cross-field dependencies (e.g., famille required when cible=etablissements). The description compensates for the remaining 18% undocumented parameters by providing context that the schema lacks.

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 computes health density per 100,000 inhabitants by cross-referencing counts (RPPS or FINESS) with INSEE population data. It distinguishes itself from sibling tools by focusing on aggregation at department or commune level, which is a unique capability among the sibling tools (e.g., professionnels_in_radius returns individual professionals).

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 extensive internal usage guidance (required parameters, conditional semantics, warnings about Paris/Marseille/Lyon and code mismatches) but does not explicitly compare this tool to sibling alternatives. While it implies the tool is for density calculations, it lacks explicit 'when to use this instead of other tools' advice.

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 indicate readOnly, idempotent, non-destructive. The description adds significant behavioral context: the tool never fails for missing commune data, it combines multiple sources, and it mentions coarse permit data in dense areas. This goes beyond annotation information.

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 reasonably concise for its complexity, front-loaded with the main purpose. It could be slightly more structured, but it effectively communicates the tool's functionality without unnecessary verbosity.

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?

Given the tool's complexity (multiple sources, edge cases, two output registers) and the presence of an output schema, the description is very complete. It covers the overall approach, edge cases, and output contents, leaving no major gaps.

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 clear descriptions for all three parameters. The description adds minimal extra detail (e.g., radius used for 'calcul par rayon'), meeting the baseline for high schema coverage.

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: assessing real estate dynamics and growth potential of a zone. It specifies the three official sources combined and the two output registers ('note' and 'info'), distinguishing it from siblings which likely focus on single sources.

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 situational guidance, such as relying on AU zones and land sales in dense cities due to coarse building permit data. It also explains behavior when the commune is not found. However, it lacks explicit 'when not to use' instructions or comparisons to sibling tools.

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, idempotentHint, destructiveHint=false, so safety is clear. The description adds behavioral details: it calls inspect_site (costly, cap at 3), checks M&A signals via entreprise_by_siren, and produces a couverture flag per competitor. However, it does not describe return format or pagination, so slightly less than perfect.

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 well-structured with lists and bold terms. It is informative but not overly verbose; every sentence adds value. A minor improvement could be trimming redundancy (e.g., 'Cap dur') but overall efficient.

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?

Given the tool's complexity (combines multiple internal tools) and no output schema, the description fairly complete. It covers what checks are performed, the cap, error handling, typical inputs, and data sources. Missing explicit output structure, but the couverture flag is mentioned.

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. The description adds context: 'max' default is 3, and 'finess' are typically the top 3 from another tool. It also explains the token cost cap ties to 'max'. This adds meaningful guidance beyond the schema.

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 performs an in-depth investigation of top competitors, specifying what it checks (status, team size, history, M&A, parent group). It distinguishes itself from siblings like inspect_site and entreprise_by_siren by being a composite tool that calls them internally. The verb 'enquête' and the enumeration of checks provide a precise 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?

Explicitly states when to use: 'Typiquement appelé sur concurrents.top[0..2].finess renvoyés par panorama_implantation_complet.' Also provides constraints: hard cap max=3, token cost warning, and error handling (one failing competitor doesn't cancel others). This is excellent guidance.

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 provide readOnlyHint, openWorldHint, etc. The description adds significant behavioral context: return type (LookupResult discriminated), possible etablissements truncation, meaning of enrichmentStatus values, and that 1-2 API calls are made. 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 well-structured with sections for purpose, output format, and warnings. It is somewhat long but every sentence adds value. Could be slightly more concise, but front-loads key info.

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?

Given the output schema exists, the description fully explains the discriminated union (found: true/false), all relevant fields (nombreEtablissements, enrichmentStatus, etc.), and edge cases (not_found, ambiguous, truncation). Comprehensive coverage.

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 describes the single parameter 'siren' as 'SIREN exact, 9 chiffres.' with 100% coverage. The description repeats 'SIREN (9 chiffres)' but adds no extra meaning beyond the schema. 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 clearly states the tool retrieves French company details by SIREN, listing key fields (raison sociale, NAF, finances, dirigeants, établissements) and the data source (DINUM). It distinguishes itself from siblings like 'etablissement_by_siret' (by SIRET) and 'entreprises_in_radius' (exhaustive enumeration).

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 explicitly advises when to use alternatives: 'Pour énumération exhaustive multi-département, utiliser `entreprises_in_radius`'. It also mentions the rate limit (~1 req/s) and recommends reading 'enrichmentStatus' for completeness.

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 (readOnlyHint=true, etc.) are already provided, and the description adds significant context: source (DINUM Recherche Entreprises), what is returned (CA, dirigeants, etc.), the behavior of the two modes, the constraint that proximity mode does not support administrative filters, and the effect of includeDirigeants. No contradictions.

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 well-structured into three paragraphs: general purpose, mode details, and parameter note. It is front-loaded with the main action. While it is fairly long, every sentence adds value and no information is redundant. Slightly more conciseness could be achieved, but it is acceptable.

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?

Given the complexity (10 parameters, two modes, output schema exists), the description covers all necessary aspects: mode exclusivity, parameter combinations, limits (radius 50 km), a specific performance optimization (includeDirigeants), and the data sources. An agent can correctly select and invoke this tool without ambiguity.

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 inline descriptions, so baseline is 3. The description adds value beyond the schema by explaining which parameters belong to which mode, that q and codePostal/departement are exclusive with lat/lon/radiusKm, and the practical use of includeDirigeants for payload reduction. This extra context raises the score.

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 it searches French companies with filters (NAF, postal code, department, geographic radius), specifies the two exclusive modes (proximity and administrative), and lists the data returned (CA, dirigeants, etc.). It distinguishes from siblings like entreprise_by_siren or etablissements_in_radius by focusing on companies and the dual-mode 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?

The description explicitly details two exclusive modes: proximity (lat+lon+radiusKm, optionally naf) and administrative (q and/or naf+codePostal/departement). It states that mixing modes is rejected with an error, provides radius limit (50 km), and explains the payload reduction option (includeDirigeants). This gives clear when-to-use guidance.

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?

Beyond the readOnly/idempotent annotations, the description discloses return-shape details (LookupResult discriminated by found), the not-found payload, DREES lag, abbreviation behavior of raison_sociale, and the always-null email field. These are substantive behavioral disclosures not present in annotations or schema.

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 long but every sentence earns its place: purpose, return behavior, data-lag warning, source, two field caveats, and cross-check advice. It is front-loaded with the core action and structured with clear notes, so an agent can extract the important constraints efficiently.

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 lookup tool with an output schema and rich annotations, the description still adds necessary real-world context: staleness, legal-name truncation, email unavailability, and fallback sources. Nothing needed to call this tool correctly or interpret its output is missing.

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 baseline is 3. The schema already documents num_finess as exact 9 digits and describes include_freshness in detail. The description adds data-quality caveats but not new field-level semantic instructions 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?

Description states a specific action ('Récupère le détail complet') on a specific resource ('établissement de santé par son numéro FINESS'), making its target unmistakable. It also differentiates from sibling tools by identifier type: this is by FINESS, while etablissement_by_siret and entreprise_by_siren are named as alternatives for legal-name lookup.

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 explicitly says when to cross-check (‘structures émergentes... cross-check ARS / Service Public') and names exact alternative tools for legal-name completness (‘entreprise_by_siren / etablissement_by_siret'). It also warns that email is always null, preventing wasted calls for that field.

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 readOnly=true, idempotent=true, non-destructive. Description adds significant behavioral context: the tool queries INSEE V3.11 API, returns a discriminated LookupResult (found true/false with specific fields), describes two not_found scenarios (API key missing, SIRET not found in SIRENE or diffusion partielle), explicitly states no GPS coordinates are returned, and explains rate limiting behavior. No contradictions 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?

Description is detailed with well-structured sections (return format, error cases, sibling distinction, limitations, rate limit). However, it is somewhat verbose (multiple paragraphs); some sentences could be condensed. Front-loaded with purpose and key details, earning a 4.

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?

Given the tool's simplicity (1 param, output schema present, rich annotations), the description covers all essential aspects: return type, error handling, source, limitations (no coords), rate limit, and comparison with sibling tool. No gaps for an AI agent to misunderstand usage.

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 has 100% coverage for the single parameter 'siret' (string, 14 digits). Description reinforces that SIRET must be exact 14 digits and adds context about format expectations. While schema already documents the parameter, the description provides meaningful usage context (exactness) justifying a score above baseline 3.

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 it retrieves details of an establishment by SIRET (14 digits) via the INSEE SIRENE API, listing specific fields returned (e.g., raison sociale, NAF, address, status). It explicitly differentiates from sibling 'entreprise_by_siren' by noting that this tool returns a single establishment site while the sibling returns the legal unit plus its establishments.

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 when-to-use: retrieving details of a specific establishment by SIRET. Contrasts with 'entreprise_by_siren' for legal unit vs. establishment. Advises on detecting closed SIRET still active on FINESS by checking 'actif' and 'dateFermeture'. Notes rate limit (30 req/min) with server-side retry handling. Offers alternative tools for geocoding ('geocode_adresse', 'entreprises_in_radius').

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 and idempotent, and the description adds rich non-obvious behavior: `email` is always null, `raison_sociale` is truncated, category counting uses the principal FINESS category, `imagerie` usually returns 0, and `nom_commune` is resolved via geo.api.gouv.fr. This goes well beyond the annotations and materially helps an agent interpret results correctly.

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 long but dense and front-loaded with purpose before diving into caveats. Each warning, truncation note, resolution behavior, and freshness explanation earns its place for a tool with this complexity; however, the inline list of 24 families partially duplicates the schema enum and adds prose length.

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?

Given the output schema exists, return values need not be explained. The description covers data source, parameter constraints, geo-resolution, XOR semantics, known data quality issues, and even freshness metadata behavior. An agent has enough to select, invoke, and interpret this tool correctly without external information.

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 adds real value by explaining that a `familles` filter counts establishments by principal FINESS category rather than every hosted activity, and warns that `imagerie` typically returns no results. It also clarifies the semantics of combining `nom_commune` with `departement` for disambiguation.

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: listing FINESS establishments by family, with optional department/commune filters. It explicitly distinguishes itself from radius-based tools with 'Pas de rayon — pour énumération exhaustive d'une zone administrative.' This makes the tool's scope immediately clear.

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 tells the agent when this tool is appropriate: exhaustive enumeration of an administrative zone rather than a radius search. It also explains the strict XOR between zone parameters and how `departement` can act as a disambiguation hint, giving practical selection guidance even if it does not explicitly name alternative sibling tools.

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 description goes far beyond the annotations by disclosing key behavioral caveats: email is always null, raison_sociale is truncated, family filtering counts only by principal FINESS category, imagerie typically returns 0, and the source is a local FINESS/DREES dump. These are exactly the non-obvious behaviors an agent needs to interpret results correctly.

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 front-loaded with the main action and the caveats are labeled clearly, but it redundantly lists all 24 family values that already appear in the schema enum. That list adds length without information value, making the overall text less concise than it could be.

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?

Despite high schema and annotation coverage, the description covers the important contextual gaps: data source, legal-name truncation and cross-checking, family-filter semantics, and a known data limitation. With an output schema present, return-value details do not need to be repeated here, so the description is sufficiently complete for an agent to invoke and interpret this 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?

Schema coverage is 100%, so the baseline is 3. The description adds genuine value for the familles parameter by explaining the principal-category lens and the imagerie limitation, which are not inferable from the enum. Other parameters are already well described in the schema.

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 and resource: searching FINESS health establishments within a geographic radius, which clearly distinguishes it from exact-match and by-category siblings. The explicit radius scope and the family-filter concept make the tool's identity unambiguous.

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 establishes a clear use case: radius-based FINESS search with optional family filtering. It mentions a relevant cross-check path to SIREN/SIRET tools for legal names, but it does not explicitly state when to prefer this tool over related siblings such as etablissements_finess_by_categorie, leaving sibling selection partially implicit.

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 declare readOnlyHint=true and destructiveHint=false, matching the description's non-destructive nature. Description adds value by detailing data sources, matching logic, version-specific behavior, and caveats beyond what annotations provide.

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?

Description is detailed but not overly verbose. Every sentence provides useful information (purpose, methodology, version notes). Could be slightly more concise, but front-loading core purpose is effective.

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?

Given 6 params (100% schema coverage) and presence of output schema, the description covers purpose, metric, usage, methodology, caveats, and version behavior. It is contextually complete for a complex 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?

Schema coverage is 100% with clear descriptions. Description adds significant context, especially for familles (auto-derivation, relationship to NAF) and naf (examples). This goes beyond Schema alone.

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?

Description clearly states the tool compares FINESS DREES and SIRENE DINUM coverage in a radius, providing a ratio. It specifies use cases (over/under-declaration) and distinguishes from siblings like etablissements_finess_in_radius by focusing on coverage ratio rather than listing.

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?

Explains when to use (detect discrepancies) and includes methodology, caveats, and parameter guidance (auto-derivation of familles). However, it does not explicitly mention when not to use or list alternative sibling tools.

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 indiquent déjà que l'outil est en lecture seule et idempotent. La description ajoute des informations comportementales importantes : source des données, précision, et signification des champs de sortie (score, confidence_low, type). 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?

Deux phrases concises qui commencent par l'essentiel : l'action principale. Aucun mot superflu, chaque phrase apporte une information utile.

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?

Malgré l'absence de schéma de sortie, la description explique suffisamment le format des résultats (score, confidence_low, type) pour qu'un agent puisse les interpréter. Elle couvre également la source et la précision, ce qui est complet pour un outil de géocodage en lecture seule.

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?

La couverture du schéma est de 100 % : chaque paramètre a une description. La description de l'outil n'ajoute pas d'information supplémentaire sur les paramètres au-delà de ce qui figure déjà dans le schéma. Note de base de 3 justifiée.

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?

La description indique clairement que l'outil géocode une adresse française en coordonnées GPS, précise la source (IGN Géoplateforme) et la précision (numéro de rue). Cela le distingue de son outil frère 'reverse_geocode' qui fait l'inverse.

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 explique comment interpréter les résultats : fiabilité selon le score, champ confidence_low pour les correspondances douteuses, et granularité via le type. Cependant, elle ne donne pas de contexte explicite sur quand utiliser cet outil plutôt que des alternatives comme 'reverse_geocode'.

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, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the discriminated return type and the not_found behavior with a suggestion for alternative tool, but does not contradict 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 very concise with four lines, front-loaded with the core purpose, and each sentence adds necessary information 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?

Given the low complexity, high annotation coverage, and presence of output schema, the description fully covers the return behavior and fallback, leaving no gaps.

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 examples. The description adds alias information (code_insee/codeInsee/insee) that is not in the schema, enhancing understanding beyond the schema definition.

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 'Récupère' and the resource 'commune par son code INSEE'. It distinguishes from sibling 'autocomplete_commune' by mentioning it for disambiguation.

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 explicitly tells the agent what to do when the commune is not found (use autocomplete_commune), providing clear guidance on fallback behavior.

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 indicate read-only and idempotent behavior. The description adds detailed behavioral context: it reads multiple sources, mentions the cross-referencing approach, version details (V0.7.0), and cost breakdown (RPC, SELECT, parallel calls). 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 well-structured with sections for purpose, version details, usage examples, output format, and cost. While slightly long, it front-loads the key purpose and provides valuable context without unnecessary verbosity.

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?

Given that an output schema exists and the input parameter is fully covered, the description provides complete context: explains the output structure (LookupResult with found flag, finess view, siret_timelines), addresses versioning, and mentions cost and lack of caching. The tool's complexity is well-handled.

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 100% schema coverage, the description adds no additional parameter semantics beyond what the schema provides (exact 9-digit FINESS number). The parameter description in the schema is sufficient, so the baseline score of 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 clearly states the tool reconstructs the complete timeline of a healthcare establishment by cross-referencing multiple data sources (FINESS, RPPS, DINUM, INSEE). It distinguishes from sibling tools like 'etablissement_by_finess' by focusing on historical reconstruction rather than just current data.

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 three typical use cases (tracing history after merger/acquisition, identifying exact closure dates, understanding rebranding cascades), which helps identify when to use the tool. However, it does not explicitly contrast with alternatives or state when not to use it.

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, destructiveHint=false, and idempotentHint. The description adds valuable context: it's an aggregator with parallel sub-calls, returns LookupResult with sections, handles truncation for professionals (not count), and describes edge cases (missing FINESS, unavailable historique). No contradictions 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 relatively long but well-structured with sections and bullet points. It includes examples and explicit guidance. While not extremely concise, 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?

Given the tool's complexity (aggregator with multiple sub-calls, optional parameters, edge cases) and the presence of an output schema, the description fully covers return format, failure modes, performance considerations, and aliases. It leaves no critical gaps.

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 baseline is 3. The description adds significant value: explains that rpps_limit is a sample (not total count) with truncated flag, that historique_detail reduces payload by ~7K tokens, and mentions aliases for num_finess. This enhances understanding beyond the schema.

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 explicitly states it provides a '360 view of a health establishment in 1 call' and aggregates four types of data (identification, administrative status, professionals, history). It distinguishes from siblings by noting it replaces three individual tools (verifier_site_actif, rpps_dans_etablissement, historique_etablissement) with a single call.

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 states when to use (prospection, audit territorial, CRM enrichment) and when not (for specific needs like just verdict or history, prefer individual tools). It also provides guidance on payload weight and suggests setting historique_detail=false for batch usage.

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?

Beyond the readOnlyHint/destructiveHint annotations, it discloses silent empty results for mismatched codes, the scoped perimeter with a detailed hors-périmètre list, pagination via total/truncated, and source freshness/legal reuse conditions. This gives an agent a realistic model of failure and scope without invoking the tool.

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 and the critical warning are front-loaded, and the rest is organized into référentiel bullets plus scope/source blocks. It is long, but most sentences carry distinct operational value; a slight redundancy with the scheama's paraméter docs prevents a 5.

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 scheama and three référentiels, the description still covers per-réferentiel response fields, pagination, edge cases (empty/null profession_code, shared libellés), out-of-scope populations, data source, and MAJ cadence. An agent has enough to call it correctly and interpret results without guessing.

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 input scheama already provides detailed descriptions and enum for every paraméter, so the baseline is 3; the description adds cross-réferentiel warnings (e.g. '10' means Médecin vs Neurochirurgien) and payload-size consequences for include_specialites/include_freshness. That extra mapping to downstream parameter names justifies one point above baseline.

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 purpose ('Découverte des nomenclatures de codes du serveur') and positions it as the tool to call before filtering another tool, so an agent knows exactly what it lists and why. The three référentiel branches are individually described with examples, which distinguishes this discovery tool from the many filter siblings.

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 explicitly says when to call it ('à appeler avant de filtrer un autre tool plutôt que deviner les codes') and maps each référentiel to the downstream tools that consume it. It also gives an exclusion: for all-status headcounts, use the external Annuaire Santé ANS because the server only covers libéraux conventionnés.

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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds parallel aggregation, degradation flags ('ok', 'partiel', 'indisponible'), internalized pitfalls (PLM mode for big cities, precise count for prescripteurs), and source references. 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 and well-structured with section list and workflow steps. Minor redundancy (e.g., 'Renvoie des RÉSUMÉS...' restates, but key info). Front-loaded with purpose.

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?

Despite no output schema, the description fully covers return values (summaries, degradation flags), edge cases (partial failure, anchorage failure), and internal logic (parallel execution, pitfalls). Sufficient for an agent to use 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?

All 4 parameters have descriptions in schema (100% coverage). Description adds critical context: XOR relationship between point and adresse, code_insee with point, default rayon_km=5, and behavior when point is used (skip geocoding).

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 it's an 'étude d'implantation labo' that aggregates 7 sections in parallel, replacing 15 individual MCP calls. It lists each section and explicitly distinguishes from sibling tools by being the orchestration entry point.

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?

Explicit workflow: call this tool to start, then handle partial/indisponible sections with unitary tools, then enrich top 3 concurrents. Also specifies when total failure occurs (anchorage failure) and that it returns summaries, not raw lists, and no business interpretation.

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?

Description adds significant behavioral context: returns no business interpretation (no 'désert médical'), granularity mix (commune vs department), PLM cities unsupported, 'demande' block null for DOM communes, and sources/update frequency. Annotations already indicate readonly, idempotent, non-destructive, but description enriches with these details.

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?

Description is long but well-structured: summary first, then version updates, granularity mix, PLM warning, aliases, sources. Could be slightly more concise (version numbers may be unnecessary for agent), but front-loaded purpose.

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?

Given complexity (multiple data sources, mixed granularity, special cases) and no output schema, description covers result blocks (population, densities, FINESS, demande) and null cases, error conditions (PLM, departement alone), and version behavior. It is complete enough for agent to use effectively.

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%, but description adds meaning: 'code_insee' notes PLM unsupported, 'departement' is hint only, 'nom_commune' combinable with departement, no abbreviations, 'finess_familles' explains default and effect of empty array. These details go beyond schema.

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 aggregates multiple data sources into one call for a French commune, replacing 7-10 individual MCP calls. It distinguishes from siblings like 'profil_iris' and 'densite_sante' by providing a holistic overview.

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?

Explicitly states when to use (single commune, replaces many calls) and when not to (Paris/Lyon/Marseille not supported, use individual tools at department level). Also explains parameter usage: 'departement' as hint only, error if used alone; granularity mix warns against confusing commune and department ratios.

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 description goes well beyond annotations by explaining auto-detection of granularity, return type (LookupResult), data sources (INSEE RP 2022, Melodi), and specific behaviors for communes fusionnées, IRIS types, and missing departments. 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 detailed and well-structured with bullet points, but slightly verbose. However, it front-loads the core purpose and uses formatting for 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?

Given the complexity of multiple granularities and edge cases, the description is comprehensive. It covers all scenarios (commune, department, IRIS, special cases like PLM, Mayotte) and references the output schema.

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% for the single parameter 'code', but the description greatly enriches it by explaining length-based auto-detection, providing examples, and detailing the IRIS code structure (e.g., '751103701'). Adds substantial meaning beyond the schema.

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: population lookup for communes, departments, or IRIS by INSEE code. It explicitly names the French administrative levels and distinguishes from sibling tools like 'profil_iris'.

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 when-to-use guidance for population counts at various granularities and when-not-to-use (detailed demographic profiles -> 'profil_iris'). Also warns about edge cases like PLM arrondissements and Mayotte absence.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description adds meaningfully rich behavior: automatic fallback to the live ANS FHIR API, multi-site result behavior (N entries per site), geo_precision semantics with accuracy implications, source field distinction (db vs ans_fhir), and the exact scope of include_freshness. This is far beyond what annotations alone provide and does not contradict them.

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 fairly long but densely informative and front-loaded with the core purpose. Each sentence contributes value (format, multi-site behavior, geo_precision, fallback, source semantics, freshness). It could be slightly tighter, but it is well-structured and readable.

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?

Given the output schema exists and annotations cover the safety/idempotency profile, the description provides nearly everything an agent needs: exact input format, multi-site return semantics, geolocation reliability interpretation, fallback behavior, and source/freshness semantics. No critical invocation detail appears missing.

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 50%, and the description compensates strongly: it explains the rpps_id format (11/12 digits, 81 prefix for post-2020 IDs) beyond the regex pattern, and it adds behavioral context to include_freshness by clarifying it only affects source: db. This gives an agent much more operational meaning than the bare boolean schema.

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 retrieves a complete professional record by national identifier (rpps_id / IDNPS), with precise number-format rules. It distinguishes this exact-ID lookup from sibling tools such as search-by-name or radius-based tools, even though it does not name them explicitly.

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 intended usage is clear: use this tool when you have an RPPS/IDNPS identifier and need the full record. It does not explicitly state when not to use it or point to alternatives like rpps_search_by_name, but the exact-ID scope provides adequate context without exclusions.

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?

Beyond the annotations (readOnly, openWorld, idempotent), the description richly discloses behavioral nuances: ~77% address-level geocoding vs ~23% commune centroid fallback, identical `distance_km` for centroid results, multi-site duplication behavior, `limit` applied before deduplication, freshness semantics, and cache behavior. These are critical operational traits an agent cannot infer from annotations alone.

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 long but appropriately densely packed for a tool with nine parameters and significant geocoding subtleties. It is front-loaded with the core purpose and precision caveat, and uses bolding/caps for key distinctions. Some repetition occurs around precision percentages and `distance_km` semantics, which slightly reduces structural economy, but every major section earns its place.

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 complex geographic-health-data tool, the description covers purpose, perimeter exclusions, paramer semantics, geocoding precision behavior, deduplication, distance semantics, data freshness, source, and legal reuse. The presence of an output schema also means return fields do not need to be re-explained. An agent has enough context to call and interpret this tool 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?

Although schema coverage is 100%, the description substantially enriches parameter meaning: it clarifies that `type_ps_codes` is a catch-all compared to `specialite_codes`, explains the exact semantics and use cases of `precise_only`, details how `dedupe_by_ps` groups multi-site practitioners, and explains the practical interpretation of `include_freshness` fields (`data_age_days` vs `staleness_days`). This goes well beyond the baseline parameter descriptions.

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 identifies a precise verb-resource pair: searching liberal conventioned health professionals within a geographic radius, with the source (Annuaire santé Améli) and perimeter stated up front. It also distinguishes the tool from sibling tools by explicitly excluding hospital-based and salaried professionals and noting that all-status counts are not covered by this server.

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 situational guidance: use `specialite_codes` instead of broad `type_ps_codes` for single professions, use `precise_only=true` for short radii and intra-commune sorting, use external services for road distance, and consult an external source for all-status counts. The PÉRIMÈTRE/HORS PÉRIMÈTRE block also clearly states what this tool is and is not for.

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 readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower, and the description adds meaningful context: data source (Annuaire santé Ameli), weekly refresh, legal reuse constraints, strict perimeter details, and pagination behavior via `truncated=true`. This goes well beyond the structured 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 long but dense and every section earns its place: purpose, filtering guidance, pagination, deduplication, scope, exclusions, alternative sources, and legal constraints. It is front-loaded with the core purpose and organized with clear markers like PÉRIMÈTRE/HORS PÉRIMÈTRE, making it easy to scan.

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 tool with 7 parameters, an output schema, and no enums, the description is complete: it covers scope, exclusions, pagination, deduplication, source freshness, and legal reuse requirements. The output schema handles return-value documentation, so the description does not need to repeat that, and the remaining guidance is sufficient 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?

Schema description coverage is 100%, so baseline is 3. Most parameter guidance in the description repeats what the schema already says, e.g., preferring `specialite_code` over `type_ps_code` and pagination via `offset`. It adds the useful 'fourre-tout' nuance for `type_ps_code`, but this is a marginal increment rather than substantial new parameter 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 states a specific verb and resource: listing liberal health professionals in a department with optional specialty/type filters. It clearly distinguishes itself from radius-based tools with 'Pour énumération administrative — pas de rayon' and gives concrete exclusion boundaries, so an agent can tell what this tool is for.

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 explicit when-to-use and when-not-to-use guidance: administrative enumeration, not geolocation; precise professions should use `specialite_code` rather than `type_ps_code`; hospital-only and salaried professionals are excluded; for all-status counts it points to Annuaire Santé ANS. It also tells the agent to use `lister_nomenclature` for exhaustive codes, which is a concrete routing decision.

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 readOnly, idempotent, openWorld, and non-destructive, and the description adds substantial behavioral context beyond that: `geo_précision` semantics for adresse vs étabissement_finess vs centroïde_commune, coverage percentages (~68.5% precise, ~31.5% centroïde), hybrid-mode merging behavior, and the warning that passing an Ameli code returns empty without error. 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 long but well-structured with bold headers, bullets, and clear separation of concepts. It is front-loaded with the purpose and the critical `precise_only` parameter. A few trailing details (source URL, license, freshness internals) are less essential for invocation, so it is not maximally concise, but every major block earns its place.

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 10-parameter tool with nested objects, output schema, and multiple subtle filtering behaviors, the description is remarkably complete: it covers purpose, alternatives, parameter semantics, geo_precision interpretation, code-nomenclature risks, default vs opt-in categories, and freshness behavior. Nothing an agent needs to call it correctly is missing.

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?

Despite 80% schema coverage, the description significantly extends parameter understanding: it explains `precise_only` semantics and thresholds, gives examples for `profession_codes` ('10' Médecin, '60' Infirmier), details `mode_exercice_codes` values, and clarifies opt-in flags `include_agents_publics` and `include_etudiants` with category percentages. The nomenclature warning about ANS vs Ameli codes is critical and not present in the schema.

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 and resource: 'Trouve les PS dans un rayon via RPPS' and immediately contrasts with `professionnels_in_radius` Ameli = libéraux conventionnés seuls. The scope is fully unambiguous: it covers all statuses (libéraux, salariés, mixtes, remplaçants) via Annuaire Santé ANS.

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 explicitly names the sibling alternative `professionnels_in_radius` and states the distinguishing condition (Ameli = libéraux conventionnés only vs RPPS = all statuses). It also gives concrete usage guidance for `précise_only`: recommended for short radii (<3 km), intra-commune ranking, and 'PS à <500 m', plus a warning not to use centroïde results for individual ranking.

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 readOnly/openWorld/idempotent/non-destructive behavior, but the description adds consequential behavioral details: pagination semantics, `geo_precision` reliability for `coords`, default category composition (~97% Civil), opt-in categories, and the ANS-vs-Ameli code pitfall that silently returns empty results. This goes well beyond what annotations convey.

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 long but each sentence carries a distinct fact: scope, preferred alternative, pagination, geo_precision, filters, category defaults, opt-in behavior, nomenclature warning, and source/license. It's structured with the core purpose and distinguishing alternative front-loaded, and the caveats follow logically. There is 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?

An output schema already exists, so the description doesn't need to document the full return shape, yet it still adds crucial info about `geo_precision`, source, license, and the ANS/Ameli code conflict. The annotations cover safety and idempotency, and the description covers pagination, filters, defaults, and categories. An agent has enough context to call it correctly in the right situation.

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 78% schema coverage, the baseline is 3, and the description adds meaningful extra semantics: it clarifies that `profession_code` and `savoir_faire_code` are ANS codes distinct from Ameli codes, explains the default category behavior, and describes what `include_etudiants` and `include_agents_publics` actually change. It doesn't exhaustively augment every parameter, but it covers the non-obvious and error-prone ones, which is the highest-value contribution.

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 precise verb-object phrase: 'Liste tous les PS d'un département via RPPS (libéraux + salariés).' It explicitly names the sibling `professionnels_par_specialite_dept` as the Ameli-based alternative, which disambiguates the tool immediately. The RPPS source and population scope together separate it cleanly from the other sibling 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 gives explicit routing guidance: for libéraux conventionnés only, it says to prefer `professionnels_par_specialite_dept` instead. It also supplies operational usage conventions, such as re-paginating via `offset` until `truncated=true`, and explains optional filters and opt-in categories. This is model when-to-use-vs-alternatives guidance.

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 indicate safe, idempotent read. Description adds that output is a LookupResult discriminated by 'found', details proxy calculation for revenu_median_pondere, data sources (INSEE RP 2022, FILOSOFI 2021), and coverage limitations (communes ≥5000 hab). No contradiction.

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?

Well-structured with clear separation of modes via bullet points. Slightly long but every sentence adds essential information. Front-loaded with purpose.

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?

Covers all aspects: dual modes, input constraints, output structure (LookupResult), data provenance, coverage caveats, and proxy calculations. No missing context despite complexity.

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 covers 100% with concise descriptions. Description adds behavioral context: lat+lon vs code_iris exclusivity, rayon_km modes, and the meaning of computed fields (e.g., revenu_median_pondere as proxy). Exceeds baseline of 3.

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 it provides demographic profiles at the IRIS (neighborhood) level for location assistance, distinguishing between single-IRIS and basin modes. It contrasts with siblings like 'population' (simple commune/department counts).

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?

Explicitly explains two modes (with/without rayon_km), specifies input constraints (exactly one of point or code_iris), and advises using 'population' for simpler population needs. Covers invalid cases (not_found).

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 description extensively details behavioral traits: algorithm (Sørensen-Dice on bigrams), score computation, verdict thresholds, and output format including the `skipped` field. Annotations already indicate read-only, open-world, idempotent, non-destructive; the description adds value with the internal logic and edge cases.

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 well-structured with clear sections and bullet points, making it easy to read. It is slightly lengthy (four paragraphs) but each part serves a purpose. Some algorithmic details could be condensed, but overall it is efficient.

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?

Given the tool's complexity and the presence of an output schema, the description provides a complete picture: input, algorithm, output format (including handling of null cases like 'not_found' vs empty candidates). Nothing essential is missing.

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 single parameter 'num_finess' is fully described in the schema (9-digit string). The description adds context about how it is used to fetch FINESS data, but does not provide additional semantic constraints beyond the schema. With 100% schema coverage, a score of 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 clearly states the tool's purpose: cross-referencing FINESS and SIRENE data and computing a coherence score for FINESS-SIRET matching. It uses specific verbs ('Croise', 'calcule') and identifies the resource (FINESS, SIRENE). The tool is distinct from siblings, none of which perform this reconciliation.

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 explicitly says the tool is useful 'pour confirmer/infirmer un appariement num_finess ↔ SIRET avant prospection ou cross-check qualité', providing clear context. It does not, however, mention when not to use it or suggest alternative tools, but the specificity is sufficient.

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, openWorldHint, idempotentHint true, and destructiveHint false. Description adds valuable behavioral context: coverage limitation, null return meaning 'no result not error', and data source attribution. No contradictions.

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?

Description is two sentences, concise, and front-loaded with the primary purpose. Every sentence adds value (purpose, source, coverage, special return behavior). No wasted 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?

Given no output schema, description mentions that out-of-zone coordinates return null, which partially addresses return behavior. However, it does not specify the format of the returned address. Still, for a simple tool with good annotations, it is nearly complete.

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?

Input schema has 100% description coverage for both parameters (lat and lon with WGS84). Description does not add additional semantics beyond what the schema provides. Baseline 3 is appropriate since schema already explains parameters.

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?

Description clearly states 'reverse geocoding' and retrieves nearest address from GPS coordinates. Specifies data source (IGN Géoplateforme) and coverage, distinguishing it from sibling tool geocode_adresse which does forward geocoding.

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 clear context on coverage (France métropolitaine + DOM) and behavior for out-of-zone coordinates (returns null). Does not explicitly state when to use versus alternatives, but the tool's purpose is self-evident and no other sibling does reverse geocoding.

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?

Even with readOnlyHint and idempotentHint annotations, the description discloses meaningful behavioral details: `coords` and `distance_km` are null, output is compact, coverage depends on RPPS declarations, and category membership is not uniform across populations. This goes well beyond what the annotations express.

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 every sentence earns its place: purpose, coverage caveats, output nulls, category defaults and opt-ins, reference, and license. The main use case is front-loaded, and the paragraphs are logically organized.

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 tool with five parameters and low schema coverage, the description provides enough context for an agent to call it correctly: required identifier format, output behavior, category filters, coverage limitations, and an alternative for spatial use. The output schema existence covers return-value detail, so no critical operational context is missing.

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 only 20%, but the tool description compensates well for `num_finess`, `include_agents_publics`, and `include_etudiants` by explaining their exact effect and category breakdowns. The one gap is `limit`, which receives no semantic explanation either in the schema or the description.

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 and resource: 'Liste les PS rattachés à un établissement FINESS', clarifying exactly what the tool returns. It also frames the tool as a 'Pivot RPPS↔FINESS' answering 'qui travaille dans ce labo / hôpital / clinique ?', which clearly distinguishes it from spatial or facility-only siblings.

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 a clear question the tool answers and explicitly says that for geolocation the agent should pivot via `etablissement_by_finess` instead. It also explains coverage and opt-in category behavior, though it does not enumerate alternative search tools like `professionnel_by_rpps` or `rpps_search_by_name`.

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 declare readOnly/openWorld/idempotent, and the description goes beyond them by revealing: ordering by match_score with pg_trgm semantics, the homonymy problem when no department is given, the meaning of truncated flag, geo_precision values with physical distance implications, category distribution percentages, and data freshness behavior for include_freshness. This is rich behavioral disclosure that materially changes how an agent should interpret 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?

The description is long but each sentence carries operational weight: search semantics, scoring, truncation, geo-precision, category opt-ins, source and license. Critical facts are front-loaded (what the tool does, the example), with secondary concerns (freshness, license) later. No filler or repetition of schema details.

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 complex search tool with 7 parameters, an output schema, and no enums, the description covers matching behavior, ordering, confidence interpretation, geo-precision, category semantics, freshness opt-in, truncation handling, and source reliability. An agent has everything it needs to decide when to call this tool, which parameters to use, and how to interpret the response, including edge 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 coverage is 71% and the description adds substantial semantic value: it explains the fuzzy matching behavior of nom, the disambiguation role of prenom and departement, the exact format of departement codes including the Corsica and DOM/COM edge cases, and the meaning and trade-offs of include_agents_publics and include_etudiants (percentages, examples, categories). The description fills the gaps left by the two schema parameters that have no description and clarifies the others beyond basic identifiers.

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 concrete verb and resource: finds a health professional (PS) by identity using trigram matching tolerant to accents/typos, with a clear search example. It distinguishes itself from sibling tools like professionnel_by_rpps (lookup by exact RPPS number) and rpps_dans_etablissement (search within an establishment), making it unambiguous what this tool searches for.

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 explicit usage guidance: when to add prenom/departement, why filtering by department is important for common names, what a score <0.5 means, and when to interpret truncation. It also explains the opt-in categories, which is effectively guidance on when to include additional parameters and the trade-offs. No alternative tool is named but the tool-specific search semantics are thoroughly explained.

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 declare readOnlyHint, idempotentHint, destructiveHint false. Description adds cost details (RPC, SELECT, DINUM calls) and explains version-specific fixes and edge cases. No contradiction.

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 well-organized with paragraphs and bullet points, but quite verbose with technical details like version numbers and distances. Could be more concise without losing key information.

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?

Given the complexity (multi-source, two verdicts, output schema), the description covers all important aspects: logic, edge cases (succession, collocation), cost, and output format. Very complete.

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?

Only one parameter 'num_finess' with schema description 'Numéro FINESS exact (9 chiffres).' Description does not add further semantics. Since schema coverage is 100%, baseline is 3.

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 explicitly states it 'Vérifie si un établissement de santé FINESS est encore en activité' and details cross-referencing multiple sources. This distinguishes it from sibling tools like 'etablissement_by_finess' which likely returns general info.

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 extensive logic (lookup steps, two verdicts, handling of successions) but does not explicitly state when to use this tool vs alternatives. The detailed algorithm helps the agent infer correct usage.

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