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 description thoroughly explains both success and failure modes: it details the `found: true` payload structure and the `found: false` response with `lookupStatus: 'not_found'` and a message. It also transparently discusses the `include_freshness` parameter, explaining the difference between `last_success_at` and `last_data_change_at` and how short-circuited runs affect data age. This exceeds the annotations (readOnly, openWorld, idempotent) by describing actual runtime behavior.

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 the description is relatively long, every sentence adds necessary information: main purpose, differentiation, success/failure payloads, source, aliases, and the optional freshness parameter. It is well-organized into clear sections and uses formatting (bold, code spans) to aid readability. There is no redundancy or 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?

The description is self-contained: it explains the tool's scope, the distinction from a sibling tool, the exact response shapes for both success and failure, the data source with legal mention, alias handling, and the optional freshness reporting. Given the complexity of the tool (lookup with status, multiple fields, aliases, freshness option), nothing essential is missing for an agent to use it 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 covers two parameters (`num_finess` and `include_freshness`), both fully described with types, defaults, and examples. Additionally, the description lists accepted aliases for `num_finess`, which adds practical value beyond the schema. The `include_freshness` parameter is explained in depth, including its behavior with `query_metadata`. Schema coverage is 100% and the description enriches it further.

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 details of a Health Centre (CDS) by its FINESS number, and explicitly distinguishes it from the sibling `etablissement_by_finess` by listing the unique fields it exposes (carte_vitale, APCV, specialités CNAM). This makes the tool's purpose unambiguous and differentiated.

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 explicit guidance on when to use this tool versus the alternative: 'Pour les structures non-CDS, utiliser `etablissement_by_finess`.' It also mentions the data source and refresh cadence (weekly CNAM sync), and the latency for very recent CDS, giving clear operational 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 the readOnlyHint annotation, the description details behavioral nuances: coordinates are commune centroids (~3 km average), filters behave as any-of, and the `include_freshness` opt-in explains how data age is computed (short-circuited runs count as success but don't refresh data). 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 long but well-structured with bullet points and clear paragraphs. All content is relevant and serves a purpose; no fluff. Slightly dense but justified given the domain complexity and multiple filters/aliases.

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 (8 parameters, domain-specific codes, sibling tools, data source nuances), the description covers everything an agent needs: purpose, usage, limitations, aliases, data freshness, and coordinate precision. The output schema exists and isn't described, but that's acceptable per the rubric.

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?

Every parameter has a clear description with examples, defaults, ranges, and aliases (e.g., radius/radius_meters → radius_km). Filter semantics are explicitly explained (any-of for specialities, true/false/omitted for carte_vitale, deprecated type codes). Schema coverage is 100% and descriptions add value beyond labels.

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?

Clearly states the tool's purpose: searching for health centers (CDS) within a geographic radius. It explicitly differentiates from the sibling tool `etablissements_finess_in_radius` by highlighting unique fields (carte_vitale, APCV, spécialités) and the source (Annuaire santé Ameli).

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 guidance on when to use this tool instead of alternatives (e.g., when needing carte_vitale/APCV/specialty data vs basic FINESS data), and when not to (no horaires/tarifs/secteur). Also explains coordinate approximation and suggests pivoting via `etab_finess` for precise address.

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?

The description discloses server-side caching behavior, approximate query cost, and read-only nature, which goes beyond the annotations. There is no contradiction with readOnlyHint or destructiveHint.

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, front-loaded with the main purpose, and every sentence carries useful information. The caveats and alert rules are concise despite the domain 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?

The description is complete for a no-input tool: it explains key output fields, defines the alert threshold, notes null behavior, excludes live sources, and mentions cache/cost. An agent has enough context to use the 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?

The tool has zero parameters and the input schema is empty, so parameter-level detail is not needed. The baseline of 4 applies because there are no parameters to describe.

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 that the tool returns the freshness of ingested data dumps, names the exact sources covered, and explicitly distinguishes which live sources are not included. It leaves no doubt about 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 provides explicit when-to-use guidance, including a typical scenario, the correct field to judge on, an alert rule, and a warning against relying on staleness_days alone. It also clarifies that live sources are not covered, preventing misuse.

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 annotations (read-only, idempotent), the description discloses several key behaviors: it only returns active establishments (EN SERVICE), it returns a discriminated union for found/not found, geo_precision is always 'adresse' when coords exist, siret_ans is unverified, and email is always null. This is unusually transparent for a lookup 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 description is concise for the complexity it covers, using a logical flow: purpose, return format, source, field details, notes. Each sentence adds meaningful information without redundancy. The structure with semicolons and bullets (though not actual bullets) keeps it 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 complexity of the tool, the description covers all necessary aspects: input parameters, output shape (including error case), data source and freshness, field semantics (geo_precision, siret_ans), and known limitations (email null). It even points to related tools for verification steps. The description is self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters in the schema have detailed descriptions. num_finess specifies the exact format (9 digits), and include_freshness explains the data_freshness field, including staleness vs data age. The description also explains how the parameters are used in the response, so the agent knows exactly what to pass.

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 action (récupère) and resource (détail complet d'un établissement de santé) and identifies the key parameter (numéro FINESS). It also lists the returned fields, making the purpose unmistakable. While it doesn't explicitly name sibling alternatives, the scope is well-defined by the exact FINESS 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 gives clear context on when to use the tool: when you have an exact FINESS number and need full establishment details. It explains the return shape and edge cases (not found, email null, freshness opt-in), which helps decide if this tool is appropriate. However, it does not explicitly state alternatives for different lookup patterns (e.g., by radius or category), so it's a 4 rather than 5.

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

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

Annotations already declare 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?

Beyond the readOnly/idempotent annotations, the description discloses numerous behavioral details: data source FINESS/ANS with ingestion schedule, only 'EN SERVICE' establishments, geo_precision 'adresse' semantics, siret_ans being unverified, email always null, the principal-category counting lens, and the freshness semantics for include_freshness. No contradiction with annotations exists.

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 carries essential information given the tool's complexity. It is well-structured, starting with the core purpose, then scope distinction, data source, result annotations, lens, and caveats. The front-loaded purpose ensures quick comprehension, and the detail is justified for correct usage.

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 existence of an output schema and the complexity of the tool, the description is complete. It covers return-field semantics (geo_precision, coords, siret_ans, email, perimetre), error cases for ambiguous commune names, data freshness behavior, and distinguishes itself from a large set of sibling tools. No critical usage 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 100% and already detailed. The tool description adds meaningful semantic context, especially for 'categorie' (the principal-category lens) and for interpreting 'nom_commune' ambiguity resolution. However, most parameter explanations are already in the schema, so the added value is moderate, not exhaustive.

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 lists FINESS establishments by family, specifies the resource (établissements FINESS), the verb (liste), and the primary parameter (categorie). It explicitly distinguishes itself from radius-based siblings by stating 'Pas de rayon — pour énumération exhaustive d'une zone administrative', making its scope and use-case 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 guidance on when to use this tool versus alternatives: it explicitly notes the administrative-zone exhaustive enumeration purpose versus radius tools, explains the interpretive lens of principal FINESS category for the 'familles' filter, and warns that 'imagerie' typically returns 0. It also documents the optional freshness parameter and the XOR parameter constraints, giving comprehensive usage 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes beyond by explaining important behaviors: `email` is always null, `geo_precision` is 'adresse' when `coords` exist, `siret_ans` is unverified SIRENE data, and family filters count by main category. 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 front-loaded with the main purpose, but it becomes verbose by repeating the full enum list of 24 family values that already exists in the schema. While each caveat is useful, the enumeration and extended notes inflate length without adding new information beyond the schema. More concise phrasing would improve the score.

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 all important aspects: purpose, parameters, data source, freshness options, field-level notes (geo_precision, siret_ans, email), and practical caveats (category counting, imagerie results). It also references the output field `perimetre` and related verification tools, making it complete for the tool's 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 descriptions cover all 6 parameters (100% coverage). The description adds significant value for `familles` (explains the counting lens and the imagerie exception) and `include_freshness` (details staleness vs. data age), going beyond the schema's basic descriptions to clarify practical semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: searching FINESS health establishments within a geographic radius. It explicitly mentions the geospatial operation (PostGIS ST_DWithin), filterable by families, and distinct from siblings by its geographic scope. The first sentence 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 direct pointers to when to use alternative tools, e.g., 'pour le verdict : reconcilier_finess_sirene / verifier_site_actif'. It also explains limitations that guide usage, such as the 'Lentille' note about category counting and the caveat that 'imagerie' often returns 0 results, helping users decide when this tool is appropriate.

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?

The read-only, idempotent, non-destructive nature is already captured by annotations, and the description adds behavioral details: pagination behavior (`total`, `truncated`, re-call with higher `limit`), the optional `include_freshness` payload semantics, server-side 5-minute caching, and data-source/update cadence. 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 using bullets, bold warnings, and a clear hierarchy: purpose, per-referentiel details, pagination, scope/limitations, and source. Despite its length, every sentence carries necessary guidance for a tool with three distinct code systems and multiple filters.

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 provides all necessary context: the three available nomenclatures, their linkage to sibling filtering tools, pagination semantics, default values, the exact scope (libéraux conventionnés), exclusions, and legal/source attribution. Even without a detailed output schema, the response shape is sufficiently described via `total`, `truncated`, `nb_specialites`, and `data_freshness`.

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 descriptions already cover 100% of the parameters, the tool description adds important semantic context beyond the schema: the meaning of each `referentiel` enum value, the default and max for `limit`, the restriction of `profession_code` to `rpps_savoir_faire`, and the token-saving effect of `include_specialites: false`. This goes well beyond the baseline 3 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 identifies the tool as a discovery endpoint for the server's code nomenclatures, parameterized by `referentiel`, and enumerates the three distinct nomenclatures. It further distinguishes itself from sibling data tools by positioning it as the pre-filter lookup step ('à appeler avant de filtrer un autre tool').

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 (before filtering other tools instead of guessing codes), maps each `referentiel` value to the relevant downstream tools, and warns against cross-referencing codes between nomenclatures. It also defines the exact perimeter (libéraux conventionnés only) and points to the external alternative for excluded populations.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds significant behavioral context beyond annotations: it explains that a single PS may return N entries (one per practice site) with distinct `geo_precision` values, describes the fallback to the live ANS FHIR API, clarifies the `source` field semantics, and details how `include_freshness` affects only `source: 'db'`. This is rich, non-redundant disclosure.

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. It is front-loaded with the core purpose and ID format, then systematically covers multiplicity, geo_precision reliability, fallback behavior, source distinction, and freshness semantics. There is no redundancy or fluff; structure is logical and information-dense.

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 sites, geo_precision levels, live fallback, source differentiation, freshness semantics), the description covers all aspects an agent needs to call it correctly. It explains expected output multiplicity, field meaning, and edge cases (e.g., data age vs last success), and there is an output schema to further document return structure. 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?

Schema coverage is only 50% (one parameter has a schema description). The description compensates fully: it explains the `rpps_id` format (11/12 digits, prefix rules) beyond the schema's pattern, and clarifies that `include_freshness` only affects `source: 'db'`. This adds meaning beyond the structured schema and covers both parameters effectively.

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'), the resource ('la fiche complète d'un PS'), and the identifier (`rpps_id` / IDNPS). It specifies the exact ID format (11 or 12 digits, prefix '81' for post-2020 IDs) and distinguishes this tool from sibling tools by its by-ID lookup scope, making its purpose unambiguous and distinct from radius/name-based searches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use this tool (fetch by national ID) but does not explicitly mention alternatives or exclusions (e.g., 'for name search use rpps_search_by_name'). Since the purpose is highly specific, usage is well implied, yet it stops short of explicit routing among siblings, earning a 4 rather than a 5.

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

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

La description révèle des comportements non évidents : géolocalisation hybride BAN avec ~77 % adresse précise et ~23 % centroïde commune, distance_km identique pour les PS d'une même commune en centroïde, multi-sites renvoyant N entrées par défaut, et application du limit avant déduplication. Elle documente aussi le cache 5 min, la fraîcheur des données via include_freshness et la sémantique précise de data_age_days.

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?

La description est longue mais chaque phrase apporte une information utile : précision géographique, codes, multi-sites, fraîcheur, périmètre, source, licence. La structure avec sections en majuscules, gras et listes rend la lecture efficace malgré la densité.

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?

La description couvre le contexte nécessaire : source (Annuaire santé Ameli), fréquence de mise à jour (hebdomadaire), cadre légal (art. L.1461-2 CSP), limites de précision et comportement des paramètres. Le schéma de sortie étant signalé comme présent, il n'est pas nécessaire de détailler davantage la structure de réponse.

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?

Bien que le schéma couvre déjà 100 % des paramètres, la description ajoute une valeur substantielle : valeurs exactes de type_ps_codes ('1', '2', '5'), mise en garde sur le fourre-tout '2', explication de precise_only, et détail du comportement de dedupe_by_ps et include_freshness. Elle explicite aussi l'interaction entre limit et déduplication, ce que le schéma ne précise pas.

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 commence par un verbe d'action précis (« Recherche de professionnels de santé libéraux conventionnés dans un rayon géographique ») et identifie clairement la ressource : l'annuaire Ameli des libéraux conventionnés. Elle la distingue des outils voisins en précisant le périmètre (libéraux conventionnés, pas tous statuts) et en nommant l'alternative RPPS/Annuaire Santé ANS pour les autres statuts.

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 donne des directives d'utilisation explicites : préférer specialite_codes à type_ps_codes pour cibler une profession, utiliser precise_only=true pour les rayons courts, et dedupe_by_ps=true pour regrouper les multi-sites. Elle indique aussi clairement quand ne pas utiliser l'outil (médecins hospitaliers, salariés, etc.) et renvoie vers l'Annuaire Santé ANS pour les effectifs tous statuts.

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 discloses behavioral details beyond the annotations: pagination via offset when 'truncated=true', deduplication behavior with 'sites[]', freshness semantics with include_freshness and the distinction between last_success_at and last_data_change_at, and cache 5min côté serveur. These do not contradict the readOnly/idempotent 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 yet well-structured, using uppercase labels (PÉRIMÈTRE, HORS PÉRIMÈTRE, Source, Réutilisation) to organize content. Every sentence carries useful information—no filler—and the main purpose is stated first for quick scanning.

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, the description is complete: it covers scope, exclusions, source, legal reuse, pagination, deduplication, freshness, and refers to output fields like 'truncated', 'sites[]', and 'query_metadata'. The output schema exists, so return structure is further defined there.

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% and every parameter has a meaningful description. The tool description adds significant nuance beyond the schema, such as advising to prefer specialite_code over type_ps_code for precise targeting, noting that limit is applied before deduplication, and detailing freshness fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the function: 'Liste des professionnels de santé libéraux conventionnés d'un département, avec filtres optionnels par spécialité ou type de PS.' It distinguishes its scope from sibling tools by explicitly delimiting PÉRIMÈTRE (libéraux conventionnés uniquement) and HORS PÉRIMÈTRE (hospitaliers, salariés, etc.), making it easy to choose over similar tools like professionnels_rpps_par_dept.

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 provides explicit guidance on when to use this tool versus alternatives, e.g., 'PÉRIMÈTRE : libéraux conventionnés UNIQUEMENT... Pour effectifs tous statuts, voir Annuaire Santé ANS (RPPS, esante.gouv.fr) — non couvert par ce serveur.' It also directs users to lister_nomenclature for codes and explains pagination and dedupe options.

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. The description adds crucial behavioral detail: the `geo_precision` field values and their distance semantics, the ~68.5% precise / ~31.5% centroide coverage split, hybrid sorting behavior, opt-in category flags, and the `include_freshness` field behavior (including the short-circuit run nuance). 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: purpose first, then the critical parameter, then geo_precision, coverage, filters, categories, and a nomenclature warning. Each sentence adds necessary information for correct usage; nothing is filler. It could be slightly tightened but the density is justified by the tool's complexity (10 params, nuanced behaviors).

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 this complexity, the description covers all facets: purpose, sibling distinction, parameter semantics, geo_precision behavior, coverage percentages, category opt-ins, nomenclature pitfalls, and the source. The output schema exists, so return values are implicitly documented. 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?

Even though the schema covers 80% of parameters, the description enriches every critical parameter: `precise_only` gets full semantics and a usage threshold, `mode_exercice_codes` lists the exact ANS letter codes, `profession_codes` gives examples, and `include_agents_publics`/`include_etudiants` explain the category breakdown. It also warns against mixing ANS/Ameli codes, which is essential for correct parameter values.

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 clear verb and resource: 'Trouve les PS dans un rayon via RPPS' and immediately distinguishes it from the sibling `professionnels_in_radius` (Ameli) by status coverage. It names the exact source (Annuaire Santé ANS) and scope, making the tool's purpose 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?

It explicitly contrasts with `professionnels_in_radius` for the Ameli-only case, provides a strong recommendation for `precise_only` (short radii, intra-commune ranking) and explains when NOT to rely on `centroide_commune`. It also instructs to use `lister_nomenclature` for code discovery, covering both alternatives and conditions.

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 (read-only, idempotent, open-world), the description discloses several non-obvious behaviors: pagination via truncated flag, geolocation precision semantics (adresse vs etablissement_finess vs centroide_commune), default category (Civil ~97%) and opt-in categories with approximate shares, and the precise semantics of include_freshness (staleness vs data_age, including the short-circuit case). It also warns that passing an Ameli code to an ANS filter returns an empty result without error, which is critical behavioral transparency.

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 contributes necessary information: primary purpose, alternative tool, pagination, geolocation, filters and defaults, code-nomenclature warning, source reference. The structure flows logically from core use to edge cases and warnings. The length is justified by the complexity, and the most important guidance (which tool to use) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters and a complex domain (ANS vs Ameli codes, RPPS categories, freshness semantics), the description covers all necessary aspects: purpose, alternatives, filter semantics, default vs opt-in behavior, output fields (geo_precision, data_freshness), error behavior (empty without error), and source licensing. It is complete enough for an agent to decide when to call it and how to set parameters correctly without needing to open the 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?

The schema descriptions are already good for most parameters, but the description adds essential meaning: the ANS vs Ameli code distinction for profession_code and savoir_faire_code, the geo_precision output field meaning, the default/enum-like behavior of include_agents_publics and include_etudiants (with percentages and categories), and the detailed semantics of include_freshness. This goes well beyond what the schema alone provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb ('Liste') and resource ('tous les PS d'un département via RPPS'), explicitly including libéraux and salariés. It also names the closest sibling alternative (professionnels_par_specialite_dept) and the condition under which that alternative should be used, making the tool's purpose distinct 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 explicitly states when NOT to use this tool ('Pour les libéraux conventionnés uniquement, préférer professionnels_par_specialite_dept') and provides concrete pagination guidance (re-paginer via offset tant que truncated=true). It also gives detailed usage warnings about ANS vs Ameli code mismatches and points to lister_nomenclature for discovering valid codes.

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?

The description aligns with readOnlyHint and idempotentHint, and adds operational details such as the default category (Civil), coverage percentages, server-side caching, and the behavior of include_freshness (including the distinction between last_success_at and last_data_change_at). 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 dense but well-structured, with paragraphs addressing scope, output behavior, categories, and freshness. Every sentence adds meaningful 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?

It covers the input, output (including null fields for spatial data), category defaults, opt-in behavior, freshness metadata, source, license, and reference URL. It also points to an alternative tool for geolocation, making the description self-sufficient for an agent.

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 only 20%, the description thoroughly explains the key parameters: num_finess (9 digits), include_agents_publics, include_etudiants, and include_freshness (with detailed semantics). It compensates for the lack of schema descriptions, leaving limit self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool lists health professionals (PS) attached to a FINESS establishment, answering the question 'who works in this lab/hospital/clinic?'. It distinguishes itself from spatial and specialty-based sibling tools by emphasizing the establishment-centric scope.

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 explains when to use it (by establishment) and when not to (for geolocation, directing to etablissement_by_finess). It also describes opt-in flags for including public agents and students, and defaults, giving clear decision criteria.

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, open-world, idempotent, non-destructive behavior. The description adds meaningful behavioral details such as default category distribution, opt-in categories, trigram matching, truncation, and freshness opt-in 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?

The description is long but well-structured and information-dense. Each paragraph covers a distinct aspect (matching, sorting, truncation, geo precision, categories, source/licence). No redundant sentences; the length is justified by 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?

The description explains the main output aspects relevant to callers: match_score, geo_precision, truncated, data_freshness, and default/opt-in categories. Combined with the input schema, this gives enough context to use the tool correctly, though a full output schema is not provided.

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%, but the description fills the gaps: include_agents_publics and include_etudiants are explained in detail, and departement format edge cases ('2A', '2B', DOM/COM) are documented. All seven parameters are effectively covered.

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 that the tool finds a health professional (PS) by identity, and gives a concrete usage example. This distinguishes it from sibling tools that search by radius, specialty, or establishment.

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 usage guidance: nom is required, prenom and departement refine results, homonyms should be filtered by department or first name, and optional category flags are explained. It does not explicitly contrast with alternative tools, but the usage conditions are otherwise explicit.

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.