france-data-mcp

etablissement_finess_by_nom

Read-onlyIdempotent

Cherche un établissement de santé par son NOM (« Institut Gustave Roussy », « Hôpital Foch », « Clinique Pasteur ») et rend ses fiches FINESS avec coordonnées exactes. À APPELER AVANT tout géocodage dès que le lieu cité est un hôpital, une clinique, un centre, un institut, un EHPAD… : l'annuaire d'adresses (BAN / geocode_adresse) ne connaît que des rues et renverrait une « rue Gustave » n'importe où en France. Passer le nom PROPRE de l'établissement (le sigle « IGR » n'est pas dans FINESS) et, si connue, la commune (nom_commune ou code_insee — Paris/Lyon/Marseille acceptés en ville entière) ou le departement.

Sortie : statut = unique (une fiche) | ambigu (plusieurs : homonymes OU plusieurs fiches d'un même campus — l'IGR en a 4 : CLCC, site EFS, service de santé au travail, site de Chevilly-Larue) | aucun. candidats[] (≥ seuil de similarité 0,8, triés : similarité, puis hôpitaux/cliniques avant pharmacies/CMP/EFS homonymes, puis libellé le plus court) avec coords, geo_precision, categorie.famille, similarite. commune_prouvee = la commune (commune-mère pour Paris/Lyon/Marseille) quand TOUS les candidats y sont — c'est le fait à utiliser pour ancrer une analyse territoriale ; null avec raison_commune: 'communes_divergentes' sinon (« Clinique Pasteur » sans commune = 16 fiches dans 9 villes → demander la commune, ne JAMAIS prendre le premier). Le point à utiliser = premier candidat avec coords non null (2,4 % des fiches n'ont pas de point). meilleure_similarite sous 0,8 sur aucun : le nom FINESS diffère (abréviations administratives : « HOP EUROPEEN G POMPIDOU ») → relancer avec la partie distinctive (« Pompidou ») + la commune ; meilleure_similarite: null = AUCUNE ligne dans le territoire demandé → vérifier la commune/le département avant de conclure que le nom n'existe pas. tronque: true (autant de lignes que limit) → la commune n'est PAS prouvée (raison_commune: 'tronque') : monter limit ou préciser le territoire. lignes_rejetees > 0 = lignes RPC illisibles écartées. Source : FINESS / ANS (flux quotidien, ingéré le 1ᵉʳ et le 15 ; établissements EN SERVICE uniquement). Chaque résultat porte geo_precision: "adresse" dès que coords est présent (point WGS84 ANS ou point BAN de l'adresse, jamais un centroïde ; un établissement sans coords n'a pas de point connu et est invisible des recherches par rayon) et siret_ans (SIRET déclaré par l'ANS, fait brut non vérifié SIRENE — pour le verdict : reconcilier_finess_sirene / verifier_site_actif). Note : champ email toujours null (non exposé par FINESS public).

Input Schema

TableJSON Schema

Name	Required	Description
`nom`	Yes	Nom de l'établissement tel qu'on le dit (3 caractères min). Accents, casse et ponctuation indifférents. Sans le nom de la commune (le mettre dans `nom_commune`).
`limit`	No	Candidats bruts lus avant seuil et tri (1-200, défaut 50). Monter si le nom est très partagé (« Saint Antoine » : 42 fiches).
`code_insee`	No	Code INSEE de la commune (5 caractères). Paris/Lyon/Marseille : 75056 / 69123 / 13055 acceptés (ville entière) comme un arrondissement. XOR avec `nom_commune` et `departement`.
`departement`	No	Code département (ex : '94', '2A', '971'). Seul = filtre département ; avec `nom_commune` = hint de désambiguïsation.
`nom_commune`	No	Nom officiel de la commune où se trouve l'établissement (résolu via geo.api.gouv.fr). Ex : "Villejuif", "Paris". Combinable avec `departement` comme hint de désambiguïsation. XOR avec `code_insee`.
`include_freshness`	No	Si true, ajoute un champ `data_freshness` au payload (dans `query_metadata` si présent, sinon à la racine) listant, par source (FINESS, Ameli, RPPS, CDS, IRIS), la dernière ingestion réussie (`last_success_at`, `staleness_days`) ET la dernière fois que la donnée a réellement changé (`last_data_change_at`, `data_age_days` — un run court-circuité « fichier amont identique » compte comme succès mais ne rajeunit pas la donnée ; c'est `data_age_days` qui dit l'âge réel de ce qui est servi). Opt-in pour ne pas alourdir les payloads par défaut. Cache 5min côté serveur — coût négligeable.

Output Schema

TableJSON Schema

Name	Required	Description
`statut`	Yes
`tronque`	Yes
`candidats`	Yes
`raison_commune`	Yes
`commune_prouvee`	Yes	{ code_insee, ville } quand tous les candidats sont dans la même commune (commune-mère PLM), sinon null.
`lignes_rejetees`	No
`query_normalisee`	No
`communes_candidates`	No
`meilleure_similarite`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedSep 22, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With annotations already declaring readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, the description still adds substantial beyond-annotation behavior: candidate sorting rules (similarity, then type priority before pharmacies/CMP/EFS, then shortest label), the 0.8 similarity threshold, `commune_prouvee`/`raison_commune` semantics, the 2.4% of records without coordinates ("un établissement sans coords n'a pas de point connu et est invisible des recherches par rayon"), truncation behavior, `lignes_rejetees` (RPC unreadable), ingestion cadence (1st and 15th, EN SERVICE only), `geo_precision: "adresse"` meaning never a centroid, `siret_ans` provenance caveat, and `email` always null. All of it is consistent with the annotations — 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.

Conciseness4/5

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

The description is long (several dense paragraphs), but the structure is coherent: purpose and when-to-use are front-loaded in the first paragraph, followed by output semantics, then edge cases and provenance. Nearly every sentence carries a functional fact (2.4% missing coords, 0.8 threshold, ingestion dates, 16 fiches in 9 villes for 'Clinique Pasteur'), and the concrete examples replace abstract explanation. It is borderline heavy and could be tightened, but the length is largely earned by the tool's genuinely complex ambiguity/truncation/freshness semantics.

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

Completeness5/5

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

Despite having an output schema, the description explains all return semantics an agent needs: `statut` values (unique/ambigu/aucun), `candidats[]` ordering and threshold, `commune_prouvee` logic with `raison_commune` reasons ('communes_divergentes', 'tronque'), `meilleure_similarite` as a diagnostic for both wrong-name and wrong-territory, `geo_precision` semantics, `siret_ans` verification caveat with cross-references to reconcilier_finess_sirene and verifier_site_actif, and the freshness source. For a tool with this many failure modes, nothing material is left to inference.

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

Parameters4/5

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

Schema coverage is 100% and the schema itself is already rich (XOR constraints, PLM codes, freshness opt-in), so the baseline is 3. The description adds value beyond the schema: the proper-name rule with the IGR acronym counter-example, the "relancer avec la partie distinctive" strategy for `nom`, a concrete `limit` tuning example ("« Saint Antoine » : 42 fiches"), and the explicit PLM code values (75056/69123/13055) echoing the schema. It genuinely complements rather than restates the structured fields, though the schema carries most of the load.

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

Purpose5/5

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

The description opens with a specific verb+resource+output: "Cherche un établissement de santé par son NOM… et rend ses fiches FINESS avec coordonnées exactes." It differentiates from siblings by explicitly contrasting with `geocode_adresse`/BAN ("l'annuaire d'adresses… ne connaît que des rues") and implies the distinction from `etablissement_by_finess` (lookup by ID) by being a by-name search. An agent can tell exactly when to pick this tool among the 33 siblings.

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

Usage Guidelines5/5

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

The description gives an explicit trigger condition — "À APPELER AVANT tout géocodage dès que le lieu cité est un hôpital, une clinique, un centre, un institut, un EHPAD" — plus a when-not (address directories only know streets and would return a 'rue Gustave' anywhere in France). It also prescribes input strategy (proper name, not acronyms like IGR; add commune if known) and fallback tactics for failure modes (relaunch with the distinctive part like 'Pompidou' when similarity < 0.8; verify the territory before concluding the name doesn't exist). This is explicit when/when-not/alternatives guidance.

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

All france-data-mcp tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.