Skip to main content
Glama
Sign In

Tulina

by ai.tulina.mcp
OverviewDiscussionsAdmin

foncier_dvf

Real-estate transactions from DVF+ open data (Cerema, since 2014) — price stats for a commune, or the raw mutations of a commune / around an address.

op:

  • "prix_m2" (default): price stats (€/m²) for a French commune. Median/mean/min/max €/m² + per-year breakdown, on clean mono-bien sales (one Appartement or Maison per mutation; outliers <100 or >50000 €/m² filtered). Use to value a property by comparables. Needs code_commune.

  • "comparables": RAW transactions for a commune. NOT filtered: ALL property types (flats, houses, land, dependencies, mixed-use, commercial) and ALL natures (sale, VEFA off-plan, auction, exchange) — the agent decides the use (valuation, land analysis, market volume…). For a clean median €/m², use op="prix_m2" instead. Needs code_commune.

  • "comparables_adresse": RAW transactions around a PRECISE address. Geocodes the address (BAN), returns ALL mutations whose parcel lies within radius_m metres (distance to nearest parcel vertex — robust to multi-parcel goods), nearest first, each with distance_m. NOT filtered by property type/nature; median_prix_m2 is computed on residential mono-bien rows only (indicative). Needs adresse.

Each raw row (both "comparables" ops): date_mutation, nature_mutation, valeur_fonciere, type_bien (raw DVF+ label) + type_local (set only for residential mono-bien, else null), surface_reelle_bati, surface_terrain, prix_m2 (null if not computable), nombre_locaux, vefa, id_parcelle(s), adresse (reverse-geocoded BAN), lat/lon. Most recent first (nearest first for "comparables_adresse").

⚠️ Dense communes (Paris arrondissements) can time out on a FIRST call. The public DVF+ API takes 20 to 35 s to serve the first page of one arrondissement-year it has not served lately (measured 26/10/2026: 75115, 75116, 75117), beyond this tool's wait; once served, the same query answers in ~1 s. Each year warms up on its own, so a few calls may be needed. A timeout here says nothing about the data: retry once or twice before concluding.

With with_dpe=True (op="comparables_adresse" only), each sale is enriched with ADEME energy data: a HOUSE gets its matched dpe (etiquette + dpe_match confidence by proximity & surface); a FLAT gets dpe_immeuble (the building's DPE list — NO 1:1 match, as DVF and DPE share no dwelling key).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "foncier_dvf"
  }
}

Input Schema

NameRequiredDescriptionDefault
opNoprix_m2 (default) | comparables | comparables_adresse.prix_m2
_orgNoOrg (id) de CET APPEL. `oto_list_orgs()`.
limitNocomparables ops — max rows (default 50).
yearsNolookback in years WITH data (DVF lags ~6 months; up to ~2014). Defaults differ per op: 3 for "prix_m2" and "comparables_adresse", 2 for "comparables".
_groupNoÉquipe (id) de CET APPEL, sous son org parente.
_run_idNoOBLIGATOIRE à chaque appel dès `run_start` ou `data_claim_next` : sans lui, l'écriture sur une ligne réservée est refusée. Hérité seulement si le serveur tient un run actif — n'y compte pas.
adresseNoop="comparables_adresse" — free-form address (e.g. "44 la canebière marseille").
_projectNoProjet (id) de CET APPEL — jeton PRIMAIRE. `oto_project(op='list')`.
radius_mNoop="comparables_adresse" — search radius in metres (default 500).
with_dpeNoop="comparables_adresse" — attach ADEME DPE energy labels per sale (default False).
_instanceNoInstance de connecteur PRÉCISE (un credential exact). `oto_instance(op='list')`.
type_localNo"Appartement" | "Maison". Default: both for "prix_m2", everything (all property types) for the two "comparables" ops.
surface_maxNo
surface_minNo
code_communeNoop="prix_m2"/"comparables" — INSEE code, 5 digits (e.g. "13201" = Marseille 1er).

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations at all, the description carries the full burden and does so: it discloses outlier filtering bounds (<100 or >50000 €/m²), that raw rows are unfiltered by property type and nature, that `median_prix_m2` on the address op is residential-only and indicative, and the DPE matching caveat (house gets a proximity/surface-matched `dpe`, flat only gets a building-level list). It also discloses a real operational hazard — 20-35 s cold first-page latency on dense communes with ~1 s warm responses — which an agent would otherwise misread as a failure.

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?

Front-loaded: purpose, then a bulleted per-op breakdown, then row fields, then caveats. The structure makes a dense 15-parameter tool scannable. It is on the long side, and the timeout paragraph spends words on provenance ("measured 26/10/2026: 75115, 75116, 75117") that an agent doesn't need to act.

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?

No output schema exists, yet the description enumerates the fields of each raw row (date_mutation, nature_mutation, valeur_fonciere, type_bien vs type_local, surfaces, prix_m2, nombre_locaux, vefa, id_parcelle(s), address, lat/lon) and the sort order, which is exactly what is otherwise missing. For a 15-param, three-mode tool it leaves nothing an agent needs before calling.

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 87%, so the baseline is 3, but the description adds genuine meaning: `years` is a lookback in years WITH data and its default differs per op (3 vs 2), `type_local` defaults differ per op (both vs everything), `with_dpe` is restricted to comparables_adresse, and `radius_m` is defined as distance to the nearest parcel vertex rather than a naive centroid radius. The only gap is `surface_min`/`surface_max`, which carry no description in the schema and are never mentioned in the description.

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

Purpose4/5

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

Opens with a specific verb+resource: real-estate transactions from DVF+ open data, price stats for a commune or raw mutations of a commune/address. The three `op` modes are each given a distinct identity (aggregated €/m² stats vs. raw commune rows vs. raw transactions around a geocoded address), so an agent can pick a mode without opening the schema. It never differentiates itself from look-alike siblings such as foncier_prix_m2_app or foncier_comparables_app, which is the one gap keeping this below 5.

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?

Gives explicit when-to-use and when-not-to-use guidance per mode: "Use to value a property by comparables" for prix_m2, and "For a clean median €/m², use op=\"prix_m2\" instead" for comparables. Prerequisites are stated per op (needs `code_commune`, needs `adresse`), and the timeout section tells the agent exactly what to do — retry once or twice before concluding.

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

All Tulina toolsInspect
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.

Resources