Query and interpret DeepPVMapper’s French rooftop-PV detection registry through search, aggregation, counting, spatial, metadata, and community-activity tools.
Search individual detections by department/commune, capacity, surface, tilt, azimuth, imagery years/vintages, source, quality, false-positive status, and RNB building match.
Count detections exactly and aggregate estimated installed capacity, either with live filters or from precomputed department-level statistics.
Run map-style spatial queries with WGS84 bounding boxes and footprint geometry.
Profile the registry with field distributions, field coverage/completeness, source breakdowns, department rankings, and yearly deployment trends.
Understand data quality and semantics: estimated recall (~0.6), model-derived vs observed fields, source codes, recommended confidence thresholds, licensing/liability, and field definitions.
Get one detection’s full record, decoded sources, and confidence signals.
View pending, unverified community contributions overall or relevant to a specific area.
Large-scale rooftop PV detection pipeline for France. Classifies IGN aerial tiles with InceptionV3, segments positive patches with FCN/DeepLab, and extracts panel characteristics (surface, tilt, azimuth, installed capacity) via pypvroof.
🗺️ Official project page
Work carried out by Gabriel Kasmi as part of his PhD at Mines Paris-PSL (2020–2024).
DeepPVMapper's detection registry is also exposed as a public MCP (Model Context Protocol) server over Streamable HTTP, so any MCP-compatible client (Claude, etc.) can query the 1.14M+ rooftop-solar detections directly via natural language: search detections, aggregate installed capacity by department, explore an area, track yearly deployment, and check data-quality signals.
Live endpoint: https://zelhliylrlktnasircwp.supabase.co/functions/v1/mcp/mcp
Server source: supabase/functions/mcp
Registry listing: registry.modelcontextprotocol.io — io.github.gabrielkasmi/deeppvmapper
No install required — add the endpoint as a custom connector in any MCP client.
Related MCP server: MeteoControl MCP Server
Pre-computed detection results for French departments are available on Zenodo:
GDAL must be installed system-wide first, then via pip to match the running Python version:
# Ubuntu/Debian
apt-get install -y gdal-bin libgdal-dev libopenjp2-7
pip install "GDAL==$(gdal-config --version)"
pip install -r requirements.txtGPU required. CUDA 11.8+, 8 GB VRAM minimum.
Download model weights and runtime data from Zenodo:
Model weights are also available on Hugging Face:
The training dataset (BDAPPV):
Fill in the source paths in config.yml before running:
config key | what goes there |
| IGN JP2 tiles + |
| BDTOPO folder (BATIMENT.shp, ZONE_D_ACTIVITE_OU_D_INTERET.shp) |
| folder containing |
| folder containing |
python main.py --dpt 06--count sets tiles per classification batch (default 16 — reduce if OOM):
python main.py --dpt 06 --count 8--config points to an alternative config file (useful for RunPod deployments):
python main.py --dpt 06 --config /workspace/config_runpod.ymlTo process a subset of tiles (local testing), set tiles_list in config.yml:
tiles_list:
- 01-2024-0850-6565-LA93-0M20-E080
- 01-2024-0850-6570-LA93-0M20-E080Force a full rerun (wipe prior progress):
python main.py --dpt 06 --cleanFour steps run sequentially inside main.py:
step | what happens |
Init | Builds per-department auxiliary files (buildings, plants, communes) into |
Classification | Tiles loaded fully in memory. InceptionV3 classifies 299×299 patches; positives saved as GeoTIFFs to |
Segmentation | FCN/DeepLab segments each positive patch. LAMB93 polygons extracted, sorted by tile, merged into pseudo-arrays. |
Aggregation | pypvroof extracts tilt/azimuth/kWp per polygon. Building filter applied. Results written to |
On success: temp/ is deleted automatically.
On crash: temp/ is kept. Rerun the same command to resume from where it stopped.
Written to outputs_dir (default: data/):
file | description |
| Detected PV polygons in WGS84 |
| Per-installation registry: surface (m²), tilt (°), azimuth (°), kWp, city code, lat, lon |
| City-level aggregation: count, total kWp, avg surface, avg kWp |
| Polygons enriched with all characteristics |
Only residential-scale installations (1.7–36.1 kWp) located on buildings are retained.
parameter | default | description |
|
| Working directory. Deleted on success, kept on crash. |
|
| Final outputs directory. |
| 0.4 | Classification confidence threshold |
| 512 | Patches per GPU batch (classification) |
| 3 | Concurrent JP2 decode processes feeding the GPU — tune to your real CPU quota, not host core count |
| 35 | Gap between initial decode submissions, to avoid lockstep bursty waits — rule of thumb: decode_time / decode_workers |
| 0.46 | Segmentation binarization threshold |
| 64 | Images per GPU batch (segmentation) |
| True | Discard detections not on a building |
|
| pypvroof tilt method ( |
|
| pypvroof azimuth method |
|
| pypvroof installed-capacity regression type |
| (empty) | Optional tile subset for partial runs |
Contributions are welcome — both code (performance, new imagery sources, models, building filters) and registry corrections via the interactive map, no coding required.
See CONTRIBUTING.md for the contribution areas, setup instructions and workflow. Issues labelled good first issue are the best entry points.
GDAL is fragile to install, for two distinct reasons — and the fix below handles both.
The pip GDAL binding must match the system libgdal version exactly. pip install GDAL fails to build, or segfaults at import, if its version differs from the system library.
On images that ship a pre-installed python3-gdal apt package (common on RunPod/cloud GPU images), that package bundles its own osgeo/, which takes priority over the pip-installed one in sys.path — and its .so is often broken, regardless of what pip installs.
Run this in place of a plain pip install, e.g. right when deploying the pipeline, around the pip install -r requirements.txt step:
#!/usr/bin/env bash
set -e
# --- native GDAL lib (gdal-config must exist before pip can build the python binding) ---
apt-get update
apt-get install -y --no-install-recommends gdal-bin libgdal-dev
# --- purge python3-gdal if present: this apt package ships its own osgeo/,
# which takes priority over the pip-installed one in sys.path, and its
# .so is often broken ---
dpkg -l | grep -q python3-gdal && apt-get remove --purge -y python3-gdal || true
rm -rf /usr/lib/python3/dist-packages/osgeo
# --- python deps ---
pip install -r requirements.txt
# --- repin the pip GDAL binding to exactly match the native lib version
# (requirements.txt only pins GDAL>=3.0, so pip can grab a newer
# version than the one apt just installed -> ABI mismatch at import) ---
GDAL_VERSION=$(gdal-config --version)
pip install --no-cache-dir --force-reinstall "GDAL==${GDAL_VERSION}"
# --- check ---
python -c "
import torch
from osgeo import gdal
print('torch', torch.__version__, '| cuda', torch.cuda.is_available())
print('gdal', gdal.__version__, '| GTiff driver:', gdal.GetDriverByName('GTiff') is not None)
"@phdthesis{kasmi2024enhancing,
title={Enhancing the Reliability of Deep Learning Models to Improve the Observability of French Rooftop Photovoltaic Installations},
author={Kasmi, Gabriel},
year={2024},
school={Universit{\'e} Paris sciences et lettres}
}Compute the total estimated installed capacity (kWp) and count of detections matching a set of filters — département, commune, capacity range, and cross-validation across sources (cross_validated) or imagery vintages (min_vintages) — plus a quality_summary for the summed sample. Unlike get_department_capacity_stats, which is a fixed pre-computed département-wide aggregate with no other filters, this tool sums a live filtered subset, up to max_rows detections. Example: "installed capacity in Gironde confirmed by at least two sources" -> dpt="33", cross_validated=true. Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | No | French département code, e.g. "33". | |
| insee | No | INSEE commune code. | |
| max_kwp | No | Maximum estimated installed capacity, in kWp. | |
| min_kwp | No | Minimum estimated installed capacity, in kWp. | |
| max_rows | Yes | Cap on the number of matching detection rows fetched to compute the capacity sum. If the true match count exceeds this, total_kwp is a partial lower bound and `truncated` is true — increase max_rows or narrow the filters (e.g. add dpt or insee) for an exact total. | |
| max_tilt | No | Maximum estimated tilt from horizontal, in degrees. | |
| min_tilt | No | Minimum estimated tilt from horizontal, in degrees. | |
| has_rnb_id | No | true = only detections matched to an RNB building identifier (rnb_id not null); false = only detections without one. | |
| max_azimuth | No | Maximum estimated azimuth, degrees clockwise from true north (180 = south). | |
| max_surface | No | Maximum estimated PV array area, in m². | |
| min_azimuth | No | Minimum estimated azimuth, degrees clockwise from true north (180 = south). | |
| min_surface | No | Minimum estimated PV array area, in m². | |
| max_vintages | No | Maximum number of imagery vintages (e.g. 1 = seen in a single year only). | |
| min_vintages | No | Minimum number of distinct imagery vintages (years) the installation was independently detected in. Use 2+ as a persistence/confidence signal, since a one-off detection in a single vintage is more likely to be a transient artifact. | |
| max_last_seen | No | Upper bound on last_seen imagery year. | |
| min_last_seen | No | Lower bound on last_seen imagery year. | |
| has_frpv_proba | No | true = only detections that have an FRPV comparison (frpv_proba not null); false = only those without one. A null frpv_proba means "no comparison available", not probability 0. | |
| max_first_seen | No | Upper bound on first_seen imagery year. | |
| min_first_seen | No | Earliest imagery year of first detection, lower bound (e.g. 2018). Not an installation date. | |
| min_frpv_proba | No | Minimum frpv_proba. The data contract recommends 0.1 as a precision/recall trade-off. Note: detections with a null frpv_proba (no FRPV comparison available) are excluded when this is set; null does not mean probability 0. | |
| quality_filter | Yes | If true, only include detections identified by 2 OR MORE sources(the `sources` field lists at least two codes, e.g. "0,1" = DeepPVMapper pipeline + FRPV reference, "0,2" = pipeline + OpenStreetMap). Default false: all detections are included, including those found by a single source (typically the automated pipeline alone). | |
| cross_validated | No | Alias of quality_filter, kept for backward compatibility. | |
| sources_include | No | Only include detections present in ALL of these sources. Accepts names or codes, case-insensitive: dpvm/deeppvmapper/kasmi (0), frpv/thebault (1), osm/openstreetmap (2), manual/annotation (3), recall (4). Examples: ["osm"] = detections that are in OpenStreetMap; ["dpvm","frpv"] = present in both DeepPVMapper and FRPV. See get_source_reference for what each source is and where it comes from. | |
| false_positive_status | No | flagged = false_positive is true; not_flagged = false_positive is false; unrecorded = false_positive is null (no status recorded — NOT a confirmed true positive). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does disclose substantive behavior: the dataset is a detection dataset with ~0.6 recall rather than an exhaustive inventory, missing detections do not imply absence of PV, and kwp/surface/tilt/azimuth are model estimates. It also surfaces the max_rows truncation caveat (partial lower bound) and that cross_validated is an alias of quality_filter. It stops short of cost/latency or permissions context, so not a 5.
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?
Front-loaded with the core purpose and the sibling contrast before moving to example, data-quality caveats, and the reference pointer. It is on the long side and partially repeats what the schema already says (quality_filter semantics, cross_validated alias, truncation), which costs it a point, but each sentence carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 24-parameter tool with no output schema and no annotations, the description supplies the essential caveats an agent needs: the detection-vs-inventory framing, recall figure, model-estimate status of key metrics, and the truncation/partial-total behavior. It is reasonably complete, with only minor gaps around result shape and the semantics of the quality_summary it mentions.
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 the baseline is 3, but the description adds meaning beyond the schema by tying filters together into a worked example and clarifying in prose that quality_filter=true means 'identified by 2 or more sources' and that cross_validated is a backward-compat alias. It doesn't re-derive every one of the 24 parameters, which is appropriate given the schema already documents them.
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?
States a specific verb+resource (compute total estimated installed capacity and count of matching detections) and enumerates the filter dimensions that define the subset. It explicitly distinguishes itself from the sibling get_department_capacity_stats (fixed pre-computed aggregate, no filters) versus this tool's live filtered sum, so an agent can route between them without opening a schema.
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?
Gives explicit when-to-use-vs-alternative guidance by contrasting with get_department_capacity_stats, supplies a concrete worked example ("installed capacity in Gironde confirmed by at least two sources" -> dpt="33", cross_validated=true), and names the prerequisite reference tool (get_data_quality_reference) for fitness assessment. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count detections matching a set of filters, exactly, without downloading rows (fast, no row cap). Use this for "how many ..." questions, e.g. "how many installations have an RNB id?" -> has_rnb_id=true; "how many are identified by 2+ sources?" -> quality_filter=true; "how many come from OpenStreetMap?" -> sources_include=[2]. Returns the matching count, the unfiltered registry total and the percentage. Counts are DETECTED systems, not an inventory. Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | No | French département code, e.g. "33". | |
| insee | No | INSEE commune code. | |
| max_kwp | No | Maximum estimated installed capacity, in kWp. | |
| min_kwp | No | Minimum estimated installed capacity, in kWp. | |
| max_tilt | No | Maximum estimated tilt from horizontal, in degrees. | |
| min_tilt | No | Minimum estimated tilt from horizontal, in degrees. | |
| has_rnb_id | No | true = only detections matched to an RNB building identifier (rnb_id not null); false = only detections without one. | |
| max_azimuth | No | Maximum estimated azimuth, degrees clockwise from true north (180 = south). | |
| max_surface | No | Maximum estimated PV array area, in m². | |
| min_azimuth | No | Minimum estimated azimuth, degrees clockwise from true north (180 = south). | |
| min_surface | No | Minimum estimated PV array area, in m². | |
| max_vintages | No | Maximum number of imagery vintages (e.g. 1 = seen in a single year only). | |
| min_vintages | No | Minimum number of distinct imagery vintages (years) the installation was independently detected in. Use 2+ as a persistence/confidence signal, since a one-off detection in a single vintage is more likely to be a transient artifact. | |
| max_last_seen | No | Upper bound on last_seen imagery year. | |
| min_last_seen | No | Lower bound on last_seen imagery year. | |
| has_frpv_proba | No | true = only detections that have an FRPV comparison (frpv_proba not null); false = only those without one. A null frpv_proba means "no comparison available", not probability 0. | |
| max_first_seen | No | Upper bound on first_seen imagery year. | |
| min_first_seen | No | Earliest imagery year of first detection, lower bound (e.g. 2018). Not an installation date. | |
| min_frpv_proba | No | Minimum frpv_proba. The data contract recommends 0.1 as a precision/recall trade-off. Note: detections with a null frpv_proba (no FRPV comparison available) are excluded when this is set; null does not mean probability 0. | |
| quality_filter | Yes | If true, only include detections identified by 2 OR MORE sources(the `sources` field lists at least two codes, e.g. "0,1" = DeepPVMapper pipeline + FRPV reference, "0,2" = pipeline + OpenStreetMap). Default false: all detections are included, including those found by a single source (typically the automated pipeline alone). | |
| cross_validated | No | Alias of quality_filter, kept for backward compatibility. | |
| sources_include | No | Only include detections present in ALL of these sources. Accepts names or codes, case-insensitive: dpvm/deeppvmapper/kasmi (0), frpv/thebault (1), osm/openstreetmap (2), manual/annotation (3), recall (4). Examples: ["osm"] = detections that are in OpenStreetMap; ["dpvm","frpv"] = present in both DeepPVMapper and FRPV. See get_source_reference for what each source is and where it comes from. | |
| breakdown_rnb_id | Yes | If true, also return how many of the matching detections do / do not have an rnb_id (ignores has_rnb_id for this breakdown). | |
| false_positive_status | No | flagged = false_positive is true; not_flagged = false_positive is false; unrecorded = false_positive is null (no status recorded — NOT a confirmed true positive). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does: exactness, the absence of a row cap, the returned values (count, unfiltered registry total, percentage), the quality_filter semantics specific to this server, the alias caveat, and substantive dataset caveats (detection dataset, recall ~0.6, model-estimated kwp/surface/tilt/azimuth). This is unusually rich behavioral disclosure for a mutation-free read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well front-loaded: purpose, usage, return shape, then caveats. The data-quality block is somewhat repetitive — the 'not an exhaustive inventory' point and the 'missing detection' point restate each other, and the recall figure is duplicated in spirit by the pointer to get_data_quality_reference.
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 24-parameter tool with no annotations and no output schema, the description covers what it returns, how the two required parameters behave, the dataset's fitness caveats, and points to the reference tool for the deeper contract. Nothing an agent needs to decide whether to call it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes beyond it by translating concrete questions into concrete parameter values (has_rnb_id=true, quality_filter=true, sources_include=[2]) and by clarifying that quality_filter means 2+ sources in this server specifically. It leaves breakdown_rnb_id and the cross_validated alias to 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?
States a specific verb and resource (count detections) plus a distinguishing capability: exact counting without downloading rows and without a row cap. That contrast implicitly separates it from search_detections and the other list/aggregate siblings, and the opening clause is front-loaded.
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 routes 'how many ...' questions to this tool and gives three worked mappings from natural-language questions to parameters. It also tells the agent to consult get_data_quality_reference before assessing fitness. It never names the row-returning alternative (search_detections) outright, so the negative case is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a snapshot of ongoing community contribution activity on the map: how many corrections are currently pending moderation, their breakdown by action type (add / modify / delete), and the most recent submissions (timestamp, action, target). Submitted free-text comments are intentionally excluded from this tool. This reflects unmoderated, unverified user activity, not the registry itself — do not present it as confirmed detection data.
| Name | Required | Description | Default |
|---|---|---|---|
| recent_limit | Yes | How many of the most recent pending contributions to list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It does this well by stating that comments are intentionally excluded and that the data reflects unmoderated, unverified user activity rather than the authoritative registry. This goes beyond a simple 'get' description. It could still mention that this is a read-only operation with no side effects, but the snapshot framing largely conveys that.
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: the first sentence states the purpose and enumerates the output contents, and the following sentences provide important limitations and usage caveats. There is no filler or redundant information; every sentence contributes to correct invocation and interpretation.
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 one-parameter tool with no output schema, the description provides enough information for an agent to understand what data will be returned and how to interpret it. It clearly lists the three output categories and includes the critical caveat about unverified data. The only notable gap is the lack of an explicit relationship to the area-scoped sibling tool, but this is not essential for basic correctness.
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 only parameter, recent_limit, is already fully documented in the schema with description, default, maximum, and exclusivity constraints. The tool description does not add new parameter semantics, but it does not need to because the schema coverage is 100%. 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 identifies the action ('Get a snapshot') and the resource ('community contribution activity'), and it enumerates the specific outputs: pending correction counts, breakdown by action type, and recent submissions. It also distinguishes this from the registry by emphasizing unmoderated, unverified user activity. However, it does not explicitly differentiate itself from the nearby sibling get_community_activity_in_area, so the distinction is mostly inferable rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context about when to use this tool: it returns unmoderated, unverified contribution activity and explicitly warns not to present it as confirmed detection data. It also notes that free-text comments are intentionally excluded. However, it does not explicitly state when to use this tool instead of a sibling like get_community_activity_in_area or search_detections, so the guidance is more implied than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find pending, unmoderated community contributions relevant to a specific area, to answer "has anyone flagged anything here that is not in the registry yet?" Two independent filters: dpt finds pending edits/deletions (action=modify/delete) targeting existing detections in that département; a full bounding box (min_lon/min_lat/max_lon/max_lat) finds pending new additions (action=add) whose proposed footprint centroid falls inside it. Combine with get_department_capacity_stats / search_detections / get_detections_in_bbox for the confirmed registry picture, and present this separately and clearly as unverified, pending community input — not confirmed detection data. Free-text comments are never included.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | No | Filter pending edits/deletions of EXISTING detections (action=modify or delete) to this département. Does not apply to proposed new additions (action=add), which have no département recorded on the pending item itself — use the bbox parameters for those. | |
| max_lat | No | ||
| max_lon | No | ||
| min_lat | No | ||
| min_lon | No | ||
| scan_limit | Yes | How many recent proposed additions (action=add) to scan for a bbox match. Only relevant when all four bbox parameters are given — there is no server-side spatial index on pending items, so matching is done by fetching this many of the most recent ones and checking their centroid against the box. | |
| recent_limit | Yes | Maximum number of matching items to return per category. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It compensates by explicitly labeling results as pending, unmoderated, unverified community input, and not confirmed detection data. It also discloses that free-text comments are never included and explains the different semantics of dpt-based vs. bbox-based matching. A brief explicit read-only statement would make this fully complete, but the description is already strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: purpose, filter semantics, relationship to confirmed-registry tools, and the critical presentational caveat. The most decision-relevant information is front-loaded. The prose is dense and structured so an agent can act on it without re-reading.
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 7-parameter tool with no annotations and no output schema, the description covers nearly everything needed to call it correctly: filter modes, parameter meanings, spatial-matching approach, and how results should be framed. Minor gaps remain, such as an explicit all-or-none rule for the bbox parameters and any description of the return structure, but these are inferable from the schema and 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?
Schema description coverage is low (43%), and the four bbox parameters are undescribed in the schema. The description compensates by explaining that min_lon/min_lat/max_lon/max_lat define a full bounding box and that matching uses the proposed footprint centroid. It also clarifies that dpt applies only to modify/delete actions and not to additions. The scan_limit and recent_limit parameters are already well documented in the schema, so the prose does not need to repeat them.
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 uses a specific verb and resource: "Find pending, unmoderated community contributions relevant to a specific area." It also gives a concrete motivating question and clearly separates this tool from the confirmed-registry tools named as siblings. The purpose is immediately distinguishable even without inspecting the schema.
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 (to surface unverified pending community input) and explicitly names the confirmed-registry alternatives to combine with. It also states how the two filter modes are used: dpt for pending edits/deletions, bbox for pending additions. The caveat to present results separately and not as confirmed data provides a clear when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the DeepPVMapper/OpenPVMapper registry's documented data-quality characteristics: estimated detection recall, which fields are model-derived estimates vs. structural/observed fields, the source-encoding table, the recommended confidence threshold, confidence signals, and licensing/liability terms. Call this before advising how much to trust a result for a specific use case (e.g. exploratory research vs. a commercial or regulatory decision) — pair it with the quality_summary attached to search_detections / aggregate_detection_capacity results, which reflects the specific query rather than the registry as a whole.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It makes the scope explicit: this returns registry-level documented characteristics, not query-specific quality information, and it is a pure retrieval operation ('Return'). It does not discuss auth, rate limits, or error behavior, but for a zero-parameter read-only reference tool the disclosed scoping is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place: the first sentence lists the return contents, and the second provides actionable usage context. It is front-loaded with the core purpose and avoids repetition of schema or annotation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description is complete: it specifies the full set of returned information, explains when to use it, and distinguishes it from query-specific alternatives. An agent has everything needed to decide whether to invoke this tool and what to expect from it.
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 zero parameters and 100% schema description coverage, so there is no parameter information for the description to add. The baseline of 4 applies because the description appropriately focuses on what the tool returns rather than trying to document nonexistent 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 uses a specific verb ('Return') and identifies the exact resource (the DeepPVMapper/OpenPVMapper registry's documented data-quality characteristics), then enumerates the contents. It is clearly distinct from the sibling tools, which operate on detections, capacity, or community activity rather than registry-level quality metadata.
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 call this tool ('before advising how much to trust a result for a specific use case') and contrasts it with the query-specific quality_summary attached to search_detections / aggregate_detection_capacity results. This gives an agent clear routing guidance relative to its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get installed rooftop-PV capacity (total kWp) and system counts for one or all French départements, from the DeepPVMapper/OpenPVMapper registry. This is a fixed, pre-computed department-wide aggregate with no other filters — use aggregate_detection_capacity instead if you need a filtered subset (e.g. only cross-validated detections). Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | No | French département code, e.g. "33" for Gironde. Omit for all départements. | |
| top_n | No | If set and dpt is omitted, return only the top N départements by installed capacity. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it delivers unusually rich disclosure: fixed pre-computed aggregate with no other filters, ~0.6 recall, model-estimated kwp/surface/tilt/azimuth, and missing detections are not evidence of absence. It omits operational traits like auth/rate limits or response shape, keeping it just short of a 5.
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?
Front-loaded with the core purpose and the alternative, and the data-quality caveats are valuable. However, the sentence about quality_filter=true is not a parameter of this tool and reads as boilerplate, slightly diluting focus.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, alternative, and the caveats an agent needs to interpret a detection-based estimate, which is the main risk here. With no output schema, it only loosely characterizes the return (total kWp and system counts) rather than its structure, leaving a small gap.
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 both dpt and top_n are already fully documented, giving a baseline of 3. The description adds only the framing that the aggregate is fixed and filterless, which does not extend meaning for either parameter.
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?
States a specific verb and resource (installed rooftop-PV capacity and system counts by French département) and names the exact sibling it is not (aggregate_detection_capacity for filtered subsets). An agent can distinguish it from siblings without opening schemas.
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 gives the when-not: 'use aggregate_detection_capacity instead if you need a filtered subset (e.g. only cross-validated detections).' It also directs the agent to get_data_quality_reference before assessing fitness, so routing guidance is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-call profile of a département: installed capacity and national rank, yearly trend (by first-seen imagery year), source mix, share identified by 2+ sources, and share matched to an RNB building id. Cross-references the pre-computed department statistics with live counts. Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | Yes | French département code, e.g. "33". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses the estimated recall (~0.6), warns that a missing detection does not mean no installation exists, flags kwp/surface/tilt/azimuth as model estimates rather than surveyed values, and explains that the profile blends pre-computed stats with live counts. These are exactly the caveats an agent needs before presenting this data.
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?
Front-loaded with what the profile returns, then caveats, then the pointer to the reference tool. Every sentence carries information, though the quality_filter aside is only loosely tied to this tool since it has no such parameter, which adds mild length.
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 no output schema and no annotations, the description compensates by enumerating the returned fields and their caveats, and it routes the agent to get_data_quality_reference for deeper assessment. Nothing an agent needs to invoke and correctly interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'dpt' parameter is already documented as a French département code in the schema. The description adds no syntax, format, or edge-case guidance beyond what the schema states, so the baseline of 3 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?
States a specific verb and resource ('one-call profile of a département') and enumerates the exact contents: capacity and national rank, yearly trend, source mix, 2+ source share, RNB match share. The composite framing makes it distinguishable from narrow siblings like get_department_capacity_stats and get_department_yearly_stats without opening their schemas.
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?
Gives a clear routing instruction ('Call get_data_quality_reference for the full picture before assessing fitness for a specific use case') and clarifies the meaning of the 2+ source share in this server. It stops short of explicitly stating when to prefer this tool over the single-stat department siblings, so it is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get yearly system counts and capacity by département, based on first-seen imagery year. Useful for tracking apparent PV deployment growth over time. Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | No | French département code, e.g. "33". Omit for all départements. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses the dataset is detection-based with estimated recall ~0.6, warns that missing detections are not evidence of absence, and flags kwp/surface/tilt/azimuth as model estimates rather than surveyed values. It also explains the quality_filter=true semantics (2+ source detections), which is server-level behavior not captured in the schema. It omits response shape and any pagination/aggregation granularity.
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?
Front-loaded with the core purpose before the caveats, and each sentence adds distinct value (data quality, recall, estimate caveat, quality_filter, pointer to reference tool). It is on the long side and the get_data_quality_reference pointer appears alongside an already-implied caveat, so it is slightly more verbose than needed.
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 one-optional-parameter read tool with no output schema and no annotations, the description supplies the caveats an agent needs to interpret results responsibly (detection vs inventory, model estimates, recall). It could say more about what the returned counts/capacity look like and at what granularity, but the critical fitness-for-use context is present.
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 single optional dpt parameter is fully documented in the schema, including the 'omit for all' behavior. The description adds no syntax or format detail about dpt, so baseline 3 applies; the 'based on first-seen imagery year' phrasing adds temporal framing but no parameter-level meaning.
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?
States a specific verb and resource (yearly system counts and capacity by département) and pins the temporal basis to first-seen imagery year, which is a meaningful scope detail. It does not explicitly differentiate itself from the closest sibling, get_department_capacity_stats, so the agent must infer the distinction between 'yearly stats' and 'capacity stats'.
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?
Gives a clear use case (tracking apparent PV deployment growth over time) and a prerequisite workflow: consult get_data_quality_reference before judging fitness for a specific use case. It stops short of stating when to prefer this over get_department_capacity_stats or get_department_profile, so the routing guidance is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full record of one detection by id: technical characteristics (surface, kwp, tilt, azimuth — model estimates), imagery years, sources decoded into plain labels, frpv_proba, false-positive flag, rnb_id and location codes, plus simple confidence signals. Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Registry identifier of the detection (the `id` field). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses that kwp/surface/tilt/azimuth are model estimates rather than surveyed values, states the dataset's estimated recall (~0.6), warns that a missing detection does not mean no PV exists, and explains the quality_filter semantics via source_encoding. This is unusually rich disclosure for a read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and mostly efficient, but the model-estimate caveat is stated twice ('surface, kwp, tilt, azimuth — model estimates' and again 'kwp, surface, tilt and azimuth are model estimates, not surveyed values'), which is redundant repetition.
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 no output schema, the description correctly enumerates the returned fields (imagery years, decoded sources, frpv_proba, false-positive flag, rnb_id, location codes, confidence signals) and pairs them with data-quality caveats. An agent has everything needed to interpret and trust the result.
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 there is only one parameter, whose schema description already defines it as the registry identifier. The description says 'by id' but adds no format, range, or lookup semantics beyond the schema, so the baseline 3 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?
Opens with a specific verb+resource ('Get the full record of one detection by id') and enumerates exactly what the record contains, which cleanly separates it from siblings like search_detections, count_detections, and get_detections_in_bbox. An agent can identify this as the single-record fetch without opening the schema.
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?
Gives clear context (single-detection lookup) and routes the agent to a sibling: 'Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.' However it never states when to choose this over search_detections, nor any exclusion conditions, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get rooftop-PV detections within a geographic bounding box (WGS84 lon/lat), including footprint geometry. Intended for map-style spatial queries over a small area. Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| max_lat | Yes | ||
| max_lon | Yes | ||
| min_lat | Yes | ||
| min_lon | Yes | ||
| max_count | Yes | Maximum number of detections to return (max 500 here; the underlying API defaults to 2000, capped lower to keep responses manageable for an LLM). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does substantial work: it discloses estimated recall (~0.6), warns that absence of a detection is not absence of PV, flags kwp/surface/tilt/azimuth as model estimates, and explains what quality_filter=true actually filters on. It omits operational traits such as truncation behavior when max_count is hit and any auth/rate constraints.
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?
Front-loads the core action and return value, then layers the data-quality caveats in short, information-dense sentences that each add distinct value. It is on the long side for a five-parameter tool, but no sentence is pure filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description should ideally describe the return shape and truncation behavior; it only hints at geometry via 'including footprint geometry'. The data-quality caveats are thorough, but an agent still cannot tell what a truncated result looks like or how to page through a larger area.
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 20%, so the description must compensate; it does add the WGS84 lon/lat coordinate convention and the geographic extent semantics, which the schema alone does not state. However, four of five parameters (min_lon/min_lat/max_lon/max_lat) remain undocumented, and the description discusses a quality_filter parameter that does not appear in the input schema at all, which could mislead an agent about available inputs.
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?
States a specific verb and resource ('Get rooftop-PV detections') plus the exact spatial scope ('within a geographic bounding box (WGS84 lon/lat)') and what is returned ('including footprint geometry'). The phrase 'map-style spatial queries over a small area' separates it from the sibling search_detections and count_detections, which an agent can distinguish without opening any schema.
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?
Gives a clear usage context ('Intended for map-style spatial queries over a small area') and a prerequisite-style pointer to get_data_quality_reference before assessing fitness. It stops short of explicit when-not-to-use guidance or naming which sibling to prefer for non-spatial or aggregate queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Completeness report: for each optional field of the registry (rnb_id, frpv_proba, false_positive, false_positive_source), how many detections have it filled in and what percentage. Answers "how many installations have an RNB id / an FRPV comparison / a false-positive flag?" in one call, for France or one département. For a single filtered count use count_detections instead. Null means "not available/recorded", never "0" or "confirmed ok". Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | No | French département code. Omit for all of France. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it defines the null convention ('not available/recorded', never '0' or 'confirmed ok'), discloses the dataset's recall limitation (~0.6) and that absence of a detection is not absence of an installation, flags kwp/surface/tilt/azimuth as model estimates, and explains quality_filter's 2+-source semantics. These are substantive behavioral facts an agent could not infer elsewhere.
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?
Purpose and scope are front-loaded and every sentence is informative, but the paragraph is dense and includes a data-quality aside (kwp, surface, tilt, azimuth model estimates) that concerns fields this tool does not report on. Slightly overstuffed rather than wasteful.
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 no-annotation, no-output-schema, single-parameter tool, the description covers what is returned (counts and percentages per field), how to read nulls, geographic scope, and pointers to the related reference tools. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents the single dpt parameter at 100% coverage, so the baseline is 3. The description reinforces the scoping ('for France or one département') and the omit-for-all-of-France behavior, but adds no format or validation detail beyond the schema, so no credit 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?
States a specific verb+resource: a completeness report giving, for each optional registry field (rnb_id, frpv_proba, false_positive, false_positive_source), how many detections have it filled and at what percentage. It names the sibling it is not (count_detections) and scopes the geography (France or one département), so an agent can distinguish it from count_detections, get_field_distribution, and get_source_breakdown.
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?
Gives an explicit trigger question ('how many installations have an RNB id / an FRPV comparison / a false-positive flag?') and an explicit exclusion routing to count_detections for a single filtered count. It also advises calling get_data_quality_reference before judging fitness, so when-to-use, when-not, and a prerequisite are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Histogram of a numeric field (kwp, surface, tilt, azimuth, n_vintages, first_seen, last_seen) with exact counts per bin, for France or one département. Answers "how are installations distributed by size / tilt / orientation / year?". kwp, surface, tilt and azimuth are model estimates. first_seen/last_seen are imagery years, not installation dates. Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | No | French département code. Omit for all of France. | |
| field | Yes | Numeric field to describe. | |
| max_year | No | For first_seen / last_seen: last year to count. | |
| min_year | No | For first_seen / last_seen: first year to count. | |
| bin_edges | No | Custom ascending bin edges; each bin is [edge_i, edge_i+1) and the last is closed. Ignored for first_seen / last_seen, which are counted per year (use min_year / max_year). | |
| quality_filter | Yes | If true, restrict to detections identified by 2+ sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses that kwp/surface/tilt/azimuth are model estimates rather than surveyed values, that first_seen/last_seen are imagery years and not installation dates, that the dataset is a detection dataset with ~0.6 recall, and that a missing detection does not imply no PV exists. It also spells out the exact semantics of quality_filter=true (2+ sources) and cross-references source_encoding.
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 purpose and scope are front-loaded, and most sentences carry distinct caveats. However, the model-estimate warning for kwp/surface/tilt/azimuth is stated twice in near-identical form ('are model estimates' then 'are model estimates, not surveyed values'), which is wasted repetition in an otherwise tight structure.
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 no output schema and no annotations, the description still conveys the return shape (exact counts per bin), the geographic scope, the year-range handling, and the key fitness-for-use caveats, plus a pointer to the quality reference. It is nearly complete, though it could say more about bin behavior or expected response structure for first_seen/last_seen.
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 the baseline is 3. The description adds genuine semantic meaning beyond the schema: it flags which enum values are model estimates, interprets first_seen/last_seen as imagery years, and reinforces the 2+ source meaning of quality_filter. It does not, however, clarify dpt format or bin_edges behavior beyond what the schema already says.
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 opening clause gives a specific verb+resource+output shape: a histogram of a named numeric field with exact counts per bin, scoped to France or a single département. The enumerated field list and the quoted user question make it unmistakable against siblings like get_field_coverage or get_department_yearly_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the question the tool answers ('how are installations distributed by size / tilt / orientation / year?') and routes the agent to get_data_quality_reference before assessing fitness for a use case. It gives no explicit when-not-to-use or a named alternative for the same job, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Field-by-field documentation of a detection record: type, unit, nullability, whether it is observed or a model estimate, how to read it, and which tool filters or reports it. Call this when the user asks what a field means or how reliable it is.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does describe the shape of what is returned (per-field metadata, semantics, reliability). It is a static, zero-param reference lookup so risk context is minimal, but it doesn't state whether it covers all fields at once or how the output is organized.
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 tight sentences: the first defines content, the second defines when to call. The trigger is front-loaded after the content summary with zero filler, and every clause 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 zero-param reference tool with no output schema, the description supplies enough to call it correctly and know what comes back. Minor gap: it doesn't clarify that the entire field catalog is returned rather than a subset.
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?
Zero parameters, so the schema has nothing to document and the baseline is 4. The description correctly signals a parameterless, whole-reference lookup, though it doesn't explicitly note that no field argument is 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?
States a specific verb (get) and resource (field reference) and enumerates exactly what the documentation covers: type, unit, nullability, observed vs. model estimate, how to read it, and which tool filters/reports it. It is clearly distinguishable from siblings like get_field_coverage or get_field_distribution, which return data rather than documentation.
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 an explicit trigger: call this when the user asks what a field means or how reliable it is. That is clear context for invocation, but it names no alternatives or exclusions (e.g., get_source_reference or get_data_quality_reference), leaving the boundary between sibling reference tools to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Break down detections by source code (0=DPVM pipeline, 1=FRPV reference, 2=OSM, 3=manual correction, 4=recall sample), for one département or all of France, with human-readable labels. A detection can carry several sources, so per-source counts overlap and do not add up to the total. Also returns how many detections are identified by 2+ sources (the meaning of quality_filter). Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | No | French département code, e.g. "33". Omit for all of France. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so richly: overlapping per-source counts that do not sum to the total, the meaning of quality_filter, estimated recall ~0.6, and the model-estimated nature of kwp/surface/tilt/azimuth. These are exactly the caveats an agent needs to avoid misinterpreting results.
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?
Front-loaded with the purpose, then layered caveats, all of which earn their place. Minor redundancy: get_data_quality_reference is referenced twice (once for source_encoding, once as a general recommendation), which slightly dilutes the ending.
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 single-parameter aggregation tool with no output schema, the description is complete: it explains the output categories, the non-additive nature of counts, the extra 2+ source figure, and the dataset's quality limits. An agent has everything needed to call it and interpret the result responsibly.
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 single parameter, so the baseline is 3; the schema already documents dpt and the omit-for-all-France behavior. The description reinforces the scope but adds no syntax or format detail beyond the schema, so no lift 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?
States a specific verb+resource (break down detections by source code) and immediately defines the scope: one département or all of France. The parenthetical decoding of the source codes lets an agent understand the output domain without opening any other tool, and it is clearly distinct from siblings like get_source_reference or get_field_distribution.
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?
Gives clear usage context (source counts overlap, quality_filter semantics) and explicitly routes the agent to get_data_quality_reference before assessing fitness. It stops short of naming when NOT to use it versus siblings such as count_detections or get_source_reference, so it is strong context without full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain the data sources behind the registry's sources field: for each source, its code, short key, name, accepted aliases, and where the data comes from (with references: code, thesis, papers). Use it for questions like "what is FRPV?", "where does the OSM data come from?", "what is a manual correction?". The sources field answers "where do we have this installation?": each listed code is a dataset or process that contains it. Example: "0,1" = present in both DeepPVMapper (DPVM) and FRPV; "0,2" = present in DeepPVMapper and OpenStreetMap.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | A source name, alias or code (e.g. "frpv", "OpenStreetMap", "kasmi", "3"). Omit to list all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden and does well by explaining that the tool returns codes, short keys, names, aliases, and provenance references. It implies a read-only explanatory lookup, but does not explicitly confirm side-effect behavior or access constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and appropriately sized for a reference lookup tool. It uses multiple examples effectively, though some of the explanatory example content is slightly repetitive.
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 one-parameter reference tool with no output schema, the description explains both the purpose and the shape of the returned information, including source codes, aliases, and references. An agent has enough context to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter is already documented in the schema, including the example values and omission behavior. The description mostly repeats those examples and does not add substantial new parameter semantics 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 states a specific verb and resource: it explains the data sources behind the registry's `sources` field and enumerates the source metadata it returns. It is clear what the tool does, though it does not explicitly name a sibling tool it should be chosen over.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete question examples such as "what is FRPV?" and "where does the OSM data come from?", which clearly indicates when to use the tool. It lacks explicit exclusions or named alternatives, so the guidance is strong but not fully complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
START HERE. Call this first when the user is new, asks what this server can do, or asks a vague question about DeepPVMapper. Returns a plain-language introduction, example questions, which tool answers which kind of question, a glossary and the main caveats. Reply to the user in their own language.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the return payload in detail plus an interaction rule ('Reply to the user in their own language'). It stops short of stating there are no side effects, though 'Returns' makes the read-only nature clear by implication.
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 filler, and the most important instruction ('START HERE. Call this first...') is front-loaded before the content enumeration. Every clause 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?
With no output schema, the description compensates by listing the five categories of content the tool returns, so an agent knows what to expect without a schema. Complete for a zero-parameter onboarding tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4 per the rubric. There is nothing for the description to disambiguate, and it correctly does not invent parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with an imperative 'START HERE' and then enumerates exactly what the tool returns: a plain-language introduction, example questions, a tool-to-question mapping, a glossary, and caveats. This is unmistakably distinct from data-retrieval siblings like get_detections_in_bbox or count_detections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit trigger conditions — 'when the user is new, asks what this server can do, or asks a vague question about DeepPVMapper' — which is precisely the routing decision an agent needs against 16 specialized sibling tools. When-not is implied by the specificity of those triggers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search individual rooftop-PV detections by département, commune (INSEE code), estimated capacity range, and/or cross-validation confidence (min_vintages, cross_validated). Returns a bounded list of detection records plus a quality_summary for the returned sample (use get_detections_in_bbox instead for map/spatial queries with geometry). Data quality note: this is a detection dataset, not an exhaustive inventory (estimated recall ~0.6). A missing detection does not mean no PV installation exists there. kwp, surface, tilt and azimuth are model estimates, not surveyed values. In this server, quality_filter=true keeps only detections identified by 2 or more sources (see source_encoding in get_data_quality_reference). Call get_data_quality_reference for the full picture before assessing fitness for a specific use case.
| Name | Required | Description | Default |
|---|---|---|---|
| dpt | No | French département code, e.g. "33". | |
| insee | No | INSEE commune code. | |
| limit | Yes | Maximum number of records to return (max 200). | |
| max_kwp | No | Maximum estimated installed capacity, in kWp. | |
| min_kwp | No | Minimum estimated installed capacity, in kWp. | |
| max_tilt | No | Maximum estimated tilt from horizontal, in degrees. | |
| min_tilt | No | Minimum estimated tilt from horizontal, in degrees. | |
| has_rnb_id | No | true = only detections matched to an RNB building identifier (rnb_id not null); false = only detections without one. | |
| max_azimuth | No | Maximum estimated azimuth, degrees clockwise from true north (180 = south). | |
| max_surface | No | Maximum estimated PV array area, in m². | |
| min_azimuth | No | Minimum estimated azimuth, degrees clockwise from true north (180 = south). | |
| min_surface | No | Minimum estimated PV array area, in m². | |
| max_vintages | No | Maximum number of imagery vintages (e.g. 1 = seen in a single year only). | |
| min_vintages | No | Minimum number of distinct imagery vintages (years) the installation was independently detected in. Use 2+ as a persistence/confidence signal, since a one-off detection in a single vintage is more likely to be a transient artifact. | |
| max_last_seen | No | Upper bound on last_seen imagery year. | |
| min_last_seen | No | Lower bound on last_seen imagery year. | |
| has_frpv_proba | No | true = only detections that have an FRPV comparison (frpv_proba not null); false = only those without one. A null frpv_proba means "no comparison available", not probability 0. | |
| max_first_seen | No | Upper bound on first_seen imagery year. | |
| min_first_seen | No | Earliest imagery year of first detection, lower bound (e.g. 2018). Not an installation date. | |
| min_frpv_proba | No | Minimum frpv_proba. The data contract recommends 0.1 as a precision/recall trade-off. Note: detections with a null frpv_proba (no FRPV comparison available) are excluded when this is set; null does not mean probability 0. | |
| quality_filter | Yes | If true, only include detections identified by 2 OR MORE sources(the `sources` field lists at least two codes, e.g. "0,1" = DeepPVMapper pipeline + FRPV reference, "0,2" = pipeline + OpenStreetMap). Default false: all detections are included, including those found by a single source (typically the automated pipeline alone). | |
| cross_validated | No | Alias of quality_filter, kept for backward compatibility. | |
| sources_include | No | Only include detections present in ALL of these sources. Accepts names or codes, case-insensitive: dpvm/deeppvmapper/kasmi (0), frpv/thebault (1), osm/openstreetmap (2), manual/annotation (3), recall (4). Examples: ["osm"] = detections that are in OpenStreetMap; ["dpvm","frpv"] = present in both DeepPVMapper and FRPV. See get_source_reference for what each source is and where it comes from. | |
| false_positive_status | No | flagged = false_positive is true; not_flagged = false_positive is false; unrecorded = false_positive is null (no status recorded — NOT a confirmed true positive). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does it well: it warns the dataset is a detection set with ~0.6 recall, that a missing detection is not evidence of no PV, that kwp/surface/tilt/azimuth are model estimates, and that it returns a quality_summary alongside a bounded record list. It does not cover auth, rate limits, or pagination behavior, so it stops short of a 5.
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?
Front-loaded with the core purpose and filters, then the routing alternative, then a compact data-quality caveat block. Every sentence earns its place, though the final pointer sentence is a slightly soft close and the caveat block is on the long side.
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 24-parameter tool with no output schema, the description covers the return shape at a high level (bounded record list plus quality_summary) and supplies the caveats an agent needs to interpret results honestly. It is close to complete; it could say more about how limit interacts with the quality_summary and whether results are ordered or paginated.
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 the baseline is 3, but the description adds interpretive framing beyond the schema: it groups the filters into semantic families and explains how quality_filter relates to the 2-plus-source rule and to cross_validated. That helps an agent choose filter values rather than merely pass them through.
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?
States a specific verb and resource ('Search individual rooftop-PV detections') and enumerates the discriminating filter families (département, INSEE commune, capacity range, cross-validation confidence). It also explicitly names the sibling it is not, get_detections_in_bbox, for spatial queries, so an agent can separate the two without opening either schema.
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?
Gives an explicit alternative and the condition that selects it ('use get_detections_in_bbox instead for map/spatial queries with geometry'), and routes the agent to get_data_quality_reference before assessing fitness. It also frames min_vintages/cross_validated as confidence-tuning levers, so the when-to-use surface is complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0aggregate_detection_capacitycount_detectionsget_community_activityget_community_activity_in_areaget_data_quality_referenceget_department_capacity_statsget_department_profileget_department_yearly_statsget_detection_detailsget_detections_in_bboxget_field_coverageget_field_distributionget_field_referenceget_source_breakdownget_source_referenceget_startedsearch_detectionsScored across 17 tools
Most tools have clearly distinct query targets, and descriptions explicitly cross-reference alternatives ('use aggregate_detection_capacity instead if...', 'use get_detections_in_bbox for spatial queries'). The main risk is the cluster of reference tools (get_data_quality_reference, get_field_reference, get_source_reference) and the department-level tools (get_department_capacity_stats, get_department_yearly_stats, get_department_profile), which overlap somewhat but are adequately differentiated in text.
Every tool follows a consistent snake_case verb_noun pattern (get_*, search_*, aggregate_*, count_*), with the domain noun consistently indicating the resource or scope (detection, department, field, source, community). No mixed conventions or casing inconsistencies.
17 tools is on the heavier end but each earns its place across distinct axes: entry/help, references, single-record lookup, filtered search, spatial search, counting, aggregation, distributions, coverage, and community activity. A couple of tools (e.g. get_department_profile) could arguably be folded into others, keeping it just short of ideal.
The read-only query surface is comprehensive: introduction/help, quality metadata, field and source references, single-record detail, filtered counts and searches, spatial bbox queries, department aggregations and trends, field distributions and coverage, plus unmoderated community activity. The only apparent gap is the absence of any write/contribution tool (e.g. submitting or moderating a correction), though this may be intentionally out of scope.
Geospatial AI MCP server — satellite imagery, embeddings, weather, GNS governance
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Keyless open data for 84 German cities: 12 lean read-only MCP tools covering 67 data types.
Natural-language queries over a verified emissions knowledge graph, plus standards validation
