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?

The description adds significant behavioral context beyond annotations: the discriminated `LookupResult` response, explicit failure modes, cache behavior (5min server-side), data freshness opt-in, and legal source attribution. Annotations already indicate read-only and idempotent, but the description enriches this.

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 contains all essential information, but is slightly verbose with repeated explanations of the `found` states. Minor trimming could improve conciseness 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 output schema exists, the description adequately covers the behavior: payload overview for found cases, failure messages, source and sync details, cache, alias, and data freshness options. No gaps for a fetch-by-ID 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?

100% schema parameter coverage is already present, but the description adds value by specifying the exact 9-digit format for `num_finess`, listing accepted aliases, and explaining the opt-in nature and behavior of `include_freshness`.

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 center (CDS) by FINESS number. It distinguishes itself from the sibling `etablissement_by_finess` by highlighting the specific CDS-related fields it exposes (carte_vitale, APCV, specialites).

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 on when to use this tool vs. `etablissement_by_finess` for non-CDS structures. It also explains the `found: false` scenario for non-CDS or very recent CDS, and mentions the data source and sync frequency.

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. Description adds source (Ameli), sync frequency, coordinate centroid approximation (~3km), and absence of hours/tariffs/secteur. 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 well-structured with clear sections (purpose, source, differentiation, filter details), though slightly dense. Every sentence adds value; could be slightly tighter but still excellent.

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

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

With output schema present, description covers all necessary context: data source, filter behavior, coordinate precision, cache, and relationship to sibling tools. Comprehensive for a complex parameter set.

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 significant value: explains any-of logic for `specialite_codes`, practical note on `accepte_carte_vitale`, `type_etab_codes` deprecation, `include_freshness` cost, and aliases for coordinates and radius.

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 'Recherche des Centres de Santé (CDS) dans un rayon géographique' and distinguishes from sibling `etablissements_finess_in_radius` by listing specific fields (carte_vitale, APCV, spécialités).

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 differentiates from `etablissements_finess_in_radius` and advises pivoting to `etablissement_by_finess` for precise address. Also notes filter semantics and deprecated 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 declare readOnly, idempotent, openWorld, and not destructive. The description adds significant context: it is a raw primitive without business interpretation, explains the statut values (match, divergent_after_normalization, finess_absent), score_dice range, and the discriminated result object. 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 a clear first sentence stating the main purpose, followed by usage example and statut explanations. It is slightly lengthy but every sentence adds value. Could be marginally trimmed without loss.

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 (LookupResult), the description fully covers return semantics, error cases, and ties to sibling tools. No gaps remain for an agent to understand selection and 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 single parameter `num_finess` is fully described in the schema with '9 chiffres'. The description adds context about usage (e.g., if not a CDS, result is not found) but does not add new parameter-level details beyond that. Given 100% schema coverage, the additional context justifies a 4.

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 addresses of a health center from two sources (CNAM vs FINESS) for the same num_finess. It uses specific verbs and resources, and distinguishes itself from the sibling tool '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?

The description provides explicit when-to-use (signaling unsynchronized moves) and when-not-to-use (if num_finess not a CNAM center, use `etablissement_by_finess`). It also explains the return format and how to interpret results.

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?

Beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description adds critical behavioral context: it warns of RangeError for Paris/Marseille/Lyon, silent empty results with wrong codes, default category (Civil), opt-in for agents publics/etudiants, and that no interpretation (e.g., 'desert medical') is returned.

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

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

The description is long and detailed but well-structured with sections, bold key terms, and examples. It could be more concise without losing clarity, but the structure aids parsing.

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 all aspects: methodology, parameter constraints, limitations, defaults, warnings, and references to complementary tools (lister_nomenclature). No gaps detected.

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 82% (high), but the description adds significant semantics beyond the schema: conditional semantics of code_dept, default for mode_exercice_codes, semantics of include_etudiants/include_agents_publics, and warnings about Paris/Marseille/Lyon. It does not fully compensate for the remaining 18% but adds clear value.

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 computes health density per 100,000 inhabitants for professionals or establishments at department or commune level, with explicit differentiation between the two cible targets and reference to siblings via methodology details.

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 mandatory famille for etablissements, warnings against mixing code systems, a note that Paris/Marseille/Lyon commune-level is unsupported, and recommendation to use compare_national. It also implies distinctions from sibling tools that list counts rather than compute density.

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 read-only, idempotent, non-destructive. Description adds critical behavioral details: hard cap at 3, token cost warning, and that a failing competitor does not cancel others. 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 structured in three paragraphs covering purpose, constraints, and usage. It is somewhat lengthy but every sentence provides valuable information 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 no output schema, the description thoroughly explains what each FINESS returns (status, team size, history, M&A signals, parent group, coverage flag) and lists data sources. It is complete for an agent to understand inputs, outputs, and 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?

Schema coverage is 100%, but description adds meaning: finess array is typically top 3 competitors from a previous step, and max is a hard cap defaulting to 3. This contextualization aids correct invocation beyond raw 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 it performs an in-depth investigation of top competitors, detailing specific data points (status, team size, history, M&A, parent group). It distinguishes itself from sibling tools by being a composite tool that uses multiple sources like inspect_site and entreprise_by_siren for enrichment.

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 typical use case: called on FINESS numbers from 'concurrents.top[0..2]' returned by 'panorama_implantation_complet'. Also provides constraints (max=3, expensive inspect_site calls) and behavior on failure, giving clear guidance on when and how to use.

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?

The description adds substantial behavioral details beyond the annotations: it explains that it makes three parallel sub-calls, has caching, a p95 overhead ≤600ms, and edge cases (e.g., when historique is unavailable). It also describes the return format (LookupResult with found flag) and truncation behavior. Annotations already indicate read-only and idempotent, and the description complements this with concrete behavioral context.

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 clear sections (purpose, when to use, return format, cost, aliases). Every sentence serves a purpose, though it could be slightly more concise without losing clarity. Front-loading the 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 the tool's complexity (four sub-calls, multiple edge cases, sibling tools, output schema exists), the description covers all needed information: input format, output structure, performance cost, truncation behavior, and use-case guidance. There are 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%, and the description enhances parameter understanding: it explains `rpps_limit` default (10), range ([1,50]), and the meaning of the `truncated` flag. It also documents aliases for `num_finess` (numFiness, finess, id). This adds significant value 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 it provides a '360 view of a health establishment' by aggregating four specific sub-calls (identification, statut, professionnels, historique). It distinguishes from sibling tools like `verifier_site_actif`, `rpps_dans_etablissement`, and `historique_etablissement`, making its purpose explicit and unique.

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 specifies when to use the tool (e.g., prospecting, territorial audit, CRM enrichment) and when not to ('for targeted needs like just the verdict or just the history, prefer the individual tools'). It names alternative sibling tools, providing clear usage guidance.

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

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

Adds substantial behavioral context beyond annotations: pagination details, scope (libéraux conventionnés only), exclusions, source and update frequency, and consequence of mixing codes (empty response).

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 sections: purpose, warnings, referentiel details, pagination, scope. Every sentence adds value; slightly long but not verbose 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?

Highly complete given tool complexity: explains all parameters, pitfalls, scope, exclusions, source, and update frequency. 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?

Schema coverage is 100% with descriptions for all 5 parameters. The description adds value by explaining referentiel-specific contexts (e.g., profession_code only for rpps_savoir_faire) and pagination behavior, justifying above-baseline 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?

Clearly states the tool lists nomenclature codes from the server, with specific verb 'Découverte des nomenclatures' and resource. Distinguishes from siblings by being a prerequisite for filtering 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?

Explicitly instructs to call before filtering rather than guessing codes, warns about distinct nomenclatures and not mixing codes. Provides precise usage for each référentiel and which sibling tools they apply to.

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 detailing degradation mechanism with couverture flags, return format (summaries only), special handling for Paris/Lyon/Marseille (plm_mode=true), precision of prescripteurs counts, and the total rejection on geocoding failure (RangeError). Annotations already indicate readOnly, idempotent, non-destructive; description adds crucial behavioral context.

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 is informative. It is front-loaded with the core purpose, then details each section, degradation, pitfalls, and workflow. No fluff; each word earns its place. Structure is logical and easy to parse.

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

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

Given the tool's complexity (7 sections, degradation, fallback), the description is remarkably complete. It explains what each section contains, how to interpret couverture flags, when to use fallbacks, and the workflow for post-processing. The output format is adequately described as summaries only. No gaps that would leave an agent guessing.

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

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

The input schema already has detailed descriptions (100% coverage). The main description adds value by explaining the XOR relationship between point and adresse, the default rayon_km of 5, and that geocoding uses IGN. It also clarifies that code_insee is needed with point. This complements the schema without being redundant.

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: a comprehensive lab implantation study that aggregates 7 sections in parallel, replacing ~15 individual MCP calls. It specifies the verb ('Étude d'implantation labo'), the resource (address, geocoding, and data sections), and distinguishes it from siblings by being the composite 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?

The description explicitly tells when to use this tool: as the first call to start a study, then follow up with individual tools for partial/indisponible sections and 'enrichir_concurrents' for the top 3 competitors. It also states that this replaces ~15 individual calls, guiding the agent to prefer this over many 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?

Discloses that no business interpretation is returned (no 'désert médical'), explains mixed granularity (commune vs department), limitations for Paris/Marseille/Lyon, and alias handling. Annotations confirm read-only, open world, idempotent, non-destructive. Description adds significant 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?

Well-structured with clear sections and bullet points, but slightly lengthy. However, every sentence provides value, and the structure aids 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 (multiple data sources, mixed granularity, limitations, no output schema), the description covers all necessary context: sources, update frequency, limitations, fallback behavior, and return field interpretation.

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% for both parameters. Description adds default values for finess_familles, explains how to omit FINESS, and documents alias variants for code_insee. This adds meaning 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 it aggregates health data for a French commune in one call, specifies data sources (INSEE, FINESS, DREES), and claims to replace 7-10 individual MCP calls, distinguishing it 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?

Explicitly says when to use (for commune panorama), when not (Paris/Marseille/Lyon: use densite_professionnels_sante), and provides guidance on interpreting the niveauEtablissements field to avoid confusion between 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it explains the auto-detection of granularity, the return type (LookupResult discriminated by found), and specific cases like lookupNotFound for Mayotte. 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 well-structured with a clear main sentence followed by bullet points for details. It front-loads the purpose but includes some redundant phrasing (e.g., repeated code length explanations). Could be slightly tighter, but overall very 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 a single required parameter, existing output schema, and comprehensive annotations, the description still adds substantial context: edge cases (arrondissements, Mayotte), alternative tool references, data source, and legal usage of PMUN. It leaves no ambiguity about what the tool does and when to use alternatives.

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 'code' parameter, providing a baseline of 3. The description adds value by listing accepted aliases (code_insee, codeInsee, insee, etc.) and explaining the auto-detection logic based on code length, which is useful for agents. Thus, score 4.

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 population data for a commune or department based on INSEE code, specifying the three population metrics (PMUN, PCAP, PTOT). It distinguishes itself from siblings by being a specialized population lookup, not a general geographic or health facility 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?

The description explicitly tells when to use this tool (population lookup) and provides guidance on what to do when a commune has merged (use autocomplete_commune) or when data is absent (Mayotte). It also notes that arrondissements are not supported, guiding the agent to use the mother commune or department code.

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?

Annotations already set readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: the proxy nature of `revenu_median_pondere` (population-weighted average, not a true median), coverage limitations (FILOSOFI only for communes ≥5000 hab), and the geographic centroid logic for basin aggregation. 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 relatively long but well-structured with clear sections and bullet-point style. Every sentence provides necessary information (modes, data sources, limitations). Could be slightly shortened without losing content, but the structure aids 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 (two modes, aggregation logic, data sources, multiple output fields), the description covers all essential aspects: input constraints, mode behaviors, output fields, data freshness, and limitations. An output schema exists, so return values need not be detailed. The description is complete for an AI 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?

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema: explains the mutual exclusivity of point vs code_iris, the effect of rayon_km on mode (ilot vs bassin), and the output structure (LookupResult with mode, revenu_median_pondere, etc.). It does not add syntax or format details already in 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 defines the tool as providing demographic profiles at the IRIS level, specifying data sources (INSEE RP 2022 + FILOSOFI 2021) and differentiating it from sibling tools like `population` (simple population) and `panorama_sante_territoire` (broader health panorama). The verb 'Profil démographique' and resource 'QUARTIER (IRIS)' 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?

The description explicitly explains two modes (with/without `rayon_km`) and gives guidance on when to use alternatives: 'Pour une simple population de commune/dept, utiliser `population`.' It also clarifies input constraints (exactly one of point or code_iris) and the optional parameter.

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.