ThinAir Geo

explore

Read-onlyIdempotent

BROWSING / DISCOVERY search — administrative places (cities, neighbourhoods, boroughs, counties, regions) near a location. Use this when the user is exploring a REGION rather than looking for a specific category. Supports population filtering ('cities > 100k'), ranking by significance or distance, and layer filtering (locality / neighbourhood / borough / county / region). Venues, addresses and streets are NOT served here — for venues and POI categories (gas, food, charging, etc.) use search_places instead. Each result carries its distance in the caller's units and a bearing from the center.

Input Schema

TableJSON Schema

Name	Required	Description
`lat`	No	Latitude of center point
`lon`	No	Longitude of center point
`size`	No	Max results (default 10, max 50)
`sort`	No	Ranking basis. Default `population` — significance (population where the source has it) with distance as the tiebreak. `distance` is nearest first; `combined` blends population against a distance decay. The basis applied is echoed in meta.ranking.
`units`	No	Units for a bare numeric `radius`: miles (default) or kilometers. Accepts the aliases mi, mile, imperial (miles) and km, kilometer, kilometre, kilometres, metric (kilometers), any case; echoed as miles\|kilometers. Ignored when `radius` already carries a unit suffix; a contradicting pair is rejected. Does not supply a radius on its own (the default is per layer — 150 km for locality/county/region, 25 km for neighbourhood/borough; tightest wins when mixed) but selects the display unit of the meta.radius / meta.units echo.
`layers`	No	Comma-separated administrative layers: locality (default), neighbourhood, borough, county, region. venue, address, street and unknown names are rejected with a structured invalid_layer error — use search_places for venues. Radius policy is per layer: locality/county/region default 150 km and cap at 500 km; neighbourhood/borough default 25 km and cap at 100 km; a mixed request takes the tightest default and cap. With several layers, `size` is split evenly between them (remainder to the first) so one dense layer cannot flood the result.
`radius`	No	Search radius — e.g. radius: 30, units: 'miles'. Bare numbers are miles unless units is set; kilometers via units or a km suffix ('50km'); aliases mi/km/imperial/metric. A value carrying its own unit suffix ('50km', '30mi') is also accepted for compatibility and its suffix wins. Per-layer policy: locality/county/region default 150 km (93.206 mi) and cap at 500 km (~310 mi); neighbourhood/borough default 25 km (15.534 mi) and cap at 100 km (~62 mi); a request naming several layers takes the tightest default and cap among them. Numeric values above 500 fail input validation before the tool runs; a string form over the maximum ('600km') or an in-range number that is over the cap once read as miles (e.g. 400, or 400 with units 'miles' — 644 km) returns a structured radius_exceeds_max error naming the governing cap instead of results.
`location`	No	Center point address or 'lat,lon'
`min_population`	No	Minimum population filter, applied JS-side to whichever layers are served (locality, neighbourhood, borough, county, region).
`boundary_country`	No	ISO country code to restrict results (alpha-2 or alpha-3)

Output Schema

TableJSON Schema

Name	Required	Description
`meta`	No
`items`	No
`geojson`	No
`metrics`	No
`summary`	No	Map of scalar facts the LLM should surface verbatim
`display_hint`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedSep 7, 2026

changedInput schema / properties / layers / description

Previous value: -"Comma-separated: venue, address, street, locality, neighbourhood (default: locality)"New value: +"Comma-separated administrative layers: locality (default), neighbourhood, borough, county, region. venue, address, street and unknown names are rejected with a structured invalid_layer error — use search_places for venues. Radius policy is per layer: locality/county/region default 150 km and cap at 500 km; neighbourhood/borough default 25 km and cap at 100 km; a mixed request takes the tightest default and cap. With several layers, `size` is split evenly between them (remainder to the first) so one dense layer cannot flood the result."

changedInput schema / properties / min_population / description

Previous value: -"Minimum population filter for locality results"New value: +"Minimum population filter, applied JS-side to whichever layers are served (locality, neighbourhood, borough, county, region)."

changedInput schema / properties / radius / description

Previous value: -"Search radius — e.g. radius: 30, units: 'miles'. Bare numbers are miles unless units is set; kilometers via units or a km suffix ('50km'); aliases mi/km/imperial/metric. A value carrying its own unit suffix ('50km', '30mi') is also accepted for compatibility and its suffix wins. Default 150 km (93.206 mi), maximum 500 km (~310 mi). Numeric values above 500 fail input validation before the tool runs; a string form over the maximum ('600km') or an in-range number that is over the cap once read as miles (e.g. 400, or 400 with units 'miles' — 644 km) returns a structured radius_exceeds_max error instead of results."New value: +"Search radius — e.g. radius: 30, units: 'miles'. Bare numbers are miles unless units is set; kilometers via units or a km suffix ('50km'); aliases mi/km/imperial/metric. A value carrying its own unit suffix ('50km', '30mi') is also accepted for compatibility and its suffix wins. Per-layer policy: locality/county/region default 150 km (93.206 mi) and cap at 500 km (~310 mi); neighbourhood/borough default 25 km (15.534 mi) and cap at 100 km (~62 mi); a request naming several layers takes the tightest default and cap among them. Numeric values above 500 fail input validation before the tool runs; a string form over the maximum ('600km') or an in-range number that is over the cap once read as miles (e.g. 400, or 400 with units 'miles' — 644 km) returns a structured radius_exceeds_max error naming the governing cap instead of results."

changedInput schema / properties / sort / description

Previous value: -"Sort mode (default: combined)"New value: +"Ranking basis. Default `population` — significance (population where the source has it) with distance as the tiebreak. `distance` is nearest first; `combined` blends population against a distance decay. The basis applied is echoed in meta.ranking."

changedInput schema / properties / units / description

Previous value: -"Units for a bare numeric `radius`: miles (default) or kilometers. Accepts 'mi'/'km'/'imperial'/'metric' as aliases (any case), echoed as miles|kilometers. Ignored when `radius` already carries a unit suffix; a contradicting pair is rejected. Does not supply a radius on its own (the default 150 km applies) but selects the display unit of the meta.radius / meta.units echo."New value: +"Units for a bare numeric `radius`: miles (default) or kilometers. Accepts the aliases mi, mile, imperial (miles) and km, kilometer, kilometre, kilometres, metric (kilometers), any case; echoed as miles|kilometers. Ignored when `radius` already carries a unit suffix; a contradicting pair is rejected. Does not supply a radius on its own (the default is per layer — 150 km for locality/county/region, 25 km for neighbourhood/borough; tightest wins when mixed) but selects the display unit of the meta.radius / meta.units echo."

addedOutput schema / properties / items / items / properties / bearing

Added value: +{
+  "maximum": 359,
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / items / items / properties / distance
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / items / items / properties / distance_unit

Added value: +{
+  "enum": [
+    "miles",
+    "kilometers"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / meta / properties / layers

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / meta / properties / ranking
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / meta / properties / total_candidates
```
Added value: +{
+  "type": "integer"
+}
```
addedOutput schema / properties / meta / properties / truncated
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / meta / properties / units / $ref

Added value: +"#/properties/items/items/properties/distance_unit"

removedOutput schema / properties / meta / properties / units / enum
```
Removed value: -[
-  "miles",
-  "kilometers"
-]
```
removedOutput schema / properties / meta / properties / units / type
```
Removed value: -"string"
```

removedOutput schema / properties / meta / required

Removed value: -[
-  "radius_km",
-  "radius",
-  "units"
-]

Changed6 schema fields changedSep 6, 2026

addedInput schema / properties / radius / anyOf

Added value: +[
+  {
+    "exclusiveMinimum": 0,
+    "maximum": 500,
+    "type": "number"
+  },
+  {
+    "maxLength": 32,
+    "type": "string"
+  }
+]

changedInput schema / properties / radius / description

Previous value: -"Search radius with unit, e.g. '50km', '30mi' (default: 150km, max: 500km / ~310mi). Larger radii return 400 INVALID_QUERY."New value: +"Search radius — e.g. radius: 30, units: 'miles'. Bare numbers are miles unless units is set; kilometers via units or a km suffix ('50km'); aliases mi/km/imperial/metric. A value carrying its own unit suffix ('50km', '30mi') is also accepted for compatibility and its suffix wins. Default 150 km (93.206 mi), maximum 500 km (~310 mi). Numeric values above 500 fail input validation before the tool runs; a string form over the maximum ('600km') or an in-range number that is over the cap once read as miles (e.g. 400, or 400 with units 'miles' — 644 km) returns a structured radius_exceeds_max error instead of results."

removedInput schema / properties / radius / maxLength
```
Removed value: -16
```
removedInput schema / properties / radius / type
```
Removed value: -"string"
```

addedInput schema / properties / units

Added value: +{
+  "description": "Units for a bare numeric `radius`: miles (default) or kilometers. Accepts 'mi'/'km'/'imperial'/'metric' as aliases (any case), echoed as miles|kilometers. Ignored when `radius` already carries a unit suffix; a contradicting pair is rejected. Does not supply a radius on its own (the default 150 km applies) but selects the display unit of the meta.radius / meta.units echo.",
+  "enum": [
+    "miles",
+    "kilometers"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / meta

Added value: +{
+  "additionalProperties": true,
+  "properties": {
+    "radius": {
+      "type": "number"
+    },
+    "radius_km": {
+      "type": "number"
+    },
+    "units": {
+      "enum": [
+        "miles",
+        "kilometers"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "radius_km",
+    "radius",
+    "units"
+  ],
+  "type": "object"
+}

Changed15 schema fields changedAug 17, 2026
- changedInput schema / properties / boundary_country / description
```
Previous value: -"ISO country code to restrict results"New value: +"ISO country code to restrict results (alpha-2 or alpha-3)"
```
- addedInput schema / properties / boundary_country / maxLength
```
Added value: +3
```
- addedInput schema / properties / lat / maximum
```
Added value: +90
```
- addedInput schema / properties / lat / minimum
```
Added value: +-90
```
- addedInput schema / properties / layers / maxLength
```
Added value: +200
```
- addedInput schema / properties / location / maxLength
```
Added value: +2000
```
- addedInput schema / properties / lon / maximum
```
Added value: +180
```
- addedInput schema / properties / lon / minimum
```
Added value: +-180
```
- addedInput schema / properties / min_population / maximum
```
Added value: +10000000000
```
- addedInput schema / properties / min_population / minimum
```
Added value: +0
```
- addedInput schema / properties / radius / maxLength
```
Added value: +16
```
- addedInput schema / properties / size / maximum
```
Added value: +50
```
- addedInput schema / properties / size / minimum
```
Added value: +1
```
- changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
- addedOutput schema / properties / metrics
```
Added value: +{}
```

Changed1 schema field changedMay 7, 2026

changedInput schema / properties / radius / description

Previous value: -"Search radius with unit, e.g. '50km', '30mi' (default: 150km)"New value: +"Search radius with unit, e.g. '50km', '30mi' (default: 150km, max: 500km / ~310mi). Larger radii return 400 INVALID_QUERY."

Changed1 schema field changedMay 1, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "display_hint": {
+      "additionalProperties": true,
+      "properties": {
+        "layout": {
+          "anyOf": [
+            {
+              "enum": [
+                "summary",
+                "table",
+                "summary+table",
+                "map",
+                "chart+table"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "string"
+            }
+          ]
+        },
+        "map_layers": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "preferred_charts": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "sections": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "layout"
+      ],
+      "type": "object"
+    },
+    "geojson": {
+      "additionalProperties": true,
+      "properties": {
+        "features": {
+          "items": {
+            "additionalProperties": true,
+            "properties": {
+              "geometry": {
+                "anyOf": [
+                  {
+                    "additionalProperties": true,
+                    "properties": {
+                      "coordinates": {},
+                      "geometries": {
+                        "items": {},
+                        "type": "array"
+                      },
+                      "type": {
+                        "anyOf": [
+                          {
+                            "enum": [
+                              "Point",
+                              "LineString",
+                              "Polygon",
+                              "MultiPoint",
+                              "MultiLineString",
+                              "MultiPolygon",
+                              "GeometryCollection"
+                            ],
+                            "type": "string"
+                          },
+                          {
+                            "type": "string"
+                          }
+                        ]
+                      }
+                    },
+                    "required": [
+                      "type"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "id": {
+                "type": [
+                  "string",
+                  "number"
+                ]
+              },
+              "properties": {
+                "additionalProperties": {},
+                "type": "object"
+              },
+              "type": {
+                "const": "Feature",
+                "type": "string"
+              }
+            },
+            "required": [
+              "type",
+              "geometry"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "type": {
+          "const": "FeatureCollection",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "features"
+      ],
+      "type": "object"
+    },
+    "items": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "coordinates": {
+            "additionalProperties": true,
+            "properties": {
+              "lat": {
+                "type": "number"
+              },
+              "lon": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "lat",
+              "lon"
+            ],
+            "type": "object"
+          },
+          "country": {
+            "type": "string"
+          },
+          "distance_km": {
+            "type": "number"
+          },
+          "label": {
+            "type": "string"
+          },
+          "layer": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "population": {
+            "type": "number"
+          },
+          "region": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "summary": {
+      "additionalProperties": {},
+      "description": "Map of scalar facts the LLM should surface verbatim",
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedApr 29, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
First observedApr 28, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations (readOnly, idempotent), the description reveals behavioral nuances: per-layer default radii and caps, how `size` is split across layers, the `meta.ranking` echo, and structured error responses like `radius_exceeds_max`. It also explains that `units` does not supply a radius on its own. This exceeds the annotation baseline.

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

Conciseness4/5

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

The description is dense but logically organized, front-loading the core purpose and usage. Every sentence carries information, though some redundancy exists (e.g., repeated mentions of 'radius policy is per layer' and unit aliases in multiple parameters). Slightly verbose but not wasteful.

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 tool with 10 parameters and complex interdependencies, the description covers all critical interactions: how radius and units combine, layer-specific caps, error cases, and tie-breaking behavior. Since an output schema is present, lack of return details is acceptable. The agent has enough context to invoke it correctly in any scenario.

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?

The schema already covers 100% of parameters, but the description adds substantial meaning: `units` aliases and precedence rules, `layers` per-layer radius policies, `radius` error conditions and unit-suffix handling, and `sort` ranking semantics. This transforms bare schemas into actionable knowledge, well above the baseline of 3.

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

Purpose5/5

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

The description clearly states the tool is for browsing/discovery of administrative places near a location, and immediately distinguishes it from `search_places` for venues. The verb 'explore' and resource 'administrative places' are explicit, making the purpose unmistakable.

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?

It explicitly tells the agent when to use this tool ('when the user is exploring a REGION') and when not to use it ('venues, addresses and streets are NOT served here... use search_places'), plus provides detailed guidance on radius policies, layer restrictions, and unit handling. This leaves no ambiguity about selection.

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

All ThinAir Geo tools Inspect

Try in Browser

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?