Skip to main content
Glama

TerraLab

by ai.terra-lab
OverviewDiscussionsAdmin

Extract open map data for an area

extract_open_data
Read-onlyIdempotent

Use this when the user wants map data or GIS layers for a place or an area anywhere in the world, such as the data of a city, a town, a neighbourhood or a site: buildings, roads, addresses, points of interest (shops, schools, pharmacies), land use, waterways, water areas, railways, transit stops, power lines, protected areas, administrative divisions and boundaries, places or routes. The area is a place, a place with a radius, or a bbox. Returns the count, sample attributes, a map and a file (GeoJSON, KML, Shapefile zip or CSV) with its licence, ready for QGIS. One extract holds at most 20,000 features: for a town centre use a radius of about 1 km, for dense cities less. For one kind of place (pharmacies, schools, supermarkets) or land (forest, vineyards), set kind: the limit then counts that kind only, so a whole city usually fits. For administrative boundaries (a commune, the departments of a region, a country) use divisions with level and the place name, without a radius. One theme per call: extract the layers the user asks for; when they ask for the data of a place without naming a layer, or what data exists for a project, name the useful themes and let them choose before extracting several. Data: Overture Maps and OpenStreetMap. Never use the user's current location unless they type it. Give the place as the user names it (place name, address or coordinates): this tool locates it, so find_places is not needed first. Download links build their file when opened; no file is saved. Never pass these links to open_gis_file: list every format the user needs in formats, in this one call.

Input Schema

NameRequiredDescriptionDefault
areaYesThe area: a bbox, or a place (name, address or coordinates) with an optional radius in metres. The place the user asks about, not the user's own location.
kindNoKeep only some kinds of feature, matched against their OpenStreetMap tag value in English: pharmacy, school, supermarket, restaurant, hospital, farmland, forest, vineyard. One kind, or several in one call (["forest", "meadow", "grass"]). Leave out for all of the theme.
levelNoFor the divisions theme: the administrative level to keep. region = French région, US state, German Land; county = French département, US county; municipality = commune, town or city. With a named place, a division of that name at this level is returned alone, and lower levels are kept only inside the named place ("the departments of Brittany": place Brittany, level county).
themeYesThe data layer.
formatsNoDownload formats. A GeoPackage is always included.

Output Schema

NameRequiredDescriptionDefault
codeNoError code, on errors only.
hintNoWhat to do next, on errors only.
messageNoError message, on errors only.
sourcesNoData sources and licences of the result.
downloadsNoDownload links; each builds its file when opened.
truncatedNo
totalFoundNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / examples
      Previous value: -[
-  {
-    "area": {
-      "bbox": [
-        2.34,
-        48.857,
-        2.343,
-        48.859
-      ]
-    },
-    "formats": [
-      "shapefile"
-    ],
-    "theme": "buildings"
-  },
-  {
-    "area": {
-      "place": "Annecy",
-      "radius_m": 500
-    },
-    "kind": "pharmacy",
-    "theme": "pois"
-  }
-]New value: +[
+  {
+    "area": {
+      "bbox": [
+        2.34,
+        48.857,
+        2.343,
+        48.859
+      ]
+    },
+    "formats": [
+      "shapefile"
+    ],
+    "theme": "buildings"
+  },
+  {
+    "area": {
+      "place": "Annecy",
+      "radius_m": 500
+    },
+    "kind": "pharmacy",
+    "theme": "pois"
+  },
+  {
+    "area": {
+      "place": "Bretagne, France"
+    },
+    "formats": [
+      "shapefile"
+    ],
+    "level": "county",
+    "theme": "divisions"
+  }
+]
    • changedInput schema / properties / formats / description
      Previous value: -"Download formats."New value: +"Download formats. A GeoPackage is always included."
    • changedInput schema / properties / formats / items / enum
      Previous value: -[
-  "geojson",
-  "kml",
-  "shapefile",
-  "csv"
-]New value: +[
+  "geojson",
+  "kml",
+  "shapefile",
+  "csv",
+  "geopackage"
+]
    • addedInput schema / properties / level
      Added value: +{
+  "description": "For the divisions theme: the administrative level to keep. region = French région, US state, German Land; county = French département, US county; municipality = commune, town or city. With a named place, a division of that name at this level is returned alone, and lower levels are kept only inside the named place (\"the departments of Brittany\": place Brittany, level county).",
+  "enum": [
+    "country",
+    "region",
+    "county",
+    "municipality"
+  ],
+  "type": "string"
+}
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive and open-world, but the description adds material context beyond them: the hard 20,000-feature cap with sizing heuristics, that download links build the file when opened and no file is saved, and the underlying data sources (Overture Maps and OpenStreetMap). These are exactly the operational traits an agent cannot infer from structured fields.

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 with the when-to-use trigger and packed with useful detail, with essentially no filler sentences. It is a single dense block, though, so the many distinct instructions (sizing, theme choice, link handling, fixed place input) would be easier to scan if grouped rather than run together.

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?

For a five-parameter, nested-area, enum-heavy tool with an output schema, the description covers everything an agent needs: input form for area, how to constrain by kind or level, size limits, licensing/format output, and the cross-tool handoff rules. Nothing operational is left unstated.

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

Parameters5/5

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning: it explains how to size radius_m ('about 1 km' for a town centre, less for dense cities), that kind filters against English OSM tag values and also lifts the feature limit to that kind only, how level works with a named place, and that all needed formats must be requested in a single call.

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

Purpose5/5

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

States a specific verb (extract) and resource (map data / GIS layers for a place or area anywhere in the world) and enumerates the themes covered, so an agent knows exactly what it produces. It also distinguishes itself from siblings by name (find_places not needed, never pass links to open_gis_file), removing ambiguity about which tool to pick.

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?

Explicit routing rules: use divisions with level and a place name (no radius) for administrative boundaries; set kind for a single feature type; one theme per call; when the user names no layer, present themes and let them choose before extracting several. It also gives negative guidance ('Never use the user's current location unless they type it', 'Never pass these links to open_gis_file').

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

All TerraLab 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