france-data-mcp

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, fully covering behavioral expectations. The description adds the data source (geo.api.gouv.fr) but no additional behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loaded with the core purpose, and contains no superfluous information. Every word earns its place.

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

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

For a simple search tool with no output schema, the description covers the search dimensions and data source. It does not specify what fields are returned, but the schema provides some hints. Minor gap for a fully self-contained description.

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%, each parameter is described. The description adds no extra meaning beyond summarizing search criteria (nom, code postal, code INSEE). Baseline 3 applies as 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 it searches French communes by name, postal code, or INSEE code, and explicitly says it's ideal for autocompletion. This distinguishes it from sibling tools like get_commune_by_code (exact lookup) or health-professional tools.

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

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

The description says 'Idéal pour autocomplétion' and mentions the boostPopulation parameter for ambiguous names, providing context for use. However, it does not explicitly state when not to use it or compare to alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial value by detailing the return format (discriminated union with 'found' and conditional 'statut'), explaining status values ('exact_match', 'divergent_after_normalization', 'rpps_absent'), and stating the behavior when num_finess is absent from FINESS DREES. This exceeds 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?

The description is well-structured with a clear purpose, usage hint, and bulletized status explanations. It front-loads the main purpose and adds necessary detail without fluff. Slightly verbose but every sentence contributes 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 (comparing two data sources, multiple status conditions, discriminated output), the description covers all essential aspects: what it does, when it's useful, what it returns in each case, and what it avoids. The presence of an output schema (not shown) further complements completeness.

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% (parameter 'num_finess' described as 9-digit exact number). The description does not add new semantic information about the parameter beyond what the schema already provides. 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' from FINESS DREES and RPPS for a given FINESS number. It distinguishes itself from sibling tools like 'etablissement_by_finess' and 'professionnel_by_rpps' by focusing on cross-reference comparison. The verb 'compare' and the specific data sources are explicit.

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 context for usage: it explains that RPPS reflects rebrandings faster than FINESS DREES, and explicitly states that the tool does not interpret the divergence (leaves decision to caller). It also clarifies what the tool does NOT do (e.g., not saying who bought whom). However, it does not mention alternative tools or 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?

Beyond annotations (readOnlyHint, openWorldHint), the description adds cache behavior (5-minute cache), cost (1 SELECT or cache hit), and notes that live sources are excluded. 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 concise but slightly verbose. It lists fields and usage in a single paragraph, which is informative but could be structured more clearly with bullet points. Still 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?

For a tool with no parameters and no output schema provided, the description fully covers the return fields, usage context, and alert thresholds. It compensates for missing output schema details and is complete 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?

No parameters exist (schema coverage 100%). The description does not need to explain parameters, and the baseline score of 4 applies due to zero 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?

The description clearly states the tool returns the freshness of ingested data dumps for specific sources (FINESS DREES, Annuaire Santé Ameli, RPPS/ANS). It lists the returned fields and explicitly excludes live sources, making its purpose distinct from sibling tools.

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

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

Provides typical use cases (before territorial audit or temporal analysis) and gives alert thresholds for staleness per source. However, it does not explicitly contrast with sibling tools or state when not to use it, though the exclusion of live sources implies a boundary.

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, idempotent, safe. The description adds valuable context: data sources (FINESS DREES, INSEE Melodi), year (2023), and cost of compare_national parameter.

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 succinct: one sentence for purpose, one for families, one for why filter is needed, and one for optional parameter. No redundant 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?

For a tool with 3 parameters, no output schema, and comprehensive annotations, the description fully covers what the tool does, why parameters are needed, and behavioral implications like cost.

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

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

Schema coverage is 100%, but the description enriches each parameter: lists all families for 'famille', explains that 'compare_national' adds national density and deviation, and clarifies default behavior without filter.

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 density of health establishments per 100,000 population by FINESS family. It lists families and distinguishes from sibling tool 'densite_professionnels_sante' which focuses on 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?

It explains why a family is required (otherwise ratio meaningless) and describes the optional compare_national parameter. However, it does not explicitly state when to use this vs. the professional density sibling.

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 adds significant behavioral context beyond annotations: it details the DREES methodology, data sources (RPPS, INSEE Melodi), cost in RPC calls, and clarifies it returns no interpretation. Consistent with readOnlyHint, idempotentHint, 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 comprehensive but slightly verbose; however, every sentence adds value. It is front-loaded with purpose and organized logically, though a more structured format (bullets) could improve readability.

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

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

Given the tool's complexity (7 parameters, no output schema), the description is very complete: it explains methodology, sources, cost, caveats (no interpretation), and parameter interactions. It adequately substitutes for missing output schema by describing the result (density, optional national comparison).

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?

Description enriches all parameters with context, default values, examples (e.g., 'SM02' for cardiology), and explanations of categories (include_agents_publics, include_etudiants). For the two parameters missing schema descriptions, the tool text compensates fully.

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 'Densité de professionnels de santé pour 100 000 habitants dans un département', a specific verb+resource. It distinguishes from siblings by focusing on density per department rather than listings or raw 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?

The description gives explicit usage examples (cardiologues, dermatologues, etc.) and instructions for adjusting parameters by profession, specialty, or mode. It references an alternative tool for listing specialties, but does not explicitly state when not to use this tool.

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 indicate readOnlyHint, idempotentHint, and no destruction. The description adds rich behavioral details: enrichment status meanings (success, partial, failed, not_attempted), potential truncation of etablissements, cost of 1-2 API calls, and rate limit of ~1 req/s. 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 and front-loaded with the core purpose. It includes necessary details (return format, enrichment logic, alternatives) but is slightly verbose; however, every sentence adds value, 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 complexity (discriminated union output, enrichment status, edge cases), the description covers all necessary context: return format, possible lookupStatus values, enrichment behavior, alternative tool, and API constraints. The output schema exists but the description adds the discriminated union details, making it 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?

Schema description coverage is 100% with a clear 'SIREN exact, 9 chiffres.' The description repeats the format but adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Récupère le détail d'une entreprise française par son SIREN', specifying the verb and resource. It distinguishes from siblings by explicitly recommending 'entreprises_in_radius' for exhaustive multi-département 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 provides explicit when-to-use (valid SIREN for company details) and when-not-to-use (exhaustive multi-département, use alternative). It also explains edge cases like not_found due to INSEE diffusion and notes rate limits, giving clear context for decision making.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: the API fallback behavior and result limits (25 per NAF in department). 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 concise and well-structured: first sentence states purpose, second adds coverage and source, third explains the critical limitation. Every sentence earns its place; no 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?

Given the tool's complexity (9 parameters, output schema exists), the description covers the main purpose, data source, and a key limitation. Pagination details are implicit (page/perPage), but the output schema provides return structure. Adequately 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?

Schema description coverage is 100%, so baseline is 3. The description adds no additional parameter-level details beyond what the schema provides, but it does give context on NAF codes (e.g., health sectors). This is acceptable but not above baseline.

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

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

The description clearly states the tool searches for French companies with filters (NAF, postal code, department, radius), covering all sectors. It is distinct from sibling tools like professionnels_in_radius or etablissements_finess_in_radius which target health professionals or facilities.

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 usage guidance by detailing a limitation: the combination naf+lat/lon/radiusKm is not supported natively and triggers a fallback with results limited to 25 companies. This informs when to use the tool and its constraints, though no explicit when-to-use or alternatives are stated.

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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral details: returns a LookupResult discriminated by found, explains both found=true and false responses, mentions data freshness opt-in, cache behavior, and the email always null. 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 comprehensive but slightly verbose (e.g., listing all fields). It is well front-loaded with the main action, but could be trimmed slightly without losing clarity. Still, it is well-structured and informative.

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 a lookup with discriminated result, data freshness opt-in, and data latency considerations, the description covers all necessary aspects. The output schema exists, so return values are not over-explained. It provides complete context for an agent 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?

Schema coverage is 100%, but the description adds meaning beyond schema: num_finess is specified as exactly 9 digits, and include_freshness explains payload adjustment and cache behavior. This enriches understanding beyond the schema descriptions.

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

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

The description clearly states it retrieves the complete details of a healthcare establishment by its FINESS number, listing specific fields (social reason, category, address, GPS, phone). It distinguishes from siblings by focusing on a single FINESS number, while sibling tools handle categories or radius 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 implies use when you have a specific FINESS number, but does not explicitly state when to use this tool versus alternatives. It provides caveats about data latency and recommends cross-checking, but lacks direct guidance on when not to use it or comparison with 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?

Description goes beyond annotations (readOnlyHint, etc.) by detailing return format (LookupResult with found true/false cases), error messages (missing API key, not found, diffusion partielle), and behavioral constraints (no GPS coordinates, rate limit).

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 well-structured with clear sections, emoji warnings, and bullet-like formatting. Though lengthy, every sentence adds value; front-loaded with main 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 output schema exists, description explains both cases (found/not found). Covers edge cases (API key missing, diffusion partielle) and provides cross-tool comparison. Fully adequate for context.

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

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

The single parameter 'siret' is fully covered by schema (100% description), and the description adds value by restating '14 chiffres' and reinforcing that it's used for lookup. No additional parameter documentation needed.

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 specifies the verb 'Récupère' and resource 'établissement par son SIRET', lists data fields (raison sociale, NAF, dates, etc.), and distinguishes from sibling 'entreprise_by_siren' by clarifying it returns a single site vs legal unit with list.

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 this tool vs 'entreprise_by_siren' and 'geocode_adresse' for coordinates. Provides guidance on interpreting 'actif: false' for FINESS cases. Also notes rate limit (30 req/min) and server-side handling.

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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds value by noting the 'email' field is always null due to FINESS public limitations and explaining the 'include_freshness' option's caching and overhead. This provides behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences plus a list of categories and notes. Key information is front-loaded (what the tool does and when to use it). The list is necessary but slightly verbose. Overall efficient and well-structured.

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 5 parameters, 24-value enum, optional filters, and a data freshness option, the description covers main usage, limitations, and optional behavior. An output schema exists, so return-value details are not needed. A minor gap: no mention of default ordering or pagination behavior.

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 5 parameters have schema descriptions (100% coverage). The description adds minimal extra meaning, such as listing all enum values (redundant) and explaining the 'include_freshness' parameter's caching behavior. Baseline 3 is appropriate since schema already documents 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?

The description clearly states the tool lists FINESS establishments by category, with optional department/municipality filters. It distinguishes from radius-based tools by explicitly saying 'Pas de rayon — pour énumération exhaustive d'une zone administrative.' This makes the purpose 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 a clear use case: exhaustive enumeration of an administrative area, contrasting with radius-based tools. It lists 24 available categories. However, it does not explicitly mention when to use sibling tools like 'etablissements_finess_in_radius' or 'professionnels_in_radius' as alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful context: the data source (FINESS/DREES), the use of PostGIS ST_DWithin, and the fact that the email field is always null. This goes beyond the annotations, though it does not describe rate limits or cost.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core action. It includes a list of 24 family values, which is necessary for usability but could be slightly trimmed. Overall, every sentence serves a purpose 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 tool's complexity (6 parameters, required output schema) and rich schema descriptions, the description adds meaningful context: data source, null email behavior, and a hint about caching. The output schema exists, so not explaining return values is acceptable. Minor omission: no mention of performance or typical use cases.

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

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

Schema description coverage is 100%, with each parameter well-documented in the schema. The main description lists the 24 family values (also in the schema enum) but does not add new semantics beyond what the schema provides. 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's purpose: searching for FINESS healthcare establishments within a geographic radius using PostGIS. It specifies the resource (établissements FINESS), the action (recherche dans un rayon), and differentiates from sibling tools like etablissement_by_finess (exact ID) and etablissements_finess_by_categorie (category-only).

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

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

The description implies usage for radius-based searches but does not explicitly state when to use this tool vs alternatives or when not to use it. It lists families and mentions the null email field but lacks exclusion criteria or comparative guidance. Sibling tools exist but are not referenced.

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 readOnlyHint=true, idempotentHint=true, openWorldHint=true, et destructiveHint=false. La description ajoute des comportements importants : la méthodologie de calcul, l'inclusion de caveats, et la mention des sources (FINESS DREES + DINUM + SIRENE INSEE). Cependant, elle ne précise pas la gestion des limites (comme le tri des unités légales au-delà du max_unites_legales) ni le format de la réponse. Avec des annotations riches, la description complète bien mais pourrait être plus explicite sur le comportement en cas de limite atteinte.

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 relativement concise (environ 80 mots) et bien structurée : elle commence par l'action principale, puis définit la métrique, les cas d'usage, et mentionne les sources et caveats. Chaque phrase apporte une information utile. Elle pourrait être légèrement raccourcie sans perte d'information, mais elle reste efficace. Pas de répétition ni de contenu superflu.

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?

Le contexte est très complet : la description couvre l'objectif, la métrique, les cas d'usage, la méthodologie, les sources, et les caveats. Un schéma de sortie existe probablement pour documenter la structure de réponse, ce qui allège la description. Compte tenu de la complexité de l'outil (comparaison de deux référentiels), la description fournit toutes les informations nécessaires à un agent pour décider de l'utiliser.

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'informations spécifiques aux paramètres au-delà de ce qui est déjà dans le schéma. Elle mentionne des exemples de codes NAF et les familles, mais cela reste général. Conformément à la règle, avec une couverture >80%, la baseline est 3. La description n'apporte pas de valeur ajoutée significative sur la sémantique des paramètres.

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 l'action : comparer la couverture des référentiels FINESS et SIRENE dans un rayon géographique, avec une métrique précise (ratio sites FINESS/SIRET SIRENE) et les cas d'usage (détection de sur ou sous-déclaration). Elle se distingue efficacement des outils frères comme 'etablissements_finess_in_radius' ou 'entreprises_in_radius' en spécifiant la comparaison inter-référentiel.

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 un contexte d'utilisation clair ('détecter une sur-déclaration FINESS ou une sous-déclaration DREES'), mais ne mentionne pas explicitement quand ne pas utiliser cet outil ni les alternatives parmi les siblings (par ex. 'reconcilier_finess_sirene' qui pourrait être plus adapté pour une réconciliation point par point). Le contexte est suffisant pour un agent, mais une exclusion explicite renforcerait la note.

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 safety, readOnly, idempotent. Description adds context about source data and precision, 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?

Two sentences, no wasted words. Purpose is front-loaded, source and precision follow efficiently.

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

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

Adequate for a simple geocoding tool with 3 params and no output schema. Could mention return format but not critical.

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 descriptions are clear. The description adds only minor context about precision beyond 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?

Clearly states it geocodes a French address to GPS coordinates, with source and precision level. Distinguishes from sibling 'reverse_geocode'.

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?

Describes what it does and source, but does not explicitly state when to use it over alternatives like reverse_geocode or commune 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 provide safety and idempotency hints. The description adds significant behavioral detail about the discriminated return type (found vs not_found) and the fields in each case, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no waste. First sentence states purpose, second explains return shape. Front-loaded and 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?

For a simple lookup tool with one parameter, the description covers purpose, input, and return behavior (including error case). It is complete given the presence of an output schema and good annotations.

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 a clear description of the 'code' parameter as 'Code INSEE (5 caractères).' The description adds no extra meaning beyond that, so baseline 3 is appropriate.

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

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

The description clearly states it retrieves a commune by INSEE code with a specific verb and resource. It distinguishes from sibling 'autocomplete_commune' by directing disambiguation there on not_found.

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 to use this tool when you have an INSEE code, and on not_found it suggests using autocomplete_commune for disambiguation. This provides clear when-to-use and an alternative.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses detailed behavioral traits: the specific data sources used (FINESS, RPPS, DINUM, INSEE), the cost in terms of API calls, the fact that it includes closed SIRETs, and that there is no cache. This adds significant transparency about what happens during execution.

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 first sentence stating the main purpose, followed by a version note, typical usage, output format, and cost. Although it is somewhat lengthy, every section adds valuable information and there is no redundancy. The information density is high.

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 covers the input, output format, behavior, typical uses, and cost. It does not explicitly address error conditions or edge cases, but the provided information is sufficient for an AI agent to correctly invoke the tool in typical scenarios.

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 describes the single parameter 'num_finess' as a 9-digit exact number with 100% coverage. The description does not add any additional semantics or constraints beyond what the schema provides, so it meets the baseline but does not exceed it.

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 that the tool reconstructs the complete timeline of a healthcare establishment by cross-referencing multiple data sources. It distinguishes itself from siblings like 'etablissement_by_finess' by focusing on historical changes rather than current state, and includes typical use cases that clarify its specific role.

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 usage scenarios (post-merger history, exact closure date, rebranding cascade) that serve as clear guidance on when to use this tool. While it does not explicitly list alternatives or state when not to use it, the scenarios implicitly differentiate it from current-state tools. This is strong contextual 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint are all appropriately set. The description adds behavioral details such as cache behavior (5min côté serveur), output format for shared labels, and the flag 'is_libelle_partage'. It also explains source and legal constraints. 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. It front-loads the main purpose and provides essential details. However, it contains detailed explanations (e.g., libelle_clarifie format) that could be shortened without losing clarity.

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 (listing specialties with structured output), the description is fully complete. It covers the output fields, purpose, usage context, perimeter, source, legal notice, and relationship to sibling tools. The presence of an output schema means return values need not be explained.

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 one optional boolean parameter with a description in the schema itself (100% coverage). The tool description does not add further parameter semantics beyond what is already documented in the schema, 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 immediately states that the tool lists Ameli specialty codes present in the database, with their native label, type_ps_code, and count, sorted by descending frequency. It clearly distinguishes from siblings like 'lister_specialites_medicales' and 'lister_types_ps_ameli' by focusing on Ameli specialties with frequencies.

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 'Utile pour découvrir la nomenclature avant de filtrer un professionnels_in_radius ou professionnels_par_specialite_dept', providing clear when-to-use context. It also delineates the perimeter (libéraux conventionnés UNIQUEMENT) and out-of-scope cases, and suggests an alternative (Annuaire Santé ANS) for other statuses.

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 readOnlyHint=true et idempotentHint=true. La description ajoute des détails comportementaux : tri par count_ps DESC, source RPPS/Annuaire Santé ANS (Supabase dump mensuel). Elle ne contredit pas 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?

La description est concise, bien structurée et front-loaded : elle commence par l'objectif, puis l'utilisation, et enfin les détails techniques. Chaque phrase apporte une information utile sans redondance.

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?

Pour un tool simple avec un paramètre optionnel et sans output schema, la description couvre tous les aspects nécessaires : objectif, usage contextuel, défaut, tri, source de données. C'est complet.

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

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

Le schéma de l'unique paramètre profession_code est bien documenté (description à 100%). La description ajoute des exemples concrets (ex '60' Infirmier) et précise le comportement avec une string vide ou 'null', ce qui renforce l'utilité.

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 le tool liste les spécialités médicales avec leur libellé et le nombre de professionnels de santé, en précisant le contexte du RPPS. Elle se distingue des outils frères comme lister_specialites_ameli ou densite_professionnels_sante.

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 fournit explicitement le cas d'usage : utiliser ce tool avant d'appeler densite_professionnels_sante ou professionnels_rpps_par_dept avec un savoir_faire_code précis. Elle explique le filtre par défaut et comment changer de profession.

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 readOnly, idempotent, and non-destructive. The description adds context that queries live data (not a dictionary) and discloses weekly update cadence and legal reuse conditions, reinforcing transparency beyond 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 and front-loaded: first sentence states core output, then clarifies live data, scope, alternatives, and source. Every sentence adds value; no 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 presence of an output schema and annotations, the description sufficiently covers purpose, scope, alternatives, and data freshness. No missing essential information for effective agent 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?

The single parameter 'include_freshness' is fully described in the input schema. The description does not add additional parameter-level semantics beyond what the schema provides, so baseline score applies.

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 Ameli type_ps codes with their labels, counts, and specialties. It explicitly distinguishes from related siblings like 'lister_specialites_ameli' by focusing on type_ps and provides scope boundaries.

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 and when-not to use: only for liberal conventioned practitioners, excludes hospitalists and salaried biologists. It points to an alternative source for other statuses (Annuaire Santé ANS).

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 (readOnly, idempotent, non-destructive), description discloses return structure (LookupResult with found discrimination), source, and error handling for merged/changed codes. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no redundant information. Efficient and clearly structured.

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 return type, conditional behavior, and source. Output schema handles return fields. Could mention data recency, but overall complete for a lookup tool.

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

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

The schema already provides full description with examples (100% coverage). The tool description adds no further parameter-level details, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns three population metrics (PMUN, PCAP, PTOT) for a French commune by INSEE code, with source and official use noted. Distinguishes from siblings like get_commune_by_code and population_par_departement.

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 tells when to use (to get commune population) and what happens when the code is obsolete (found: false with redirection to autocomplete_commune), providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds value by specifying the data source (INSEE Melodi) and methodology recommendation (DREES), complementing the annotations without 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?

Two sentences, front-loaded with key information (metrics, source, usage tip). Every sentence adds value; no filler or 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 presence of an output schema, the description does not need to detail return values. It covers purpose, parameter usage, source, and recommendation, which is fully sufficient for this simple read-only tool.

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

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

Schema covers parameter 'code' at 100% with description. Description enriches it with concrete examples (75, 13, 2A, 971) and adds contextual validation (support for special codes), going beyond the schema's generic description.

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

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

Clearly states the tool returns three population metrics (PMUN, PCAP, PTOT) for a French department by INSEE code. Distinguishes from sibling 'population_par_commune' by targeting departments, and provides specific usage guidance (e.g., PMUN for density).

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 covers when to use (department lookup by code) and includes edge cases (Corse 2A/2B, DOM 971-976). Does not list alternatives, but sibling names imply context, and the description provides recommended metric (PMUN) for a common use case.

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 adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It details fallback logic to the FHIR ANS API with freshness specifications (monthly ingestion for db, daily for ans_fhir), the 'source' field behavior, and the 'include_freshness' parameter effects. 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 comprehensive but not overly verbose. It front-loads the core purpose and ID format, then provides details on multiplicity, fallback, and parameters. Each sentence adds value, though it could be slightly more concise by grouping related technical details.

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

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

Given the tool's complexity (multi-site, fallback, freshness parameter) and the presence of an output schema, the description covers all necessary aspects: ID format, behavior when multiple sites, fallback mechanism, source field, freshness parameter effect, API key requirement, and data license. It is complete and well-rounded.

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 description adds meaning beyond the schema for the 'rpps_id' parameter by explaining the 11/12 character format and the '81' prefix for modern IDs. For 'include_freshness', it clarifies that it only affects 'source: db' results. Since schema description coverage is 50% (include_freshness has a schema description, rpps_id does not), the description compensates well.

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

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

The description clearly states the tool retrieves a healthcare professional's profile by national ID (rpps_id/IDNPS). It specifies the ID format (11-12 digits, with prefix '81' for modern IDs) and notes it returns multiple rows if the professional practices at multiple sites. This distinguishes it from sibling tools like 'rpps_search_by_name' (name-based search) and 'professionnels_rpps_in_radius' (geographic 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 implies when to use: when you have an exact rpps_id and need the professional's details. It explains fallback behavior (local DB then FHIR ANS) and the source distinction. However, it does not explicitly state when not to use it (e.g., for name-based lookups use 'rpps_search_by_name') or provide alternative tools; but the context makes it clear enough.

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 (readOnly, openWorld, idempotent, non-destructive), the description adds key behavioral details: geolocation precision (~3 km), distance type (haversine), deduplication behavior, data source and update frequency (weekly), and copyright attribution. 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 efficiently structured: starts with a clear purpose sentence, then proceeds logically through precision, parameter usage, dedup, distance, perimeter, and source. Every sentence adds unique value with no redundancy. Though lengthy, it earns its length through completeness.

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?

Considering the 8 parameters, output schema presence, and complexity, the description covers all necessary context: geolocation precision, parameter interplay, perimeter inclusion/exclusion, data freshness, and linkage to sibling tools. It leaves no significant gap for the agent to infer.

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 description coverage, the description adds significant value by explaining the meaning of type_ps_codes (listing the three codes and their catch-all nature), dedupe_by_ps (default behavior and structure), include_freshness (effect on payload), and referencing sibling tool for specialite_codes. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: searching for liberal health professionals (conventionnés) within a geographic radius. It specifies the resource (professionnels de santé libéraux conventionnés), distinguishes from sibling tools by mentioning the Ameli source and scope, and includes precise geolocation accuracy notes.

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 guidance is provided: when to use specialite_codes over type_ps_codes, how dedupe_by_ps works, and when to use external services for driving distance. It also clearly defines the perimeter (libéraux conventionnés only) and lists what is not covered, directing users to alternative sources like RPPS.

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, openWorldHint. The description adds operational context: source (Ameli), update frequency (weekly), legal reuse requirements, and pagination behavior with `truncated=true`. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with clear sections, but somewhat lengthy. Each sentence adds value (scope, filters, pagination, deduplication, source, legal). Could be slightly more concise, but structure is good and information is front-loaded.

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

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

Given the tool's complexity (7 params, 1 required), the description is highly complete. It covers scope, out-of-scope, pagination, deduplication, source, legal note, and references a sibling tool for code lists. Output schema exists, so return values need not be described.

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 good descriptions. The description adds meaning beyond schema by explaining `type_ps_code` values, the distinction between type and specialty codes, how to use `offset` for pagination, and `dedupe_by_ps` for multi-sites. This justifies a slightly higher score than 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 lists liberal health professionals in a department with optional filters, distinguishes itself from radius-based tools, and contrasts with sibling tools like `lister_specialites_ameli`. The verb 'list' and resource 'professionnels de santé libéraux conventionnés' are specific.

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 provides when to use (administrative enumeration), when not to use (for hospital/salaried or all statuses), and alternatives (Annuaire Santé ANS, or `lister_specialites_ameli` for codes). Gives guidance on choosing `specialite_code` over `type_ps_code` and explains pagination with `offset`.

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 value by explaining coordinate accuracy (centroids ~3km), the need to cross-reference num_finess for precise addresses, and the default category plus optional includes (agents publics, étudiants). This goes beyond 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 and detailed, which is justified given the complexity (9 parameters, multiple categories). However, it could be more concise; some details like percentages and source URLs, while useful, add length. The front-loading is good.

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 covers all critical aspects: differentiation, parameter defaults, coordinate caveats, data freshness opt-in, and data source. It leaves no major gaps for an AI agent to understand usage and limitations.

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

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

With 78% schema coverage, the description significantly enriches parameter meaning: examples for profession_codes, ANS codes for mode_exercice_codes, detailed explanation of include_agents_publics and include_etudiants with percentages. It also links to the nomenclature source, providing context the schema alone 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 it searches for health professionals via RPPS, using the verb 'Recherche' and specifying the resource. It immediately distinguishes itself from the sibling 'professionnels_in_radius' by noting it covers all professionals (liberals, salaried, etc.), making the 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?

The description provides explicit guidance on when to use this over the sibling, explaining the filtration difference. It details parameter usage (e.g., profession_codes, mode_exercice_codes) and defaults (only civil category). However, it does not explicitly state when not to use this tool beyond the sibling comparison.

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, and idempotent hints. The description adds detailed behavioral context: default category Civil, optional inclusion of public agents and students, source of nomenclature, pagination details, and the include_freshness parameter. 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 thorough and front-loaded with purpose and alternatives, but it is somewhat lengthy with detailed category breakdowns. Every sentence adds value, but could be more concise.

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 (9 parameters, 1 required, output schema present), the description covers usage, filters, categories, pagination, and alternative tools completely. The output schema handles return values, so no need to detail them.

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

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

Schema description coverage is 78% (high), and the schema already documents each parameter. The description reiterates the optional filters and pagination but does not add significant meaning beyond what the schema provides, so baseline scoring applies.

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 lists health professionals by department via RPPS, specifies it includes both liberal and salaried professionals, and distinguishes from the sibling tool 'professionnels_par_specialite_dept' by noting its specific use case for counting or listing salaried/total workforce.

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 preferring 'professionnels_par_specialite_dept' for conventioned liberals, and states this tool is for counting or listing salaried/total workforce. It also explains optional filters and default inclusion categories, providing 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?

The description adds significant context beyond the annotations, such as the public nature of the algorithm, the weighting of sub-scores, and the detailed output structure including the 'skipped' field. It does not contradict the annotations (readOnlyHint, idempotentHint, etc.).

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 thorough but somewhat lengthy, containing multiple paragraphs and bullet points. While well-structured, it could be more concise. However, the detail is warranted given the complexity of the tool.

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 has an output schema (context signals indicate 'Has output schema: true'), the description covers all essential aspects: algorithm, scoring logic, output fields (candidates, skipped, score_global), and differentiation between no candidates and rejected candidates. It is complete for the 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?

The single parameter 'num_finess' is well-documented in the schema (9-digit exact number). The description provides context on how it is used (to retrieve FINESS data) but does not add new semantic information beyond what the schema already covers. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: cross-referencing FINESS and SIRENE data to compute a coherence score for candidate SIRETs. It also explains the use case (confirmation/infirmation before prospection) and distinguishes itself from sibling tools by detailing its unique scoring algorithm.

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

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

The description explains when to use the tool (before prospection or quality cross-check) and clarifies the meaning of the 'skipped' field to differentiate scenarios. However, it does not explicitly mention when not to use it or list direct alternatives among siblings.

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, open-world, idempotent, and non-destructive traits. Description adds the data source but no additional behavioral context 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?

Single sentence with source, no wasted words. Perfectly concise for a simple tool.

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?

No output schema; description mentions 'nearest address' but not its structure. For a straightforward reverse geocode, partially adequate but could specify address fields or limitations.

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 provides full descriptions for both parameters ('Latitude (WGS84)', 'Longitude (WGS84)'). Description adds no extra parameter 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 performs reverse geocoding from GPS coordinates to nearest address, naming the source. It effectively distinguishes itself from sibling tools like geocode_adresse.

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?

No explicit guidance on when to use this tool versus alternatives, though the context implies it for reverse geocoding. Lack of when-not conditions or alternative references.

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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context beyond annotations: coverage limitations (RPPS link declared by professional, salaried well covered), default exclusion of agents publics and étudiants, source and license info. 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 moderately long but well-structured in French. It front-loads the core purpose and usage, then details coverage, defaults, and optional parameters. Every sentence contributes value, though minor repetition could be trimmed. Overall efficient for the 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 the tool has 5 parameters and an existing output schema (not shown), the description provides comprehensive context: purpose, usage, coverage, source, default behavior, and optional filters. It does not explain the output schema, but that is separate. It sufficiently aids selection and correct invocation.

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

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

The input schema has 5 parameters, but only 'include_freshness' has a description (coverage 20%). The description explains the boolean parameters 'include_agents_publics' and 'include_etudiants' with percentages and categories, adding meaning beyond the schema. However, 'limit' and 'num_finess' lack description, and 'mode_exercice' mentioned in description is not a parameter. The description partially compensates for low 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 lists healthcare professionals attached to a FINESS establishment using a 9-digit number. It identifies itself as the pivot between RPPS and FINESS, answering 'who works in this lab/hospital/clinic?'. This distinguishes it from sibling tools like 'etablissement_by_finess' (establishment info) and 'professionnel_by_rpps' (single professional).

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

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

The description explicitly states when to use this tool ('répond à "qui travaille dans ce labo / hôpital / clinique ?"') and provides detailed context: coverage details, default filtering to civil category, and optional inclusion of agents publics and étudiants with percentages. It does not explicitly mention when not to use or compare to alternatives, but the usage context is clear.

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

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

Annotations already mark as readOnly, idempotent, non-destructive. Description adds: fuzzy matching engine (pg_trgm), tolerance details, sorting by relevance, default category filtering with percentages, return format with match_score field, and opt-in freshness. 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?

Well-structured with clear paragraphs covering search behavior, usage, return format, category details, and source. Slightly verbose but every sentence adds value. Front-loaded with essential 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 the tool has an output schema, the description covers all needed aspects: parameters, default behaviors, category filtering, return format, source citation, and license. No gaps for a complex search 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 description coverage is 71% (5/7 params described in schema). Description adds value for undocumented parameters (include_etudiants, include_agents_publics) by explaining their effect and referencing official nomenclature. Also provides examples for departement codes. Lacks explicit mention of all params but overall enhances 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?

The description clearly states it performs fuzzy search of healthcare professionals by identity (nom + optional prenom and departement), using trigram matching tolerant to accents and typos. It distinguishes from sibling tools like professionnel_by_rpps (exact ID lookup) or professionnels_in_radius (location-based).

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 typical usage example ('find Dr Martin in Paris'), explains that without département results can be numerous and recommends using match_score for disambiguation. Also clarifies default category filtering (Civil only) and how to include other categories via parameters.

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 provides extensive behavioral context beyond annotations: cost (RPC calls), version changes (V0.7.0 breaking), logic steps, two distinct verdicts, and data freshness delay (1-2 months). Annotations already indicate read-only, idempotent, and non-destructive, and the description adds valuable detail without 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-structured with clear sections (version, logic, return format) but is somewhat verbose for an AI agent. It could be more concise while retaining essential details.

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

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

Given the tool's complexity and presence of an output schema, the description is comprehensive: it explains the algorithm, data sources, multiple verdicts, edge cases (not found), and cost. No gaps identified.

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 describes the parameter (num_finess) with 100% coverage. The description adds some context about the parameter's usage in the logic but does not provide significant additional 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: to verify if a FINESS healthcare establishment is still active by cross-referencing multiple data sources. It distinguishes itself from sibling tools by focusing on activity status rather than just retrieving establishment 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 does not explicitly state when to use this tool versus alternatives. It implies usage for activity verification but lacks guidance on exclusions or when another tool would be more appropriate.

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