# Geo — canonical payload contracts

GeoNames-backed geospatial MCP: countries, cities, admin regions, marine, POIs (airports, peaks, lakes, …), distance and nearby search.

**Service id:** `geo`  
**Docs:** [https://mcp.glc-rag.hu/guide/geo](https://mcp.glc-rag.hu/guide/geo)  
**Markdown docs:** [https://mcp.glc-rag.hu/guide/geo.md](https://mcp.glc-rag.hu/guide/geo.md)  
**MCP resource:** `docs://geo/payload`

POST `https://mcp.glc-rag.hu/mcp`. Values below are **type slots** from the live input schema (e.g. `<string, required>`), not example data. Fill them from the user task.

RPC result wrapper: `result.structuredContent` is the object in **Output schema**. `result.isError` mirrors `structuredContent.is_error`.

## `geo_status`

Geo DB health, read-only mode, and row counts by entity_type.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_status",
    "arguments": {}
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    }
  },
  "additionalProperties": true,
  "required": [
    "ok"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_resolve`

Resolve a name, ISO2/ISO3, or IATA code to geo entities (best matches).

**Required arguments:** `query`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_resolve",
    "arguments": {
      "query": "<string, required>",
      "entity_type": "<string, optional, enum country|city|place|admin1|admin2|marine>",
      "country_code": "<string, optional>",
      "place_kind": "<string, optional, enum hill|mountain|peak|volcano|lake|lakes|reservoir|waterfall|island|islands|atoll|airport|heliport|park|nature_reserve|wildlife_reserve|pass|ruin|castle|museum|monument|oilfield>",
      "limit": "<integer, optional, default 10, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "country",
        "city",
        "place",
        "admin1",
        "admin2",
        "marine"
      ]
    },
    "country_code": {
      "type": "string",
      "description": "ISO2 filter"
    },
    "place_kind": {
      "type": "string",
      "enum": [
        "hill",
        "mountain",
        "peak",
        "volcano",
        "lake",
        "lakes",
        "reservoir",
        "waterfall",
        "island",
        "islands",
        "atoll",
        "airport",
        "heliport",
        "park",
        "nature_reserve",
        "wildlife_reserve",
        "pass",
        "ruin",
        "castle",
        "museum",
        "monument",
        "oilfield"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_get`

Full entity profile by geoname_id (columns + complete payload).

**Required arguments:** `geoname_id`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_get",
    "arguments": {
      "geoname_id": "<integer, required>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "geoname_id": {
      "type": "integer"
    }
  },
  "required": [
    "geoname_id"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "entity": {
      "type": [
        "object",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "found"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_text_search`

Fuzzy text search (pg_trgm) over names and search_text.

**Required arguments:** `query`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_text_search",
    "arguments": {
      "query": "<string, required>",
      "entity_type": "<string, optional, enum country|city|place|admin1|admin2|marine>",
      "limit": "<integer, optional, default 20, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "country",
        "city",
        "place",
        "admin1",
        "admin2",
        "marine"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_semantic_search`

Embedding-space neighbors around the best name match (uses stored e5 vectors; no write to DB). Falls back to text search if anchor has no embedding.

**Required arguments:** `query`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_semantic_search",
    "arguments": {
      "query": "<string, required>",
      "entity_type": "<string, optional, enum country|city|place|admin1|admin2|marine>",
      "limit": "<integer, optional, default 20, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "country",
        "city",
        "place",
        "admin1",
        "admin2",
        "marine"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_country_get`

Country facts by ISO2 or geoname_id (currency, languages, coastal flags, …).

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_country_get",
    "arguments": {
      "iso2": "<string, optional>",
      "geoname_id": "<integer, optional>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    },
    "geoname_id": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "entity": {
      "type": [
        "object",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "found"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_country_list`

List countries, optionally filtered by continent_code.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_country_list",
    "arguments": {
      "continent_code": "<string, optional>",
      "limit": "<integer, optional, default 50, minimum 1, maximum 252>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "continent_code": {
      "type": "string",
      "description": "e.g. EU, AS, AF"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 252,
      "default": 50
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_country_neighbours`

Neighbouring countries via payload.neighbours ISO2 list.

**Required arguments:** `iso2`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_country_neighbours",
    "arguments": {
      "iso2": "<string, required>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    }
  },
  "required": [
    "iso2"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_country_capital`

Resolve country capital via capital_geoname_id.

**Required arguments:** `iso2`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_country_capital",
    "arguments": {
      "iso2": "<string, required>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    }
  },
  "required": [
    "iso2"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "entity": {
      "type": [
        "object",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "found"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_admin1_list`

List admin1 regions for a country (e.g. Italian regions).

**Required arguments:** `country_code`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_admin1_list",
    "arguments": {
      "country_code": "<string, required>",
      "limit": "<integer, optional, default 50, minimum 1, maximum 100>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "required": [
    "country_code"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_admin1_get`

Get admin1 by admin_code (e.g. IT.03) or geoname_id.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_admin1_get",
    "arguments": {
      "admin_code": "<string, optional>",
      "geoname_id": "<integer, optional>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "admin_code": {
      "type": "string"
    },
    "geoname_id": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "entity": {
      "type": [
        "object",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "found"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_admin2_list`

List admin2 for a country, optionally under an admin1 short code.

**Required arguments:** `country_code`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_admin2_list",
    "arguments": {
      "country_code": "<string, required>",
      "admin1_code": "<string, optional>",
      "limit": "<integer, optional, default 50, minimum 1, maximum 100>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "admin1_code": {
      "type": "string",
      "description": "Short code e.g. 03"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "required": [
    "country_code"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_admin2_get`

Get admin2 by admin_code or geoname_id.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_admin2_get",
    "arguments": {
      "admin_code": "<string, optional>",
      "geoname_id": "<integer, optional>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "admin_code": {
      "type": "string"
    },
    "geoname_id": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "entity": {
      "type": [
        "object",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "found"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_cities_search`

Search cities with filters: country, admin1 short code, population, coastal_category, distance_to_coast_km, is_capital, name query.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_cities_search",
    "arguments": {
      "country_code": "<string, optional>",
      "admin1_code": "<string, optional>",
      "min_population": "<integer, optional>",
      "max_population": "<integer, optional>",
      "coastal_category": "<string, optional, enum direct_coastal|coastal|near_coast|inland>",
      "max_distance_to_coast_km": "<number, optional>",
      "is_capital": "<boolean, optional>",
      "query": "<string, optional>",
      "limit": "<integer, optional, default 20, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "admin1_code": {
      "type": "string"
    },
    "min_population": {
      "type": "integer"
    },
    "max_population": {
      "type": "integer"
    },
    "coastal_category": {
      "type": "string",
      "enum": [
        "direct_coastal",
        "coastal",
        "near_coast",
        "inland"
      ]
    },
    "max_distance_to_coast_km": {
      "type": "number"
    },
    "is_capital": {
      "type": "boolean"
    },
    "query": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_coastal_cities`

Shortcut for coastal city lists (distance and/or coastal_category).

**Required arguments:** `country_code`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_coastal_cities",
    "arguments": {
      "country_code": "<string, required>",
      "admin1_code": "<string, optional>",
      "max_distance_to_coast_km": "<number, optional, default 5>",
      "coastal_category": "<string, optional, enum direct_coastal|coastal|near_coast|inland>",
      "max_population": "<integer, optional>",
      "limit": "<integer, optional, default 20, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "admin1_code": {
      "type": "string"
    },
    "max_distance_to_coast_km": {
      "type": "number",
      "default": 5
    },
    "coastal_category": {
      "type": "string",
      "enum": [
        "direct_coastal",
        "coastal",
        "near_coast",
        "inland"
      ]
    },
    "max_population": {
      "type": "integer"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "country_code"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_region_cities`

Cities in an admin1 region (country_code + admin1 short code).

**Required arguments:** `country_code`, `admin1_code`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_region_cities",
    "arguments": {
      "country_code": "<string, required>",
      "admin1_code": "<string, required>",
      "min_population": "<integer, optional>",
      "max_population": "<integer, optional>",
      "limit": "<integer, optional, default 20, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "admin1_code": {
      "type": "string"
    },
    "min_population": {
      "type": "integer"
    },
    "max_population": {
      "type": "integer"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "country_code",
    "admin1_code"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_nearest_marine`

Precomputed nearest sea/bay for a city (nearest_marine_* + coastal fields).

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_nearest_marine",
    "arguments": {
      "geoname_id": "<integer, optional>",
      "city_query": "<string, optional>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "geoname_id": {
      "type": "integer"
    },
    "city_query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "entity": {
      "type": [
        "object",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "found"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_marine_get`

Marine entity (sea, bay, …) by geoname_id or name query.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_marine_get",
    "arguments": {
      "geoname_id": "<integer, optional>",
      "query": "<string, optional>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "geoname_id": {
      "type": "integer"
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "entity": {
      "type": [
        "object",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "found"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_distance`

Haversine distance (km) between two places (id or name). Countries use capital coords.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_distance",
    "arguments": {
      "from_id": "<integer, optional>",
      "from_query": "<string, optional>",
      "to_id": "<integer, optional>",
      "to_query": "<string, optional>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "from_id": {
      "type": "integer"
    },
    "from_query": {
      "type": "string"
    },
    "to_id": {
      "type": "integer"
    },
    "to_query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "from": {
      "type": "object"
    },
    "to": {
      "type": "object"
    },
    "distance_km": {
      "type": "number"
    }
  },
  "additionalProperties": true,
  "required": [
    "distance_km"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_nearby`

Entities within radius_km of a center (id, name, or lat/lon). Optional type/kind filters.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_nearby",
    "arguments": {
      "center_id": "<integer, optional>",
      "center_query": "<string, optional>",
      "latitude": "<number, optional>",
      "longitude": "<number, optional>",
      "radius_km": "<number, optional, default 30>",
      "entity_type": "<string, optional, enum country|city|place|admin1|admin2|marine>",
      "place_kind": "<string, optional, enum hill|mountain|peak|volcano|lake|lakes|reservoir|waterfall|island|islands|atoll|airport|heliport|park|nature_reserve|wildlife_reserve|pass|ruin|castle|museum|monument|oilfield>",
      "limit": "<integer, optional, default 20, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "center_id": {
      "type": "integer"
    },
    "center_query": {
      "type": "string"
    },
    "latitude": {
      "type": "number"
    },
    "longitude": {
      "type": "number"
    },
    "radius_km": {
      "type": "number",
      "default": 30
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "country",
        "city",
        "place",
        "admin1",
        "admin2",
        "marine"
      ]
    },
    "place_kind": {
      "type": "string",
      "enum": [
        "hill",
        "mountain",
        "peak",
        "volcano",
        "lake",
        "lakes",
        "reservoir",
        "waterfall",
        "island",
        "islands",
        "atoll",
        "airport",
        "heliport",
        "park",
        "nature_reserve",
        "wildlife_reserve",
        "pass",
        "ruin",
        "castle",
        "museum",
        "monument",
        "oilfield"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_places_search`

Search POIs by place_kind (hill, mountain, peak, volcano, lake, lakes, reservoir, waterfall, …), country, name, elevation.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_places_search",
    "arguments": {
      "place_kind": "<string, optional, enum hill|mountain|peak|volcano|lake|lakes|reservoir|waterfall|island|islands|atoll|airport|heliport|park|nature_reserve|wildlife_reserve|pass|ruin|castle|museum|monument|oilfield>",
      "country_code": "<string, optional>",
      "query": "<string, optional>",
      "min_elevation": "<number, optional>",
      "limit": "<integer, optional, default 20, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "place_kind": {
      "type": "string",
      "enum": [
        "hill",
        "mountain",
        "peak",
        "volcano",
        "lake",
        "lakes",
        "reservoir",
        "waterfall",
        "island",
        "islands",
        "atoll",
        "airport",
        "heliport",
        "park",
        "nature_reserve",
        "wildlife_reserve",
        "pass",
        "ruin",
        "castle",
        "museum",
        "monument",
        "oilfield"
      ]
    },
    "country_code": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "min_elevation": {
      "type": "number"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_airport_lookup`

Find airports by IATA/ICAO, name, country, or near a city.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_airport_lookup",
    "arguments": {
      "iata": "<string, optional>",
      "icao": "<string, optional>",
      "query": "<string, optional>",
      "country_code": "<string, optional>",
      "near_query": "<string, optional>",
      "radius_km": "<number, optional, default 50>",
      "limit": "<integer, optional, default 10, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "iata": {
      "type": "string"
    },
    "icao": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "country_code": {
      "type": "string"
    },
    "near_query": {
      "type": "string"
    },
    "radius_km": {
      "type": "number",
      "default": 50
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_rank_places`

Rank places of a kind (e.g. highest peaks) optionally within a country.

**Required arguments:** `place_kind`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_rank_places",
    "arguments": {
      "place_kind": "<string, required, enum hill|mountain|peak|volcano|lake|lakes|reservoir|waterfall|island|islands|atoll|airport|heliport|park|nature_reserve|wildlife_reserve|pass|ruin|castle|museum|monument|oilfield>",
      "country_code": "<string, optional>",
      "limit": "<integer, optional, default 10, minimum 1, maximum 50>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "place_kind": {
      "type": "string",
      "enum": [
        "hill",
        "mountain",
        "peak",
        "volcano",
        "lake",
        "lakes",
        "reservoir",
        "waterfall",
        "island",
        "islands",
        "atoll",
        "airport",
        "heliport",
        "park",
        "nature_reserve",
        "wildlife_reserve",
        "pass",
        "ruin",
        "castle",
        "museum",
        "monument",
        "oilfield"
      ]
    },
    "country_code": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "required": [
    "place_kind"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geoname_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "ascii_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "place_kind": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "count",
    "results"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `geo_place_kinds`

List supported place_kind values and entity_type values.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "geo_place_kinds",
    "arguments": {}
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "kinds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": true,
  "required": [
    "kinds"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```