bbox-mcp-server 1.3.0 → 1.4.0

package/dist/index.js

@@ -4,11 +4,21 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as h3 from "h3-js";
 import proj4 from "proj4";
+import pkg from "./package.json" with { type: "json" };
 import proj4defs from "./proj4defs.json" with { type: "json" };
 import { wktToGeoJSON as parseWKT } from "@terraformer/wkt";
 const SERVER_NAME = "bbox-mcp-server";
-const SERVER_VERSION = "1.2.6";
-const MAX_H3_CELLS = process.env.MAX_H3_CELLS ? parseInt(process.env.MAX_H3_CELLS, 10) : 50000;
+const SERVER_VERSION = pkg.version;
+const MAX_H3_CELLS = (() => {
+    if (!process.env.MAX_H3_CELLS)
+        return 50000;
+    const v = parseInt(process.env.MAX_H3_CELLS, 10);
+    if (!Number.isFinite(v) || v <= 0) {
+        console.error(JSON.stringify({ timestamp: new Date().toISOString(), level: 'warn', server: 'bbox-mcp-server', message: `Invalid MAX_H3_CELLS="${process.env.MAX_H3_CELLS}", using default 50000` }));
+        return 50000;
+    }
+    return v;
+})();
 const MAPBOX_ACCESS_TOKEN = process.env.MAPBOX_ACCESS_TOKEN;
 const MAX_INPUT_LENGTH = 1_000_000; // 1 MB input size guard
 const FETCH_TIMEOUT_MS = 10_000; // 10 second timeout for external API calls
@@ -56,6 +66,9 @@ initProj4();
  */
 function extractCoords(obj) {
     const result = [];
+    // Only follow GeoJSON-structural keys to avoid walking into properties
+    // which may contain arbitrary numeric arrays.
+    const GEO_KEYS = new Set(['coordinates', 'geometry', 'geometries', 'features']);
     const stack = [obj];
     while (stack.length > 0) {
         const current = stack.pop();
@@ -70,9 +83,10 @@ function extractCoords(obj) {
             }
         }
         else if (current && typeof current === 'object') {
-            const values = Object.values(current);
-            for (let i = values.length - 1; i >= 0; i--) {
-                stack.push(values[i]);
+            for (const key of Object.keys(current)) {
+                if (GEO_KEYS.has(key)) {
+                    stack.push(current[key]);
+                }
             }
         }
     }
@@ -110,7 +124,7 @@ function validateBBox(lat1, lng1, lat2, lng2) {
         return false;
     return true;
 }
-function parseBBox(input) {
+function parseBBox(input, warnings) {
     if (!input || typeof input !== 'string') {
         throw new Error(`Invalid bbox input.`);
     }
@@ -174,8 +188,16 @@ function parseBBox(input) {
     // Support space-separated (GDAL) or comma-separated
     const parts = cleanInput.split(/[\s,]+/).map(s => parseFloat(s.trim())).filter(n => !isNaN(n));
     if (parts.length === 4) {
-        // Assume format: lat1, lng1, lat2, lng2 OR minX, minY, maxX, maxY
-        // BBox finder defaults to minLat, minLng, maxLat, maxLng
+        // Default interpretation: lat1, lng1, lat2, lng2
+        // Detect ambiguity: if both (lat,lng) and (lng,lat) orderings are valid,
+        // the caller may have a transposed box without knowing it.
+        const asLatLng = validateBBox(parts[0], parts[1], parts[2], parts[3]);
+        const asLngLat = validateBBox(parts[1], parts[0], parts[3], parts[2]);
+        if (asLatLng && asLngLat && (parts[0] !== parts[1] || parts[2] !== parts[3])) {
+            warnings?.push(`Ambiguous coordinate order: interpreted as lat,lng,lat,lng → (${parts[0]}, ${parts[1]}, ${parts[2]}, ${parts[3]}). ` +
+                `If your source uses lng,lat order (GeoJSON, GDAL, most GIS tools), the bounding box may be transposed. ` +
+                `Use GeoJSON or WKT input to avoid ambiguity.`);
+        }
         return ensureValidBBox(parts[0], parts[1], parts[2], parts[3]);
     }
     throw new Error(`Failed to parse bounding box. Input must be one of: WKT, GeoJSON, ogrinfo extent, or "lat1,lng1,lat2,lng2" string. Got: ${input.substring(0, 50)}...`);
@@ -192,6 +214,9 @@ function ensureValidBBox(lat1, lng1, lat2, lng2) {
         lng2: Math.max(lng1, lng2)
     };
 }
+function formatWarnings(warnings) {
+    return warnings.length > 0 ? '\n\n⚠️ ' + warnings.join('\n⚠️ ') : '';
+}
 function projectBounds(bbox, epsg) {
     if (epsg === "4326") {
         return { xmin: bbox.lng1, ymin: bbox.lat1, xmax: bbox.lng2, ymax: bbox.lat2 };
@@ -200,13 +225,20 @@ function projectBounds(bbox, epsg) {
     if (!proj4.defs(epsgKey)) {
         throw new Error(`Unknown EPSG code: ${epsg}. Make sure it exists in proj4defs.`);
     }
-    const p1 = proj4(epsgKey, [bbox.lng1, bbox.lat1]);
-    const p2 = proj4(epsgKey, [bbox.lng2, bbox.lat2]);
+    // Project all four corners to handle axis flips and oblique/rotated CRS
+    const corners = [
+        proj4(epsgKey, [bbox.lng1, bbox.lat1]),
+        proj4(epsgKey, [bbox.lng2, bbox.lat1]),
+        proj4(epsgKey, [bbox.lng1, bbox.lat2]),
+        proj4(epsgKey, [bbox.lng2, bbox.lat2]),
+    ];
+    const xs = corners.map(c => c[0]);
+    const ys = corners.map(c => c[1]);
     return {
-        xmin: p1[0],
-        ymin: p1[1],
-        xmax: p2[0],
-        ymax: p2[1],
+        xmin: Math.min(...xs),
+        ymin: Math.min(...ys),
+        xmax: Math.max(...xs),
+        ymax: Math.max(...ys),
     };
 }
 /**
@@ -224,6 +256,9 @@ async function ensureProjection(epsg) {
     const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
         const response = await fetch(`https://epsg.io/${epsg}.proj4`, {
+            headers: {
+                'User-Agent': `${SERVER_NAME}/${SERVER_VERSION} (https://github.com/iamvibhorsingh/bbox-mcp-server)`
+            },
             signal: controller.signal,
         });
         if (!response.ok) {
@@ -312,9 +347,11 @@ function calculateBboxArea(bbox) {
     return widthKm * heightKm;
 }
 function latLngToTile(lat, lng, zoom) {
+    // Clamp to Web Mercator latitude limits to avoid Math.tan(±90°) → Infinity → NaN
+    const clampedLat = Math.max(-85.0511, Math.min(85.0511, lat));
     const n = Math.pow(2, zoom);
     const x = Math.floor((lng + 180) / 360 * n);
-    const latRad = lat * Math.PI / 180;
+    const latRad = clampedLat * Math.PI / 180;
     const y = Math.floor((1 - Math.log(Math.tan(latRad) + 1 / Math.cos(latRad)) / Math.PI) / 2 * n);
     return { z: zoom, x, y };
 }
@@ -394,90 +431,298 @@ function h3CellsToGeoJSON(cells) {
         features
     };
 }
-async function geocodeLocation(query) {
-    if (!MAPBOX_ACCESS_TOKEN) {
-        throw new Error('Mapbox API token not configured. Set MAPBOX_ACCESS_TOKEN environment variable to use the location search feature. Alternatively, provide exact coordinate bounds via the `bbox` argument.');
+// ---------------------------------------------------------------------------
+// Nominatim Rate Limiter, Caching, and Utilities
+// ---------------------------------------------------------------------------
+let lastNominatimRequestTime = 0;
+const NOMINATIM_CACHE = new Map();
+const NOMINATIM_TTL_MS = 60 * 60 * 1000; // 1 hour TTL
+const NOMINATIM_BASE_URL = (process.env.NOMINATIM_API_URL || "https://nominatim.openstreetmap.org").replace(/\/+$/, "");
+async function fetchNominatim(url) {
+    const cached = NOMINATIM_CACHE.get(url);
+    if (cached && (Date.now() - cached.timestamp < NOMINATIM_TTL_MS)) {
+        return cached.data;
+    }
+    const now = Date.now();
+    const timeSinceLast = now - lastNominatimRequestTime;
+    if (timeSinceLast < 1000) {
+        await new Promise(resolve => setTimeout(resolve, 1000 - timeSinceLast));
     }
+    lastNominatimRequestTime = Date.now();
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
-        const url = `https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(query)}.json?access_token=${MAPBOX_ACCESS_TOKEN}&limit=1`;
-        const response = await fetch(url, { signal: controller.signal });
+        const response = await fetch(url, {
+            headers: {
+                'User-Agent': `${SERVER_NAME}/${SERVER_VERSION} (https://github.com/iamvibhorsingh/bbox-mcp-server)`,
+                'Accept': 'application/json'
+            },
+            signal: controller.signal
+        });
         if (!response.ok) {
-            throw new Error(`Geocoding failed with status: ${response.status} ${response.statusText}`);
+            throw new Error(`Nominatim request failed with status: ${response.status} ${response.statusText}`);
         }
         const data = await response.json();
-        if (!data || typeof data !== "object" || !Array.isArray(data.features)) {
-            throw new Error(`Unexpected geocoding response format from Mapbox API for query: ${query}`);
-        }
-        if (!data.features || data.features.length === 0) {
-            throw new Error(`No results found for location: ${query}`);
+        NOMINATIM_CACHE.set(url, { timestamp: Date.now(), data });
+        return data;
+    }
+    catch (err) {
+        if (err.name === 'AbortError') {
+            throw new Error(`Nominatim request timed out after ${FETCH_TIMEOUT_MS / 1000}s for URL: ${url}`);
         }
-        const feature = data.features[0];
-        if (feature.bbox) {
-            // mb bbox format: minX, minY, maxX, maxY
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function geocodeLocation(query) {
+    // 1. Try Nominatim first (free, returns exact OSM area boundaries & alternatives)
+    try {
+        const nominatimUrl = `${NOMINATIM_BASE_URL}/search?q=${encodeURIComponent(query)}&format=json&addressdetails=1&extratags=1&limit=5`;
+        const items = await fetchNominatim(nominatimUrl);
+        if (Array.isArray(items) && items.length > 0) {
+            const parsedItems = items.map((item) => {
+                let bbox;
+                if (item.boundingbox && item.boundingbox.length === 4) {
+                    const south = parseFloat(item.boundingbox[0]);
+                    const north = parseFloat(item.boundingbox[1]);
+                    const west = parseFloat(item.boundingbox[2]);
+                    const east = parseFloat(item.boundingbox[3]);
+                    bbox = ensureValidBBox(south, west, north, east);
+                }
+                else {
+                    const lat = parseFloat(item.lat);
+                    const lon = parseFloat(item.lon);
+                    bbox = ensureValidBBox(lat - 0.05, lon - 0.05, lat + 0.05, lon + 0.05);
+                }
+                const center = { lat: parseFloat(item.lat), lng: parseFloat(item.lon) };
+                let osm_area_id;
+                const osmIdNum = parseInt(item.osm_id, 10);
+                if (item.osm_type === "relation" && !isNaN(osmIdNum)) {
+                    osm_area_id = 3600000000 + osmIdNum;
+                }
+                else if (item.osm_type === "way" && !isNaN(osmIdNum)) {
+                    osm_area_id = 2400000000 + osmIdNum;
+                }
+                return {
+                    matched_place: item.display_name,
+                    bbox,
+                    center,
+                    osm_area_id,
+                    class: item.class,
+                    type: item.type,
+                    osm_type: item.osm_type,
+                    osm_id: osmIdNum
+                };
+            });
+            // Boundary relation preference: prefer relation with class=boundary or type=administrative/boundary
+            let primaryIndex = parsedItems.findIndex(i => i.osm_type === "relation" &&
+                (i.class === "boundary" || i.type === "administrative" || i.type === "boundary"));
+            if (primaryIndex === -1)
+                primaryIndex = 0;
+            const primary = parsedItems[primaryIndex];
+            const alternatives = parsedItems.filter((_, idx) => idx !== primaryIndex);
             return {
-                lat1: feature.bbox[1],
-                lng1: feature.bbox[0],
-                lat2: feature.bbox[3],
-                lng2: feature.bbox[2]
+                ...primary,
+                alternatives
             };
         }
-        else if (feature.center) {
-            // create a small bbox around the center point (10km roughly)
-            const centerLng = feature.center[0];
-            const centerLat = feature.center[1];
-            const offset = 0.05;
+    }
+    catch (err) {
+        log('warn', `Nominatim geocoding failed for '${query}', trying Mapbox fallback`, { error: err.message });
+    }
+    // 2. Fallback to Mapbox if available
+    if (MAPBOX_ACCESS_TOKEN) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        try {
+            const url = `https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(query)}.json?access_token=${MAPBOX_ACCESS_TOKEN}&limit=5`;
+            const response = await fetch(url, { signal: controller.signal });
+            if (!response.ok) {
+                throw new Error(`Geocoding failed with status: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            if (!data || !Array.isArray(data.features) || data.features.length === 0) {
+                throw new Error(`No results found for location: ${query}`);
+            }
+            const mapboxItems = data.features.map((feature) => {
+                let bbox;
+                let center;
+                if (feature.bbox) {
+                    bbox = ensureValidBBox(feature.bbox[1], feature.bbox[0], feature.bbox[3], feature.bbox[2]);
+                    center = { lat: (bbox.lat1 + bbox.lat2) / 2, lng: (bbox.lng1 + bbox.lng2) / 2 };
+                }
+                else if (feature.center) {
+                    center = { lat: feature.center[1], lng: feature.center[0] };
+                    bbox = ensureValidBBox(center.lat - 0.05, center.lng - 0.05, center.lat + 0.05, center.lng + 0.05);
+                }
+                else {
+                    throw new Error(`Unable to determine location bounds for feature`);
+                }
+                return {
+                    matched_place: feature.place_name || feature.text || query,
+                    bbox,
+                    center,
+                    class: feature.properties?.category
+                };
+            });
+            const primary = mapboxItems[0];
+            const alternatives = mapboxItems.slice(1);
             return {
-                lat1: centerLat - offset,
-                lng1: centerLng - offset,
-                lat2: centerLat + offset,
-                lng2: centerLng + offset
+                ...primary,
+                alternatives
             };
         }
-        else {
-            throw new Error(`Unable to determine bounding box for location: ${query}`);
+        catch (err) {
+            if (err.name === 'AbortError') {
+                throw new Error(`Geocoding request timed out for query: ${query}`);
+            }
+            throw err;
         }
-    }
-    catch (err) {
-        if (err.name === 'AbortError') {
-            throw new Error(`Geocoding request timed out after ${FETCH_TIMEOUT_MS / 1000}s for query: ${query}`);
+        finally {
+            clearTimeout(timeout);
         }
-        throw err;
     }
-    finally {
-        clearTimeout(timeout);
+    throw new Error(`No geocoding results found for location: ${query}`);
+}
+async function reverseGeocode(lat, lng, zoom = 18) {
+    if (isNaN(lat) || isNaN(lng) || lat < -90 || lat > 90 || lng < -180 || lng > 180) {
+        throw new Error(`Invalid lat/lng coordinates for reverse geocoding: (${lat}, ${lng})`);
+    }
+    const clampedZoom = Math.max(0, Math.min(18, Math.round(zoom)));
+    const url = `${NOMINATIM_BASE_URL}/reverse?format=json&lat=${lat}&lon=${lng}&zoom=${clampedZoom}&addressdetails=1`;
+    const data = await fetchNominatim(url);
+    if (!data || !data.display_name) {
+        throw new Error(`No reverse geocoding results found for coordinates: (${lat}, ${lng})`);
     }
+    let bbox;
+    if (data.boundingbox && data.boundingbox.length === 4) {
+        const south = parseFloat(data.boundingbox[0]);
+        const north = parseFloat(data.boundingbox[1]);
+        const west = parseFloat(data.boundingbox[2]);
+        const east = parseFloat(data.boundingbox[3]);
+        bbox = ensureValidBBox(south, west, north, east);
+    }
+    else {
+        bbox = ensureValidBBox(lat - 0.005, lng - 0.005, lat + 0.005, lng + 0.005);
+    }
+    const shareUrl = buildShareUrl(bbox);
+    return {
+        matched_place: data.display_name,
+        center: { lat, lng },
+        bbox,
+        address: data.address || {},
+        class: data.class,
+        type: data.type,
+        osm_type: data.osm_type,
+        osm_id: data.osm_id ? parseInt(data.osm_id, 10) : undefined,
+        share_url: shareUrl
+    };
 }
-async function geocodeLocationPoint(query) {
-    if (!MAPBOX_ACCESS_TOKEN) {
-        throw new Error('Mapbox API token not configured. Set MAPBOX_ACCESS_TOKEN to use location search. Provide explicit coordinates via bbox instead.');
+function splitOverpassStatements(query) {
+    const statements = [];
+    let current = '';
+    let inDouble = false;
+    let inSingle = false;
+    for (let i = 0; i < query.length; i++) {
+        const char = query[i];
+        if (char === '"' && !inSingle) {
+            inDouble = !inDouble;
+            current += char;
+        }
+        else if (char === "'" && !inDouble) {
+            inSingle = !inSingle;
+            current += char;
+        }
+        else if (char === ';' && !inDouble && !inSingle) {
+            if (current.trim()) {
+                statements.push(current.trim());
+            }
+            current = '';
+        }
+        else {
+            current += char;
+        }
     }
+    if (current.trim()) {
+        statements.push(current.trim());
+    }
+    return statements;
+}
+/**
+ * Attaches a spatial filter (e.g. `(area.searchArea)` or `(around:2000,lat,lng)`)
+ * to every selector statement in a multi-statement Overpass QL query string.
+ * Respects quoted semicolons in tag values and skips non-selector/output statements.
+ */
+function applySpatialFilter(queryRaw, spatialFilter) {
+    if (!spatialFilter)
+        return queryRaw.trim().endsWith(';') ? queryRaw.trim() : `${queryRaw.trim()};`;
+    const statements = splitOverpassStatements(queryRaw);
+    if (statements.length === 0)
+        return queryRaw;
+    const processed = statements.map(stmt => {
+        // Skip non-selector statements like 'out center', directives, set operations, comments
+        if (/^(out|[()\[]|->)/i.test(stmt) || /\bout\s+(body|skel|ids|meta|geom|center)/i.test(stmt)) {
+            return stmt;
+        }
+        if (stmt.includes(spatialFilter.trim())) {
+            return stmt;
+        }
+        // If statement defines a named set (e.g., `... -> .searchSet`), insert spatial filter before `->`
+        if (/->\s*\.[a-zA-Z0-9_]+/.test(stmt)) {
+            return stmt.replace(/(->\s*\.[a-zA-Z0-9_]+)/, `${spatialFilter} $1`);
+        }
+        return `${stmt}${spatialFilter}`;
+    });
+    return processed.join('; ') + ';';
+}
+function calculateHaversineDistanceMeters(lat1, lng1, lat2, lng2) {
+    const R = 6371000; // Earth radius in meters
+    const dLat = (lat2 - lat1) * Math.PI / 180;
+    const dLng = (lng2 - lng1) * Math.PI / 180;
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
+            Math.sin(dLng / 2) * Math.sin(dLng / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R * c;
+}
+async function getTaginfoSuggestions(keyword) {
+    const url = `https://taginfo.openstreetmap.org/api/4/search/by_keyword?query=${encodeURIComponent(keyword)}&rp=30`;
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    const MAINSTREAM_KEYS = new Set([
+        "amenity", "shop", "leisure", "tourism", "natural", "highway",
+        "office", "healthcare", "craft", "sport", "landuse", "building",
+        "historic", "emergency", "railway", "aeroway", "public_transport"
+    ]);
     try {
-        const url = `https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(query)}.json?access_token=${MAPBOX_ACCESS_TOKEN}&limit=1`;
-        const response = await fetch(url, { signal: controller.signal });
-        if (!response.ok)
-            throw new Error(`Geocoding failed: ${response.status} ${response.statusText}`);
-        const data = await response.json();
-        if (!data?.features?.length)
-            throw new Error(`No results found for location: ${query}`);
-        const feature = data.features[0];
-        if (feature.center) {
-            return { lat: feature.center[1], lng: feature.center[0] };
-        }
-        else if (feature.bbox) {
-            return { lat: (feature.bbox[1] + feature.bbox[3]) / 2, lng: (feature.bbox[0] + feature.bbox[2]) / 2 };
+        const response = await fetch(url, {
+            headers: { 'User-Agent': `${SERVER_NAME}/${SERVER_VERSION} (https://github.com/iamvibhorsingh/bbox-mcp-server)` },
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            throw new Error(`Taginfo status: ${response.status}`);
         }
-        else {
-            throw new Error(`Unable to determine center point for location: ${query}`);
+        const data = await response.json();
+        const results = data.data || [];
+        const filtered = results
+            .filter((item) => item.key &&
+            MAINSTREAM_KEYS.has(item.key) &&
+            (item.count_all ?? 0) >= 1000)
+            .sort((a, b) => (b.count_all ?? 0) - (a.count_all ?? 0))
+            .slice(0, 10);
+        if (filtered.length === 0) {
+            return `No mainstream OSM tags found for '${keyword}' with usage count > 1,000.\nTry searching standard keys like amenity, shop, leisure, or tourism.`;
         }
+        const lines = filtered.map((item) => {
+            const valStr = item.value ? `="${item.value}"` : '';
+            return `- nwr["${item.key}"${valStr}] (${(item.count_all || 0).toLocaleString()} objects)`;
+        });
+        return `Taginfo OSM Tag Recommendations for '${keyword}':\n\n${lines.join('\n')}`;
     }
     catch (err) {
-        if (err.name === 'AbortError')
-            throw new Error(`Geocoding timed out after ${FETCH_TIMEOUT_MS / 1000}s for: ${query}`);
-        throw err;
+        return `Taginfo lookup failed for '${keyword}': ${err.message}`;
     }
     finally {
         clearTimeout(timeout);
@@ -554,7 +799,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         location: {
                             type: "string",
-                            description: "A text location to search for (e.g. 'San Francisco'). Requires MAPBOX_ACCESS_TOKEN env var. Either 'location' or 'bbox' MUST be provided."
+                            description: "A text location to search for (e.g. 'San Francisco'). Either 'location' or 'bbox' MUST be provided."
                         },
                         bbox: {
                             type: "string",
@@ -568,6 +813,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "boolean",
                             description: "Whether to return a compacted list of cells (mixing resolutions) to minimize response size. Defaults to false."
                         },
+                        summary_only: {
+                            type: "boolean",
+                            description: "If true, returns only cell count, sample cells, and map share URL without dumping thousands of cell IDs into context. Ideal for high resolutions. Defaults to false."
+                        },
                         return_geometry: {
                             type: "boolean",
                             description: "If true, return GeoJSON FeatureCollection with hex boundary polygons in addition to cell IDs. Defaults to false."
@@ -594,15 +843,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["bbox"],
                 },
             },
+            {
+                name: "reverse_geocode",
+                description: "Reverse geocode latitude and longitude coordinates to discover context, place name, address components, and OSM details ('what is here?').",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        lat: {
+                            type: "number",
+                            description: "Latitude coordinate (-90 to 90)."
+                        },
+                        lng: {
+                            type: "number",
+                            description: "Longitude coordinate (-180 to 180)."
+                        },
+                        zoom: {
+                            type: "number",
+                            description: "Detail zoom level from 0 (country) to 18 (building/address). Defaults to 18."
+                        }
+                    },
+                    required: ["lat", "lng"]
+                }
+            },
             {
                 name: "search_overpass",
-                description: "Execute an Overpass QL query to find POIs, roads, or other OSM features within a bounding box or radius. The server wraps your query in the appropriate spatial filter and returns structured JSON with a map link.\n\nSEARCH MODES:\n- Bounding box (default): searches a rectangular area. Use for region/area queries ('hospitals in Manhattan', 'parks in downtown Seattle').\n- Circle: searches within an exact radius. Use ONLY when the user specifies an explicit distance ('within 2km of JFK', '500 metres from the Eiffel Tower', '1 mile from Times Square'). Omit radius_meters for vague terms like 'near' or 'close to'.\n\nCOMMON TAG EXAMPLES:\n- Restaurants: `nwr[\"amenity\"=\"restaurant\"]`\n- Pizza: `nwr[\"amenity\"=\"fast_food\"][\"cuisine\"=\"pizza\"]`\n- Supermarkets: `nwr[\"shop\"=\"supermarket\"]`\n- Parks: `nwr[\"leisure\"=\"park\"]`\n- Hospitals: `nwr[\"amenity\"=\"hospital\"]`\n- Schools: `nwr[\"amenity\"=\"school\"]`\n- Parking: `nwr[\"amenity\"=\"parking\"]`\n- Highways/Roads: `way[\"highway\"]`",
+                description: "Execute an Overpass QL query to find POIs, roads, or other OSM features within an admin boundary area, bounding box, or radius. The server wraps your query in spatial filters and returns structured JSON with distance calculations and a map link.\n\nSEARCH MODES:\n- Location / Admin Area: when 'location' resolves to an OSM boundary polygon (e.g. 'Manhattan', 'Seattle'), searches inside exact boundary polygon.\n- Bounding box (default): searches a rectangular area.\n- Circle: searches within an exact radius when 'radius_meters' is provided.\n\nCOMMON TAG EXAMPLES:\n- Restaurants: `nwr[\"amenity\"=\"restaurant\"]`\n- Pizza: `nwr[\"amenity\"=\"fast_food\"][\"cuisine\"=\"pizza\"]`\n- Supermarkets: `nwr[\"shop\"=\"supermarket\"]`\n- Parks: `nwr[\"leisure\"=\"park\"]`\n- Hospitals: `nwr[\"amenity\"=\"hospital\"]`\n- EV Charging: `nwr[\"amenity\"=\"charging_station\"]`\n- Gyms: `nwr[\"leisure\"=\"fitness_centre\"]`\n- Banks: `nwr[\"amenity\"=\"bank\"]`",
                 inputSchema: {
                     type: "object",
                     properties: {
                         location: {
                             type: "string",
-                            description: "A text location to search for (e.g. 'San Francisco', 'JFK Airport'). Requires MAPBOX_ACCESS_TOKEN env var. Either 'location' or 'bbox' MUST be provided."
+                            description: "A text location to search for (e.g. 'Manhattan', 'San Francisco'). Either 'location' or 'bbox' MUST be provided."
                         },
                         bbox: {
                             type: "string",
@@ -610,19 +881,35 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         query: {
                             type: "string",
-                            description: "The Overpass QL core query. Example: `node[\"amenity\"=\"cafe\"]` or `nwr[\"leisure\"=\"park\"]`. DO NOT include spatial filters, bounding box, or output directives — the server handles those automatically."
+                            description: "The Overpass QL core query. Example: `node[\"amenity\"=\"cafe\"]` or `nwr[\"leisure\"=\"park\"]`. Multi-statement queries supported (e.g. `nwr[\"office\"=\"coworking\"]; nwr[\"amenity\"=\"coworking_space\"]`). DO NOT include spatial filters or output directives."
                         },
                         radius_meters: {
                             type: "number",
-                            description: "Search radius in metres. Enables circle mode — use ONLY when the user specifies an explicit distance (e.g. '2km' → 2000, '500 metres' → 500, '1 mile' → 1609). Omit entirely for area/region queries or vague terms like 'near'."
+                            description: "Search radius in metres. Enables circle mode — use ONLY when explicit distance is specified ('2km' → 2000)."
                         },
                         limit: {
                             type: "number",
-                            description: "Maximum number of elements to return. Default is 100. Increase if you need more results."
+                            description: "Maximum number of elements to return per page. Default is 100."
+                        },
+                        offset: {
+                            type: "number",
+                            description: "Pagination offset for retrieving subsequent pages of results. Default is 0."
+                        },
+                        timeout_seconds: {
+                            type: "number",
+                            description: "Overpass server query timeout in seconds. Default is 25."
+                        },
+                        use_area_boundary: {
+                            type: "boolean",
+                            description: "If true (default), uses exact OSM administrative boundary polygon for named locations when available, avoiding bounding box collapse."
+                        },
+                        sort_by_distance: {
+                            type: "boolean",
+                            description: "If true, sorts returned elements by distance from origin/center. Enabled by default for circle mode and point locations."
                         },
                         return_geometry: {
                             type: "boolean",
-                            description: "If true, returns the full geometry (polygon/polyline) for ways and relations instead of just the center point. Necessary for area or length calculations. Defaults to false."
+                            description: "If true, returns full geometry (polygon/polyline) for ways and relations instead of center point. Defaults to false."
                         }
                     },
                     required: ["query"],
@@ -634,13 +921,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "list_osm_tags",
-                description: "Discovery tool to look up the correct OpenStreetMap tags for a given category. Helps prevent hallucinating incorrect tags before writing an Overpass query.",
+                description: "Discovery tool to look up the correct OpenStreetMap tags for any category. Uses built-in category index and live Taginfo API fallback to prevent tag hallucination.",
                 inputSchema: {
                     type: "object",
                     properties: {
                         category: {
                             type: "string",
-                            description: "Broad category to look up (e.g. 'food', 'health', 'transport', 'leisure', 'retail')."
+                            description: "Category or keyword to look up (e.g. 'food', 'ev charging', 'gym', 'coworking', 'banks', 'dog park')."
                         }
                     },
                     required: ["category"]
@@ -667,6 +954,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         resolution: {
                             type: "number",
                             description: "The H3 resolution level (0-15) for binning. Default is 8."
+                        },
+                        timeout_seconds: {
+                            type: "number",
+                            description: "Overpass server query timeout in seconds. Default is 25."
+                        },
+                        use_area_boundary: {
+                            type: "boolean",
+                            description: "If true (default), uses exact OSM boundary polygon for named locations when available."
                         }
                     },
                     required: ["query", "resolution"],
@@ -685,23 +980,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         if (toolName === "get_bounds") {
             const args = request.params.arguments || {};
+            const warnings = [];
             let bboxObj;
+            let geocodeRes;
             if (args.location) {
                 try {
-                    bboxObj = await geocodeLocation(args.location);
+                    geocodeRes = await geocodeLocation(args.location);
+                    bboxObj = geocodeRes.bbox;
                 }
                 catch (err) {
                     if (!args.bbox) {
                         log('error', `Geocoding failed for location: ${args.location}`, { error: err.message });
                         return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
                     }
-                    // User provided bbox fallback
                     log('warn', `Geocoding failed, falling back to bbox argument`, { error: err.message });
-                    bboxObj = parseBBox(args.bbox);
+                    bboxObj = parseBBox(args.bbox, warnings);
                 }
             }
             else if (args.bbox) {
-                bboxObj = parseBBox(args.bbox);
+                bboxObj = parseBBox(args.bbox, warnings);
             }
             else {
                 return { content: [{ type: "text", text: "Error: Either 'location' or 'bbox' argument must be provided." }], isError: true };
@@ -709,14 +1006,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let epsg = args.epsg || "4326";
             let format = args.format || "csv";
             let coordOrder = args.coord_order || "lng,lat";
-            let zoom = args.zoom || 15;
-            let precision = args.precision || 6;
+            let zoom = args.zoom ?? 15;
+            let precision = args.precision ?? 6;
             epsg = epsg.replace(/[^0-9]/g, "");
-            // Dynamically fetch projection if not bundled
             await ensureProjection(epsg);
             const projCoords = projectBounds(bboxObj, epsg);
             const WGS84Formatted = getFormattedBox(bboxObj, format, precision, coordOrder);
-            // Build projected bbox for formatting (uses projected values)
             const projBbox = {
                 lat1: projCoords.ymin,
                 lng1: projCoords.xmin,
@@ -727,20 +1022,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const shareUrl = buildShareUrl(bboxObj);
             const dims = calculateBboxDimensions(bboxObj);
             const areaKm2 = calculateBboxArea(bboxObj);
-            // Calculate center and tile indices based on WGS84 original bounds
             const centerLat = (bboxObj.lat1 + bboxObj.lat2) / 2;
             const centerLng = (bboxObj.lng1 + bboxObj.lng2) / 2;
             const tileIndices = latLngToTile(centerLat, centerLng, zoom);
             log('info', `get_bounds completed`, { epsg, format, area_km2: areaKm2 });
+            const geocodeInfo = geocodeRes ? `Matched Place: "${geocodeRes.matched_place}"\n` : '';
+            const altInfo = geocodeRes && geocodeRes.alternatives.length > 0
+                ? `Alternates: ${geocodeRes.alternatives.map(a => `"${a.matched_place}"`).join(', ')}\n\n`
+                : '\n';
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Original WGS84 Bounds (${format}):\n${WGS84Formatted}\n\nProjected to EPSG:${epsg} (${format}):\n${projectedFormatted}\n\nArea: ${areaKm2.toFixed(3)} km² (${dims.widthKm.toFixed(3)}km x ${dims.heightKm.toFixed(3)}km)\n\nView on map: ${shareUrl}`
+                        text: `${geocodeInfo}${altInfo}Original WGS84 Bounds (${format}):\n${WGS84Formatted}\n\nProjected to EPSG:${epsg} (${format}):\n${projectedFormatted}\n\nArea: ${areaKm2.toFixed(3)} km² (${dims.widthKm.toFixed(3)}km x ${dims.heightKm.toFixed(3)}km)\n\nView on map: ${shareUrl}${formatWarnings(warnings)}`
                     },
                     {
                         type: "text",
                         text: JSON.stringify({
+                            ...(geocodeRes ? { matched_place: geocodeRes.matched_place, alternatives: geocodeRes.alternatives } : {}),
                             original_wgs84: bboxObj,
                             projected: projCoords,
                             center: {
@@ -767,35 +1066,64 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const args = request.params.arguments || {};
             const resolution = args.resolution;
             const compact = args.compact || false;
+            const summaryOnly = args.summary_only || false;
             const returnGeometry = args.return_geometry || false;
+            const warnings = [];
             if (resolution === undefined) {
                 return { content: [{ type: "text", text: "Error: 'resolution' is required." }], isError: true };
             }
             let bboxObj;
+            let geocodeRes;
             if (args.location) {
                 try {
-                    bboxObj = await geocodeLocation(args.location);
+                    geocodeRes = await geocodeLocation(args.location);
+                    bboxObj = geocodeRes.bbox;
                 }
                 catch (err) {
                     if (!args.bbox) {
                         log('error', `Geocoding failed for H3 location: ${args.location}`, { error: err.message });
                         return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
                     }
-                    bboxObj = parseBBox(args.bbox);
+                    bboxObj = parseBBox(args.bbox, warnings);
                 }
             }
             else if (args.bbox) {
-                bboxObj = parseBBox(args.bbox);
+                bboxObj = parseBBox(args.bbox, warnings);
             }
             else {
                 return { content: [{ type: "text", text: "Error: Either 'location' or 'bbox' argument must be provided." }], isError: true };
             }
             const cells = getH3Cells(bboxObj, resolution, compact);
             const shareUrl = buildShareUrl(bboxObj);
-            log('info', `get_h3_indices completed`, { resolution, compact, cell_count: cells.length });
+            log('info', `get_h3_indices completed`, { resolution, compact, summary_only: summaryOnly, cell_count: cells.length });
+            if (summaryOnly) {
+                const sampleCells = cells.slice(0, 10);
+                const responseData = {
+                    resolution,
+                    compact,
+                    summary_only: true,
+                    cell_count: cells.length,
+                    sample_cells: sampleCells,
+                    original_bbox: bboxObj,
+                    share_url: shareUrl
+                };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `H3 summary: ${cells.length.toLocaleString()} cells generated at resolution ${resolution} (compacted: ${compact}).\nSample cells: ${sampleCells.join(', ')}\n\nView on map: ${shareUrl}${formatWarnings(warnings)}`
+                        },
+                        {
+                            type: "text",
+                            text: JSON.stringify(responseData, null, 2)
+                        }
+                    ]
+                };
+            }
             const responseData = {
                 resolution,
                 compact,
+                summary_only: false,
                 cell_count: cells.length,
                 cells,
                 original_bbox: bboxObj,
@@ -808,7 +1136,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [
                     {
                         type: "text",
-                        text: `H3 cells generated: ${cells.length.toLocaleString()}\nResolution: ${resolution} | Compacted: ${compact}\n\nCells:\n${JSON.stringify(cells)}\n\nView on map: ${shareUrl}`
+                        text: `H3 cells generated: ${cells.length.toLocaleString()}\nResolution: ${resolution} | Compacted: ${compact}\n\nCells:\n${JSON.stringify(cells)}\n\nView on map: ${shareUrl}${formatWarnings(warnings)}`
                     },
                     {
                         type: "text",
@@ -820,17 +1148,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         else if (toolName === "generate_share_url") {
             const args = request.params.arguments || {};
             const bbox = args.bbox;
+            const warnings = [];
             if (!bbox) {
                 return { content: [{ type: "text", text: "Error: 'bbox' is required." }], isError: true };
             }
-            const bboxObj = parseBBox(bbox);
+            const bboxObj = parseBBox(bbox, warnings);
             const shareUrl = buildShareUrl(bboxObj);
             log('info', `generate_share_url completed`, { share_url: shareUrl });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `View on map: ${shareUrl}`
+                        text: `View on map: ${shareUrl}${formatWarnings(warnings)}`
                     },
                     {
                         type: "text",
@@ -842,10 +1171,36 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ]
             };
         }
+        else if (toolName === "reverse_geocode") {
+            const args = request.params.arguments || {};
+            const lat = args.lat;
+            const lng = args.lng;
+            const zoom = args.zoom ?? 18;
+            if (lat === undefined || lng === undefined) {
+                return { content: [{ type: "text", text: "Error: Both 'lat' and 'lng' arguments are required." }], isError: true };
+            }
+            const result = await reverseGeocode(lat, lng, zoom);
+            log('info', `reverse_geocode completed`, { lat, lng, matched: result.matched_place });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Matched Location: "${result.matched_place}"\nCoordinates: (${result.center.lat.toFixed(5)}, ${result.center.lng.toFixed(5)})\nOSM Details: [${result.osm_type || 'point'}] ${result.osm_id || 'N/A'}\n\nView on map: ${result.share_url}`
+                    },
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2)
+                    }
+                ]
+            };
+        }
         else if (toolName === "search_overpass") {
             const args = request.params.arguments || {};
             const queryRaw = args.query;
             const limit = args.limit || 100;
+            const offset = args.offset || 0;
+            const timeoutSec = args.timeout_seconds || 25;
+            const useAreaBoundary = args.use_area_boundary !== false;
             const radiusMeters = args.radius_meters;
             const returnGeometry = args.return_geometry || false;
             const useCircle = typeof radiusMeters === 'number' && radiusMeters > 0;
@@ -858,20 +1213,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (queryRaw.includes("[out:") || queryRaw.includes("[timeout:") || queryRaw.includes("[bbox:")) {
                 return { content: [{ type: "text", text: "Error: Query must not contain [out:], [timeout:], or [bbox:] directives. The server handles these automatically." }], isError: true };
             }
+            const warnings = [];
             let overpassQuery;
             let searchModeLabel;
-            let centerPoint;
+            let refPoint;
             let bboxObj;
+            let geocodeRes;
+            let usedAreaId;
             if (useCircle) {
                 if (args.location) {
                     try {
-                        centerPoint = await geocodeLocationPoint(args.location);
+                        geocodeRes = await geocodeLocation(args.location);
+                        refPoint = { lat: geocodeRes.center.lat, lng: geocodeRes.center.lng, description: `geocoded center of "${geocodeRes.matched_place}"` };
                     }
                     catch (err) {
                         if (args.bbox) {
                             log('warn', `Geocoding failed for radius search, using bbox center`, { error: err.message });
-                            const fb = parseBBox(args.bbox);
-                            centerPoint = { lat: (fb.lat1 + fb.lat2) / 2, lng: (fb.lng1 + fb.lng2) / 2 };
+                            const fb = parseBBox(args.bbox, warnings);
+                            refPoint = { lat: (fb.lat1 + fb.lat2) / 2, lng: (fb.lng1 + fb.lng2) / 2, description: "centroid of provided bounding box" };
                         }
                         else {
                             log('error', `Geocoding failed for radius search: ${args.location}`, { error: err.message });
@@ -880,25 +1239,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
                 }
                 else if (args.bbox) {
-                    const fb = parseBBox(args.bbox);
-                    centerPoint = { lat: (fb.lat1 + fb.lat2) / 2, lng: (fb.lng1 + fb.lng2) / 2 };
+                    const fb = parseBBox(args.bbox, warnings);
+                    refPoint = { lat: (fb.lat1 + fb.lat2) / 2, lng: (fb.lng1 + fb.lng2) / 2, description: "centroid of provided bounding box" };
                 }
                 else {
                     return { content: [{ type: "text", text: "Error: Either 'location' or 'bbox' argument must be provided." }], isError: true };
                 }
                 const outDirective = returnGeometry ? "out geom;" : "out center;";
-                overpassQuery = `[out:json][timeout:25];\n(${queryRaw}(around:${radiusMeters},${centerPoint.lat},${centerPoint.lng}););\n${outDirective}`;
-                searchModeLabel = `circle — ${radiusMeters}m radius around (${centerPoint.lat.toFixed(5)}, ${centerPoint.lng.toFixed(5)})`;
+                const circleFilter = `(around:${radiusMeters},${refPoint.lat},${refPoint.lng})`;
+                const formattedCore = applySpatialFilter(queryRaw, circleFilter);
+                overpassQuery = `[out:json][timeout:${timeoutSec}];\n(${formattedCore});\n${outDirective}`;
+                searchModeLabel = `circle — ${radiusMeters}m radius around (${refPoint.lat.toFixed(5)}, ${refPoint.lng.toFixed(5)})`;
             }
             else {
                 if (args.location) {
                     try {
-                        bboxObj = await geocodeLocation(args.location);
+                        geocodeRes = await geocodeLocation(args.location);
+                        bboxObj = geocodeRes.bbox;
+                        refPoint = { lat: geocodeRes.center.lat, lng: geocodeRes.center.lng, description: `geocoded centroid of "${geocodeRes.matched_place}"` };
+                        if (useAreaBoundary && geocodeRes.osm_area_id) {
+                            usedAreaId = geocodeRes.osm_area_id;
+                        }
                     }
                     catch (err) {
                         if (args.bbox) {
                             log('warn', `Geocoding failed, falling back to bbox argument`, { error: err.message });
-                            bboxObj = parseBBox(args.bbox);
+                            bboxObj = parseBBox(args.bbox, warnings);
+                            refPoint = { lat: (bboxObj.lat1 + bboxObj.lat2) / 2, lng: (bboxObj.lng1 + bboxObj.lng2) / 2, description: "centroid of provided bounding box" };
                         }
                         else {
                             log('error', `Geocoding failed for overpass location: ${args.location}`, { error: err.message });
@@ -907,16 +1274,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
                 }
                 else if (args.bbox) {
-                    bboxObj = parseBBox(args.bbox);
+                    bboxObj = parseBBox(args.bbox, warnings);
+                    refPoint = { lat: (bboxObj.lat1 + bboxObj.lat2) / 2, lng: (bboxObj.lng1 + bboxObj.lng2) / 2, description: "centroid of provided bounding box" };
                 }
                 else {
                     return { content: [{ type: "text", text: "Error: Either 'location' or 'bbox' argument must be provided." }], isError: true };
                 }
                 const outDirective = returnGeometry ? "out geom;" : "out center;";
-                overpassQuery = `[out:json][timeout:25][bbox:${bboxObj.lat1},${bboxObj.lng1},${bboxObj.lat2},${bboxObj.lng2}];\n(${queryRaw};);\n${outDirective}`;
-                searchModeLabel = `bounding box`;
+                if (usedAreaId) {
+                    const formattedCore = applySpatialFilter(queryRaw, "(area.searchArea)");
+                    overpassQuery = `[out:json][timeout:${timeoutSec}];\narea(${usedAreaId})->.searchArea;\n(${formattedCore});\n${outDirective}`;
+                    searchModeLabel = `exact OSM boundary area (id: ${usedAreaId}) for "${geocodeRes?.matched_place}"`;
+                }
+                else {
+                    const formattedCore = applySpatialFilter(queryRaw, "");
+                    overpassQuery = `[out:json][timeout:${timeoutSec}][bbox:${bboxObj.lat1},${bboxObj.lng1},${bboxObj.lat2},${bboxObj.lng2}];\n(${formattedCore});\n${outDirective}`;
+                    searchModeLabel = `bounding box`;
+                }
             }
-            log('info', `search_overpass starting`, { query: queryRaw, mode: useCircle ? 'circle' : 'bbox', radius_meters: radiusMeters });
+            log('info', `search_overpass starting`, { query: queryRaw, mode: useCircle ? 'circle' : (usedAreaId ? 'area' : 'bbox'), radius_meters: radiusMeters, timeoutSec });
             const endpoints = [
                 "https://overpass-api.de/api/interpreter",
                 "https://overpass.kumi.systems/api/interpreter"
@@ -928,9 +1304,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let lastError = null;
             const params = new URLSearchParams();
             params.append('data', overpassQuery);
+            const clientTimeoutMs = (timeoutSec + 5) * 1000;
             for (const endpoint of endpoints) {
                 const controller = new AbortController();
-                const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS * 2);
+                const timeout = setTimeout(() => controller.abort(), clientTimeoutMs);
                 try {
                     log('info', `Executing Overpass query at ${endpoint}`);
                     const response = await fetch(endpoint, {
@@ -939,7 +1316,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         headers: {
                             'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
                             'Accept': 'application/json',
-                            'User-Agent': `${SERVER_NAME}/${SERVER_VERSION}`
+                            'User-Agent': `${SERVER_NAME}/${SERVER_VERSION} (https://github.com/iamvibhorsingh/bbox-mcp-server)`
                         },
                         signal: controller.signal
                     });
@@ -959,23 +1336,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             if (!data) {
                 if (lastError?.name === 'AbortError') {
-                    return { content: [{ type: "text", text: `Error: Overpass API request timed out on all endpoints after ${(FETCH_TIMEOUT_MS * 4) / 1000}s. The query or radius may be too large.` }], isError: true };
+                    return { content: [{ type: "text", text: `Error: Overpass API request timed out on all endpoints after ${clientTimeoutMs / 1000}s. The query or area may be too large.` }], isError: true };
                 }
                 throw new Error(`Overpass query failed on all endpoints: ${lastError?.message}`);
             }
             const seenIds = new Set();
             let parsedElements = (data.elements || []).reduce((acc, e) => {
-                if (seenIds.has(e.id))
+                const dedupKey = `${e.type}/${e.id}`;
+                if (seenIds.has(dedupKey))
                     return acc;
-                seenIds.add(e.id);
+                seenIds.add(dedupKey);
                 const lat = e.lat ?? e.center?.lat ?? e.geometry?.[0]?.lat;
                 const lon = e.lon ?? e.center?.lon ?? e.geometry?.[0]?.lon;
                 if (lat !== undefined && lon !== undefined) {
+                    const distM = calculateHaversineDistanceMeters(refPoint.lat, refPoint.lng, lat, lon);
                     const el = {
                         id: e.id,
                         type: e.type,
                         name: e.tags?.name || "Unnamed",
                         coordinates: { lat, lon },
+                        distance_meters: Math.round(distM * 10) / 10,
                         tags: e.tags || {}
                     };
                     if (returnGeometry && e.geometry) {
@@ -985,38 +1365,60 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 return acc;
             }, []);
-            const elementCount = parsedElements.length;
-            let truncated = false;
-            if (parsedElements.length > limit) {
-                parsedElements = parsedElements.slice(0, limit);
-                truncated = true;
+            // Deterministic sorting: sort by (distance_meters, type, id) ascending
+            const sortByDistance = args.sort_by_distance !== false;
+            parsedElements.sort((a, b) => {
+                if (sortByDistance) {
+                    const diff = (a.distance_meters ?? 0) - (b.distance_meters ?? 0);
+                    if (Math.abs(diff) > 0.001)
+                        return diff;
+                }
+                const typeDiff = (a.type || "").localeCompare(b.type || "");
+                if (typeDiff !== 0)
+                    return typeDiff;
+                return (a.id ?? 0) - (b.id ?? 0);
+            });
+            if (args.location && useAreaBoundary && !usedAreaId && geocodeRes) {
+                warnings.push(`Exact admin boundary polygon unavailable for '${geocodeRes.matched_place}', fell back to bounding box query.`);
             }
-            const shareUrl = useCircle && centerPoint
-                ? buildShareUrlCircleWithMarkers(centerPoint, radiusMeters, parsedElements)
-                : buildShareUrlWithMarkers(bboxObj, parsedElements);
-            log('info', `search_overpass completed`, { elements: elementCount, returned: parsedElements.length, truncated, mode: useCircle ? 'circle' : 'bbox' });
+            const totalCount = parsedElements.length;
+            const pagedElements = parsedElements.slice(offset, offset + limit);
+            const truncated = totalCount > offset + limit;
+            const hasMore = totalCount > offset + limit;
+            const nextOffset = hasMore ? offset + limit : undefined;
+            const shareUrl = useCircle
+                ? buildShareUrlCircleWithMarkers(refPoint, radiusMeters, pagedElements)
+                : buildShareUrlWithMarkers(bboxObj || geocodeRes.bbox, pagedElements);
+            log('info', `search_overpass completed`, { total: totalCount, returned: pagedElements.length, offset, limit, truncated, mode: useCircle ? 'circle' : (usedAreaId ? 'area' : 'bbox') });
             const responseData = {
-                search_mode: useCircle ? 'circle' : 'bbox',
-                ...(useCircle && centerPoint
-                    ? { center: centerPoint, radius_meters: radiusMeters }
-                    : { original_bbox: bboxObj }),
+                search_mode: useCircle ? 'circle' : (usedAreaId ? 'area' : 'bbox'),
+                ...(geocodeRes ? { matched_place: geocodeRes.matched_place, alternatives: geocodeRes.alternatives } : {}),
+                ...(usedAreaId ? { osm_area_id: usedAreaId } : {}),
+                distance_from: refPoint,
                 generator: data.generator,
                 osm3s: data.osm3s,
-                elements: parsedElements,
-                total_count: elementCount,
-                returned_count: parsedElements.length,
+                elements: pagedElements,
+                total_count: totalCount,
+                returned_count: pagedElements.length,
+                offset,
+                limit,
                 truncated,
+                has_more: hasMore,
+                ...(nextOffset !== undefined ? { next_offset: nextOffset } : {}),
+                pagination_hint: hasMore
+                    ? `Use offset=${nextOffset} to fetch the next page. Note: Each page re-queries Overpass; for large result sets, consider narrowing your query filters or bounding area instead of deep paging.`
+                    : "End of result set.",
                 share_url: shareUrl
             };
-            const topResults = parsedElements.slice(0, 5)
-                .map((e) => `- [${e.type}] ${e.name} (${e.coordinates.lat.toFixed(5)}, ${e.coordinates.lon.toFixed(5)})`)
+            const topResults = pagedElements.slice(0, 5)
+                .map((e) => `- [${e.type}] ${e.name} (${e.coordinates.lat.toFixed(5)}, ${e.coordinates.lon.toFixed(5)}) — ${e.distance_meters}m away`)
                 .join('\n');
-            const moreNote = parsedElements.length > 5 ? `\n  … and ${parsedElements.length - 5} more (see JSON)` : '';
+            const moreNote = pagedElements.length > 5 ? `\n  … and ${pagedElements.length - 5} more on this page (see JSON)` : '';
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Overpass query executed within a ${searchModeLabel}.\nFound ${elementCount} element${elementCount !== 1 ? 's' : ''}${truncated ? ` (showing first ${limit})` : ''}.\n\nTop results:\n${topResults}${moreNote}\n\nView on map: ${shareUrl}`
+                        text: `Overpass query executed within a ${searchModeLabel}.\nFound ${totalCount} element${totalCount !== 1 ? 's' : ''}${totalCount > limit ? ` (showing items ${offset + 1}-${offset + pagedElements.length} of ${totalCount})` : ''}.\nDistance measured from: ${refPoint.description}\n\nTop results:\n${topResults}${moreNote}\n\nView on map: ${shareUrl}${formatWarnings(warnings)}`
                     },
                     {
                         type: "text",
@@ -1027,72 +1429,119 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         else if (toolName === "list_osm_tags") {
             const args = request.params.arguments || {};
-            const category = (args.category || "").toLowerCase();
+            const category = (args.category || "").toLowerCase().trim();
             let recommendations = "";
             switch (true) {
-                case category.includes('food') || category.includes('restaurant') || category.includes('cafe'):
-                    recommendations = `Restaurants: nwr["amenity"="restaurant"]\nFast Food: nwr["amenity"="fast_food"]\nCafes: nwr["amenity"="cafe"]\nBars: nwr["amenity"="bar"]\nPubs: nwr["amenity"="pub"]`;
+                case category.includes('food') || category.includes('restaurant') || category.includes('cafe') || category.includes('pizza') || category.includes('dining'):
+                    recommendations = `Restaurants: nwr["amenity"="restaurant"]\nFast Food: nwr["amenity"="fast_food"]\nCafes: nwr["amenity"="cafe"]\nBars: nwr["amenity"="bar"]\nPubs: nwr["amenity"="pub"]\nIce Cream: nwr["amenity"="ice_cream"]\nCoffee Shops: nwr["shop"="coffee"]\nBakeries: nwr["shop"="bakery"]`;
                     break;
-                case category.includes('health') || category.includes('medical'):
-                    recommendations = `Hospitals: nwr["amenity"="hospital"]\nClinics: nwr["amenity"="clinic"]\nPharmacies: nwr["amenity"="pharmacy"]\nDoctors: nwr["amenity"="doctors"]\nDentists: nwr["amenity"="dentist"]`;
+                case category.includes('health') || category.includes('medical') || category.includes('doctor') || category.includes('hospital') || category.includes('pharmacy'):
+                    recommendations = `Hospitals: nwr["amenity"="hospital"]\nClinics: nwr["amenity"="clinic"]\nPharmacies: nwr["amenity"="pharmacy"]\nDoctors: nwr["amenity"="doctors"]\nDentists: nwr["amenity"="dentist"]\nGeneral Healthcare: nwr["healthcare"]`;
                     break;
-                case category.includes('transport') || category.includes('transit') || category.includes('traffic'):
-                    recommendations = `Parking: nwr["amenity"="parking"]\nBus Stops: nwr["highway"="bus_stop"]\nSubway Stations: nwr["railway"="station"]["station"="subway"]\nTrain Stations: nwr["railway"="station"]\nBicycle Parking: nwr["amenity"="bicycle_parking"]\nGas Stations: nwr["amenity"="fuel"]`;
+                case category.includes('transport') || category.includes('transit') || category.includes('bus') || category.includes('train') || category.includes('subway') || category.includes('gas') || category.includes('fuel') || category.includes('parking') || category.includes('airport') || category.includes('taxi'):
+                    recommendations = `Parking: nwr["amenity"="parking"]\nBus Stops: nwr["highway"="bus_stop"]\nSubway Stations: nwr["railway"="station"]["station"="subway"]\nTrain Stations: nwr["railway"="station"]\nBicycle Parking: nwr["amenity"="bicycle_parking"]\nGas Stations: nwr["amenity"="fuel"]\nFerry Terminals: nwr["amenity"="ferry_terminal"]\nAerodromes: nwr["aeroway"="aerodrome"]\nTaxi Stands: nwr["amenity"="taxi"]`;
                     break;
-                case category.includes('leisure') || category.includes('park') || category.includes('entertainment'):
+                case category.includes('leisure') || category.includes('park') || category.includes('playground') || category.includes('theatre') || category.includes('cinema'):
                     recommendations = `Parks: nwr["leisure"="park"]\nPlaygrounds: nwr["leisure"="playground"]\nTheatres: nwr["amenity"="theatre"]\nCinemas: nwr["amenity"="cinema"]\nSports Centres: nwr["leisure"="sports_centre"]`;
                     break;
-                case category.includes('retail') || category.includes('shop') || category.includes('store'):
-                    recommendations = `Supermarkets: nwr["shop"="supermarket"]\nConvenience Stores: nwr["shop"="convenience"]\nMalls: nwr["shop"="mall"]\nClothes Shops: nwr["shop"="clothes"]\nBakeries: nwr["shop"="bakery"]`;
+                case category.includes('retail') || category.includes('shop') || category.includes('store') || category.includes('supermarket') || category.includes('mall'):
+                    recommendations = `Supermarkets: nwr["shop"="supermarket"]\nConvenience Stores: nwr["shop"="convenience"]\nMalls: nwr["shop"="mall"]\nClothes Shops: nwr["shop"="clothes"]\nBakeries: nwr["shop"="bakery"]\nAlcohol Shops: nwr["shop"="alcohol"]\nHairdressers: nwr["shop"="hairdresser"]\nLaundries: nwr["shop"="laundry"]`;
                     break;
-                case category.includes('education') || category.includes('school'):
+                case category.includes('education') || category.includes('school') || category.includes('university') || category.includes('college') || category.includes('library'):
                     recommendations = `Schools: nwr["amenity"="school"]\nUniversities: nwr["amenity"="university"]\nColleges: nwr["amenity"="college"]\nKindergartens: nwr["amenity"="kindergarten"]\nLibraries: nwr["amenity"="library"]`;
                     break;
-                case category.includes('tourism') || category.includes('hotel'):
-                    recommendations = `Hotels: nwr["tourism"="hotel"]\nMotels: nwr["tourism"="motel"]\nHostels: nwr["tourism"="hostel"]\nAttractions: nwr["tourism"="attraction"]\nMuseums: nwr["tourism"="museum"]\nInformation: nwr["tourism"="information"]`;
+                case category.includes('tourism') || category.includes('hotel') || category.includes('motel') || category.includes('hostel') || category.includes('museum') || category.includes('attraction'):
+                    recommendations = `Hotels: nwr["tourism"="hotel"]\nMotels: nwr["tourism"="motel"]\nHostels: nwr["tourism"="hostel"]\nAttractions: nwr["tourism"="attraction"]\nMuseums: nwr["tourism"="museum"]\nGuest Houses: nwr["tourism"="guest_house"]\nApartments: nwr["tourism"="apartment"]\nCampsites: nwr["tourism"="camp_site"]`;
+                    break;
+                case category.includes('finance') || category.includes('bank') || category.includes('atm') || category.includes('post') || category.includes('police') || category.includes('fire') || category.includes('embassy'):
+                    recommendations = `Banks: nwr["amenity"="bank"]\nATMs: nwr["amenity"="atm"]\nPost Offices: nwr["amenity"="post_office"]\nPolice: nwr["amenity"="police"]\nFire Stations: nwr["amenity"="fire_station"]\nCourthouses: nwr["amenity"="courthouse"]\nEmbassies: nwr["office"="diplomatic"]`;
+                    break;
+                case category.includes('fitness') || category.includes('sport') || category.includes('gym') || category.includes('swimming') || category.includes('pool') || category.includes('stadium') || category.includes('golf') || category.includes('climbing'):
+                    recommendations = `Gyms: nwr["leisure"="fitness_centre"]\nSwimming Pools: nwr["leisure"="swimming_pool"]\nStadiums: nwr["leisure"="stadium"]\nSports Pitches: nwr["leisure"="pitch"]\nGolf Courses: nwr["leisure"="golf_course"]\nClimbing: nwr["sport"="climbing"]`;
+                    break;
+                case category.includes('nature') || category.includes('outdoor') || category.includes('forest') || category.includes('water') || category.includes('beach') || category.includes('peak') || category.includes('viewpoint') || category.includes('hike') || category.includes('trail'):
+                    recommendations = `Forests: nwr["landuse"="forest"]\nWater Bodies: nwr["natural"="water"]\nBeaches: nwr["natural"="beach"]\nPeaks: nwr["natural"="peak"]\nViewpoints: nwr["tourism"="viewpoint"]\nNature Reserves: nwr["leisure"="nature_reserve"]\nPicnic Sites: nwr["tourism"="picnic_site"]\nHiking Trails: way["highway"="path"]["sac_scale"]`;
+                    break;
+                case category.includes('religion') || category.includes('worship') || category.includes('church') || category.includes('mosque') || category.includes('synagogue') || category.includes('temple') || category.includes('cemetery'):
+                    recommendations = `Places of Worship: nwr["amenity"="place_of_worship"]\nChurches: nwr["amenity"="place_of_worship"]["religion"="christian"]\nMosques: nwr["amenity"="place_of_worship"]["religion"="muslim"]\nSynagogues: nwr["amenity"="place_of_worship"]["religion"="jewish"]\nTemples: nwr["amenity"="place_of_worship"]["religion"~"buddhist|hindu"]\nCemeteries: nwr["landuse"="cemetery"]`;
+                    break;
+                case category.includes('ev') || category.includes('automotive') || category.includes('car') || category.includes('charging') || category.includes('mechanic') || category.includes('rental'):
+                    recommendations = `EV Charging: nwr["amenity"="charging_station"]\nCar Repair: nwr["shop"="car_repair"]\nCar Dealers: nwr["shop"="car"]\nCar Wash: nwr["amenity"="car_wash"]\nCar Rental: nwr["amenity"="car_rental"]\nDriving Schools: nwr["amenity"="driving_school"]`;
+                    break;
+                case category.includes('nightlife') || category.includes('nightclub') || category.includes('casino') || category.includes('arcade') || category.includes('bowling') || category.includes('escape'):
+                    recommendations = `Nightclubs: nwr["amenity"="nightclub"]\nCasinos: nwr["amenity"="casino"]\nArcades: nwr["leisure"="amusement_arcade"]\nBowling Alleys: nwr["leisure"="bowling_alley"]\nEscape Rooms: nwr["leisure"="escape_game"]`;
+                    break;
+                case category.includes('utility') || category.includes('toilet') || category.includes('water') || category.includes('bench') || category.includes('waste') || category.includes('recycling') || category.includes('shower') || category.includes('locker'):
+                    recommendations = `Toilets: nwr["amenity"="toilets"]\nDrinking Water: nwr["amenity"="drinking_water"]\nBenches: nwr["amenity"="bench"]\nWaste Baskets: nwr["amenity"="waste_basket"]\nRecycling: nwr["amenity"="recycling"]\nPublic Showers: nwr["amenity"="shower"]\nLockers: nwr["amenity"="locker"]`;
+                    break;
+                case category.includes('work') || category.includes('office') || category.includes('coworking') || category.includes('conference'):
+                    recommendations = `Coworking Spaces: nwr["office"="coworking"]; nwr["amenity"="coworking_space"];\nGeneral Offices: nwr["office"]\nConference Centres: nwr["amenity"="conference_centre"]`;
+                    break;
+                case category.includes('pet') || category.includes('dog') || category.includes('vet') || category.includes('zoo') || category.includes('animal'):
+                    recommendations = `Dog Parks: nwr["leisure"="dog_park"]\nVeterinarians: nwr["amenity"="veterinary"]\nPet Shops: nwr["shop"="pet"]\nZoos: nwr["tourism"="zoo"]`;
+                    break;
+                case category.includes('childcare') || category.includes('daycare') || category.includes('child'):
+                    recommendations = `Childcare/Daycare: nwr["amenity"="childcare"]\nPlaygrounds: nwr["leisure"="playground"]`;
                     break;
                 default:
-                    recommendations = `Top categories:\n- Food: nwr["amenity"="restaurant"], nwr["amenity"="cafe"]\n- Health: nwr["amenity"="hospital"]\n- Transport: nwr["highway"="bus_stop"], nwr["amenity"="parking"]\n- Leisure: nwr["leisure"="park"]\n- Retail: nwr["shop"="supermarket"]\n- Education: nwr["amenity"="school"]\n\nPlease try searching for one of those broader categories (e.g. "health") for more detailed tag combinations.`;
+                    log('info', `Category '${category}' not in index, querying Taginfo API`);
+                    recommendations = await getTaginfoSuggestions(category);
                     break;
             }
             return {
                 content: [{
                         type: "text",
-                        text: `OSM Tag Recommendations for '${category}':\n\n${recommendations}\n\nTip: You can usually just use these directly as the 'query' argument in search_overpass.`
+                        text: `OSM Tag Recommendations for '${category}':\n\n${recommendations}\n\nTip: You can use these tag selectors directly in the 'query' argument of search_overpass.`
                     }]
             };
         }
         else if (toolName === "aggregate_overpass_h3") {
             const args = request.params.arguments || {};
             const queryRaw = args.query;
-            const resolution = args.resolution || 8;
+            const resolution = args.resolution ?? 8;
+            const timeoutSec = args.timeout_seconds || 25;
+            const useAreaBoundary = args.use_area_boundary !== false;
+            const warnings = [];
             if (!queryRaw) {
                 return { content: [{ type: "text", text: "Error: 'query' is required." }], isError: true };
             }
+            if (resolution < 0 || resolution > 15 || !Number.isInteger(resolution)) {
+                return { content: [{ type: "text", text: `Error: Invalid H3 resolution: ${resolution}. Must be 0-15.` }], isError: true };
+            }
             let bboxObj;
+            let geocodeRes;
+            let usedAreaId;
             if (args.location) {
                 try {
-                    bboxObj = await geocodeLocation(args.location);
+                    geocodeRes = await geocodeLocation(args.location);
+                    bboxObj = geocodeRes.bbox;
+                    if (useAreaBoundary && geocodeRes.osm_area_id) {
+                        usedAreaId = geocodeRes.osm_area_id;
+                    }
                 }
                 catch (err) {
                     if (!args.bbox) {
                         return { content: [{ type: "text", text: `Error: Geocoding failed: ${err.message}` }], isError: true };
                     }
-                    bboxObj = parseBBox(args.bbox);
+                    bboxObj = parseBBox(args.bbox, warnings);
                 }
             }
             else if (args.bbox) {
-                bboxObj = parseBBox(args.bbox);
+                bboxObj = parseBBox(args.bbox, warnings);
             }
             else {
                 return { content: [{ type: "text", text: "Error: Either 'location' or 'bbox' argument must be provided." }], isError: true };
             }
-            log('info', `aggregate_overpass_h3 starting`, { query: queryRaw, resolution });
-            // Ensure H3 resolution is valid early
-            if (resolution < 0 || resolution > 15 || !Number.isInteger(resolution)) {
-                return { content: [{ type: "text", text: `Error: Invalid H3 resolution: ${resolution}. Must be 0-15.` }], isError: true };
+            log('info', `aggregate_overpass_h3 starting`, { query: queryRaw, resolution, timeoutSec, mode: usedAreaId ? 'area' : 'bbox' });
+            let overpassQuery;
+            if (usedAreaId) {
+                const formattedCore = applySpatialFilter(queryRaw, "(area.searchArea)");
+                overpassQuery = `[out:json][timeout:${timeoutSec}];\narea(${usedAreaId})->.searchArea;\n(${formattedCore});\nout center;`;
+            }
+            else {
+                const formattedCore = applySpatialFilter(queryRaw, "");
+                overpassQuery = `[out:json][timeout:${timeoutSec}][bbox:${bboxObj.lat1},${bboxObj.lng1},${bboxObj.lat2},${bboxObj.lng2}];\n(${formattedCore});\nout center;`;
             }
-            const overpassQuery = `[out:json][timeout:25][bbox:${bboxObj.lat1},${bboxObj.lng1},${bboxObj.lat2},${bboxObj.lng2}];\n(${queryRaw};);\nout center;`;
             let data = null;
             let lastError = null;
             const params = new URLSearchParams();
@@ -1104,9 +1553,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (process.env.OVERPASS_API_URL) {
                 endpoints.unshift(process.env.OVERPASS_API_URL);
             }
+            const clientTimeoutMs = (timeoutSec + 5) * 1000;
             for (const endpoint of endpoints) {
                 const controller = new AbortController();
-                const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS * 2);
+                const timeout = setTimeout(() => controller.abort(), clientTimeoutMs);
                 try {
                     const response = await fetch(endpoint, {
                         method: "POST",
@@ -1114,7 +1564,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         headers: {
                             'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
                             'Accept': 'application/json',
-                            'User-Agent': `${SERVER_NAME}/${SERVER_VERSION}`
+                            'User-Agent': `${SERVER_NAME}/${SERVER_VERSION} (https://github.com/iamvibhorsingh/bbox-mcp-server)`
                         },
                         signal: controller.signal
                     });
@@ -1134,14 +1584,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: `Error: Overpass query failed: ${lastError?.message}` }], isError: true };
             }
             let rawElements = data.elements || [];
-            // Bin into H3 Hexagons
             const hexCounts = {};
             const hexElements = {};
             const seenIds = new Set();
             rawElements.forEach((e) => {
-                if (seenIds.has(e.id))
+                const dedupKey = `${e.type}/${e.id}`;
+                if (seenIds.has(dedupKey))
                     return;
-                seenIds.add(e.id);
+                seenIds.add(dedupKey);
                 const lat = e.lat ?? e.center?.lat;
                 const lon = e.lon ?? e.center?.lon;
                 if (lat !== undefined && lon !== undefined) {
@@ -1149,7 +1599,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     hexCounts[h3Index] = (hexCounts[h3Index] || 0) + 1;
                     if (!hexElements[h3Index])
                         hexElements[h3Index] = [];
-                    // Keep element data minimal to avoid massive payloads
                     hexElements[h3Index].push({
                         id: e.id,
                         name: e.tags?.name || "Unnamed"
@@ -1158,10 +1607,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             });
             const shareUrl = buildShareUrl(bboxObj);
             const totalGrouped = Object.values(hexCounts).reduce((a, b) => a + b, 0);
-            // Generate GeoJSON of the active hexes
             const activeHexes = Object.keys(hexCounts);
             const geojson = h3CellsToGeoJSON(activeHexes);
-            // Inject the counts into the GeoJSON properties
             geojson.features.forEach((f) => {
                 const cellId = f.properties.h3_index;
                 f.properties.count = hexCounts[cellId];
@@ -1170,6 +1617,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             log('info', `aggregate_overpass_h3 completed`, { resolution, elements: totalGrouped, activeHexes: activeHexes.length });
             const responseData = {
                 resolution,
+                ...(geocodeRes ? { matched_place: geocodeRes.matched_place, alternatives: geocodeRes.alternatives } : {}),
+                ...(usedAreaId ? { osm_area_id: usedAreaId } : {}),
                 total_elements: totalGrouped,
                 active_hex_count: activeHexes.length,
                 hex_counts: hexCounts,
@@ -1177,7 +1626,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 original_bbox: bboxObj,
                 share_url: shareUrl
             };
-            // Sort map for display
             const topHexes = Object.entries(hexCounts)
                 .sort((a, b) => b[1] - a[1])
                 .slice(0, 10);
@@ -1185,7 +1633,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [
                     {
                         type: "text",
-                        text: `Aggregated ${totalGrouped} element${totalGrouped !== 1 ? 's' : ''} into ${activeHexes.length} H3 hexagon${activeHexes.length !== 1 ? 's' : ''} at resolution ${resolution}.\n\nTop hexagons by density:\n${topHexes.map(([hex, count]) => `- ${hex}: ${count} element${count !== 1 ? 's' : ''}`).join('\n')}\n\nView on map: ${shareUrl}`
+                        text: `Aggregated ${totalGrouped} element${totalGrouped !== 1 ? 's' : ''} into ${activeHexes.length} H3 hexagon${activeHexes.length !== 1 ? 's' : ''} at resolution ${resolution}.\n\nTop hexagons by density:\n${topHexes.map(([hex, count]) => `- ${hex}: ${count} element${count !== 1 ? 's' : ''}`).join('\n')}\n\nView on map: ${shareUrl}${formatWarnings(warnings)}`
                     },
                     {
                         type: "text",