Returns the full admin hierarchy from country down to neighbourhood
    for the given coordinates.

    Args:
        lat: Latitude (-90 to 90)
        lon: Longitude (-180 to 180)
        output_mode: "json" (default) or "text"

    Returns:
        Administrative boundaries from largest to smallest
    

    Each query is processed sequentially to respect Nominatim rate limits.
    Individual failures don't abort the batch.

    Args:
        queries: JSON array of place names (e.g. '["Boulder, CO", "Denver, CO"]')
        limit: Maximum results per query (default 1)
        output_mode: "json" (default) or "text"

    Returns:
        Per-query results with coordinates, or error for failed queries

    CRITICAL — LLM retry guidance:
        If any query in the batch fails, re-run only the failed queries
        with simplified names using the single geocode tool. Nominatim
        works best with simple place names — remove landmarks, qualifiers,
        and descriptive words before retrying.
    

    Returns bbox as [west, south, east, north] in EPSG:4326, compatible
    with dem_fetch, stac_search, dem_slope, and other geospatial tools.

    Args:
        query: Place name to get bbox for (e.g. "Palm Jumeirah, Dubai")
        padding: Fractional padding to expand bbox (0.1 = 10% on each side, default 0.0)
        output_mode: "json" (default) or "text"

    Returns:
        Bounding box [west, south, east, north], center point, and approximate area

    CRITICAL — LLM retry workflow when no results are found:
        If the query returns no results, you MUST retry automatically — do
        NOT ask the user. Simplify the query progressively:

        1. Remove specific landmarks/features, keep the broader place.
           "Strood Causeway, Mersea Island" → "Mersea Island"
        2. Drop region/country qualifiers if still no results.
           "Mersea Island, Essex, UK" → "Mersea Island"
        3. Try alternative or official names for the place.
        4. If using a broader place, consider adding padding to cover the
           area of interest (e.g. padding=0.1 for 10% expansion).

        Always retry at least twice before reporting failure.
    

    Pure computation — no API calls needed. Accepts points as either
    [lat, lon] pairs or {"name": ..., "lat": ..., "lon": ...} objects.

    Args:
        points: JSON array of points. Each point is either:
                - [lat, lon] pair (auto-named "Point 1", "Point 2", ...)
                - {"name": "Label", "lat": 40.0, "lon": -105.0}
        output_mode: "json" (default) or "text"

    Returns:
        NxN distance matrix in metres between all point pairs
    

    Searches the OpenStreetMap/Nominatim database for places matching
    the query and returns coordinates, bounding boxes, and address details.

    Args:
        query: Place name or address to search for (e.g. "Boulder, Colorado")
        limit: Maximum results (1-50, default 5)
        countrycodes: Comma-separated ISO 3166-1 country codes to filter (e.g. "us,gb")
        language: Preferred response language (e.g. "en", "de", "fr")
        output_mode: "json" (default) or "text"

    Returns:
        List of matching places with coordinates, bbox, and address details

    CRITICAL — LLM retry workflow when no results are found:
        Nominatim works best with simple, well-known place names. Specific
        or compound names (e.g. "Strood Causeway, Mersea Island, UK") often
        return nothing.

        If the query returns no results, you MUST retry automatically — do
        NOT ask the user. Follow this cascade:

        1. Remove qualifiers and landmarks — keep only the core place name.
           "Strood Causeway, Mersea Island, UK" → "Mersea Island, UK"
           "Portland Harbor, Maine" → "Portland, Maine"
        2. Simplify further — drop region/country qualifiers.
           "Mersea Island, UK" → "Mersea Island"
           "Portland, Maine" → "Portland"
        3. Use countrycodes to narrow broad queries (e.g. countrycodes="gb").
        4. If the place is near a well-known location, geocode that instead
           and report the approximate area.
        5. Try alternative or official names — "The Strood" instead of
           "Strood Causeway", etc.

        Always retry at least twice with progressively simpler terms before
        telling the user the location could not be found.
    

    Returns the complete list of tools, Nominatim API details,
    and LLM-friendly usage guidance.

    Args:
        output_mode: "json" (default) or "text"

    Returns:
        Full server capabilities including tool lists and guidance
    

    Returns server version, Nominatim URL, cache stats, and tool count.

    Args:
        output_mode: "json" (default) or "text"

    Returns:
        Server status information
    

    Discovers nearby places at different scales (buildings, streets,
    suburbs, cities) using reverse geocoding at multiple zoom levels.

    Args:
        lat: Latitude (-90 to 90)
        lon: Longitude (-180 to 180)
        limit: Maximum number of results (default 10)
        categories: Comma-separated OSM categories to filter (e.g. "natural,tourism")
        output_mode: "json" (default) or "text"

    Returns:
        List of nearby places with distances, sorted by proximity
    

    Looks up the nearest place for the given coordinates and returns
    the display name, structured address, and bounding box.

    Args:
        lat: Latitude (-90 to 90)
        lon: Longitude (-180 to 180)
        zoom: Detail level 0-18 (18=building, 10=city, 3=country, default 18)
        language: Preferred response language (e.g. "en", "de", "fr")
        output_mode: "json" (default) or "text"

    Returns:
        Place name, address components, and bounding box
    

    Resolves each waypoint to coordinates, then computes haversine
    distances between consecutive points.

    Args:
        waypoints: JSON array of place names in route order
                   (e.g. '["Boulder, CO", "Denver, CO", "Aspen, CO"]')
        output_mode: "json" (default) or "text"

    Returns:
        Resolved waypoints, leg distances, total distance, and bounding box

    CRITICAL — LLM retry guidance:
        If a waypoint fails to resolve, simplify its name and retry the
        entire route. Remove landmarks, qualifiers, and descriptive words.
        Use the single geocode tool to test problematic names first.