geotap-mcp-server 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geotap-mcp-server",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "MCP server for GeoTap — access 37 US federal environmental and infrastructure data sources from Claude, Cursor, and other AI tools",
   "type": "module",
   "main": "src/index.js",
@@ -9,7 +9,10 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "dev": "node --watch src/index.js"
+    "dev": "node --watch src/index.js",
+    "test": "node tests/unit-tests.js",
+    "test:verbose": "node tests/unit-tests.js --verbose",
+    "test:integration": "node tests/workflow-tests.js"
   },
   "keywords": [
     "mcp",

package/src/api.js

@@ -1,6 +1,95 @@
 const BASE_URL = process.env.GEOTAP_API_URL || 'https://geotapdata.com/api/v1';
 const API_KEY = process.env.GEOTAP_API_KEY || '';
 
+/**
+ * Structured API Error with fix instructions for LLMs.
+ */
+export class StructuredApiError extends Error {
+  constructor(details) {
+    super(details.message);
+    this.name = 'StructuredApiError';
+    this.details = details;
+  }
+}
+
+/**
+ * Build a structured error with fix instructions and related tools.
+ */
+function buildStructuredError(status, errorText, endpoint, method, params) {
+  const base = {
+    error: true,
+    status,
+    message: `GeoTap API error (${status}): ${errorText}`,
+    endpoint,
+    method
+  };
+
+  // Parse common error patterns and provide actionable fixes
+  const fixes = [];
+  const relatedTools = [];
+
+  if (status === 400) {
+    if (/geometry|polygon|geojson/i.test(errorText)) {
+      fixes.push('Provide a valid GeoJSON geometry object, or use lat/lng parameters instead (they will be auto-converted to GeoJSON).');
+      fixes.push('Example: { "lat": 32.08, "lng": -81.09 } instead of a GeoJSON polygon.');
+    }
+    if (/missing|required/i.test(errorText)) {
+      const missingParam = errorText.match(/(?:missing|required)[:\s]+(\w+)/i)?.[1];
+      if (missingParam) {
+        fixes.push(`Add the required parameter: "${missingParam}".`);
+      }
+    }
+    if (/lat|lng|lon|coordinate/i.test(errorText)) {
+      fixes.push('Ensure lat is between -90 and 90, lng is between -180 and 180. Note: coordinates must be within the United States.');
+      relatedTools.push('geocode_address');
+    }
+    if (/layer/i.test(errorText)) {
+      fixes.push('Use list_data_layers to see valid layer names. Layer names use underscores (e.g., flood_zones, wetlands).');
+      relatedTools.push('list_data_layers');
+    }
+    if (/bbox|bounding/i.test(errorText)) {
+      fixes.push('Bounding box format: "west,south,east,north" in WGS84 (e.g., "-81.1,32.0,-81.0,32.1"). West must be less than east, south less than north.');
+    }
+  }
+
+  if (status === 401 || status === 403) {
+    fixes.push('Set GEOTAP_API_KEY environment variable with a valid API key. Get one at https://geotapdata.com');
+    relatedTools.push('check_api_status');
+  }
+
+  if (status === 404) {
+    if (/gage|site|station/i.test(endpoint)) {
+      fixes.push('Station/gage not found. Verify the site ID is a valid USGS station number (e.g., "08158000").');
+      relatedTools.push('find_monitoring_stations', 'search_stations');
+    }
+    if (/job/i.test(endpoint)) {
+      fixes.push('Job ID not found or expired. Submit a new request to start a fresh job.');
+    }
+  }
+
+  if (status === 429) {
+    fixes.push('Rate limit exceeded. Wait a moment and retry, or upgrade your API key tier at https://geotapdata.com');
+  }
+
+  if (status >= 500) {
+    fixes.push('Server error — the upstream federal data source may be temporarily unavailable.');
+    fixes.push('Try again in a few seconds, or check check_api_status to see which services are up.');
+    relatedTools.push('check_api_status');
+  }
+
+  if (fixes.length === 0) {
+    fixes.push('Check that all required parameters are provided and valid.');
+    fixes.push('Use discover_tools to find the right tool for your question.');
+    relatedTools.push('discover_tools');
+  }
+
+  return {
+    ...base,
+    fix: fixes,
+    relatedTools: [...new Set(relatedTools)]
+  };
+}
+
 /**
  * Call the GeoTap API.
  * Handles both GET (query params) and POST (JSON body) requests.
@@ -52,7 +141,8 @@ export async function callApi(endpoint, method, params) {
 
   if (!response.ok) {
     const errorText = await response.text().catch(() => 'Unknown error');
-    throw new Error(`GeoTap API error (${response.status}): ${errorText}`);
+    const structured = buildStructuredError(response.status, errorText, endpoint, method, params);
+    throw new StructuredApiError(structured);
   }
 
   // Check content type to handle binary vs JSON responses

package/src/discoverTools.js

@@ -0,0 +1,173 @@
+/**
+ * Tool Discovery Meta-Tool
+ *
+ * With 68+ tools, LLMs waste context loading all descriptions upfront.
+ * This meta-tool lets the AI describe what it needs in natural language
+ * and get back the 3-5 most relevant tools.
+ */
+
+import { tools } from './tools.js';
+
+/**
+ * Tool categories with keywords for matching.
+ */
+const TOOL_CATEGORIES = {
+  'Getting Started': {
+    keywords: ['start', 'begin', 'address', 'location', 'what is', 'tell me about', 'lookup', 'search address', 'find address'],
+    tools: ['query_address', 'identify_features_at_point', 'geocode_address']
+  },
+  'Flood & FEMA': {
+    keywords: ['flood', 'fema', 'firm', 'floodplain', 'flood zone', 'flood insurance', 'nfhl', 'base flood', 'special flood'],
+    tools: ['query_address', 'get_firm_panels', 'get_environmental_data_for_area']
+  },
+  'Rainfall & Precipitation': {
+    keywords: ['rain', 'rainfall', 'precipitation', 'storm', 'idf', 'hyetograph', 'atlas 14', 'design storm', 'intensity', 'duration', 'frequency', 'climate change', 'climate projection'],
+    tools: ['get_rainfall_data', 'get_idf_curves', 'generate_hyetograph', 'get_rainfall_distribution', 'get_climate_change_rainfall_projection', 'get_rainfall_uncertainty_bounds', 'run_rainfall_sensitivity_analysis']
+  },
+  'Watershed & Hydrology': {
+    keywords: ['watershed', 'drainage', 'basin', 'delineate', 'hydrology', 'runoff', 'peak flow', 'streamstats', 'catchment', 'time of concentration'],
+    tools: ['delineate_watershed', 'get_watershed_characteristics', 'get_flow_statistics', 'analyze_hydrology', 'get_flowlines']
+  },
+  'Curve Number & Soils': {
+    keywords: ['curve number', 'cn', 'soil', 'hsg', 'hydrologic soil', 'runoff', 'scs', 'nrcs', 'ssurgo', 'infiltration', 'pervious', 'impervious'],
+    tools: ['analyze_curve_numbers', 'lookup_curve_number', 'get_curve_number_tables']
+  },
+  'Water Quality': {
+    keywords: ['water quality', 'impairment', 'impaired', 'pollution', 'pollutant', 'tmdl', '303d', 'attains', 'epa', 'clean water', 'npdes', 'discharge'],
+    tools: ['get_water_quality', 'get_water_impairments', 'get_watershed_for_point', 'get_watershed_water_quality']
+  },
+  'Wetlands & Species': {
+    keywords: ['wetland', 'nwi', 'endangered', 'species', 'habitat', 'critical habitat', 'protected', 'conservation', 'wildlife'],
+    tools: ['query_address', 'identify_features_at_point', 'get_environmental_data_for_area']
+  },
+  'Elevation & Terrain': {
+    keywords: ['elevation', 'dem', 'terrain', 'contour', 'topography', 'slope', 'lidar', '3dep', 'relief', 'grading'],
+    tools: ['get_elevation_stats', 'get_contour_lines', 'export_dem', 'export_contours', 'check_dem_availability']
+  },
+  'Stream Gages': {
+    keywords: ['gage', 'gauge', 'stream gage', 'streamflow', 'usgs gage', 'flood frequency', 'flow duration', 'low flow', 'storm event', 'bulletin 17', 'peak flow record', 'annual peak'],
+    tools: ['get_gage_summary', 'get_flood_frequency_analysis', 'get_flow_duration_curve', 'get_low_flow_statistics', 'get_storm_events', 'get_published_gage_statistics']
+  },
+  'Ungaged Estimation': {
+    keywords: ['ungaged', 'ungauged', 'no gage', 'regression', 'nss', 'regional equation', 'estimate flow', 'similar watershed'],
+    tools: ['estimate_ungaged_flood_frequency', 'estimate_all_ungaged_statistics', 'find_similar_watersheds', 'recommend_index_gage', 'transfer_flood_statistics']
+  },
+  'Permits & Regulatory': {
+    keywords: ['permit', 'regulatory', 'section 404', 'usace', 'army corps', 'waterway', 'crossing', 'construction near water', '401 certification'],
+    tools: ['find_water_features', 'analyze_permit_requirements']
+  },
+  'Site Analysis & Reports': {
+    keywords: ['site analysis', 'report', 'assessment', 'due diligence', 'developability', 'constraints', 'can i build', 'feasibility', 'environmental review'],
+    tools: ['generate_site_analysis', 'generate_constraints_report', 'generate_developability_report']
+  },
+  'Monitoring Stations': {
+    keywords: ['station', 'monitoring', 'weather station', 'tide', 'groundwater', 'well', 'camera', 'sensor'],
+    tools: ['find_monitoring_stations', 'search_stations', 'get_station_types']
+  },
+  'Data Export': {
+    keywords: ['export', 'download', 'shapefile', 'geojson', 'csv', 'kml', 'geopackage', 'geotiff', 'gis', 'cad'],
+    tools: ['export_data', 'get_export_options', 'export_dem', 'export_contours', 'export_land_use', 'export_satellite_imagery']
+  },
+  'Land Use & Imagery': {
+    keywords: ['land use', 'land cover', 'nlcd', 'satellite', 'imagery', 'aerial', 'naip', 'impervious surface', 'developed', 'forest'],
+    tools: ['export_land_use', 'export_satellite_imagery', 'get_satellite_resolution_options']
+  },
+  'HUC Watersheds': {
+    keywords: ['huc', 'hydrologic unit', 'watershed boundary', 'wbd', 'huc8', 'huc10', 'huc12', 'subwatershed'],
+    tools: ['get_huc_watersheds', 'get_huc_watershed_by_code', 'get_watershed_for_point']
+  },
+  'API Status': {
+    keywords: ['status', 'health', 'api', 'available', 'working', 'service', 'down', 'outage'],
+    tools: ['check_api_status', 'check_specific_api_status', 'check_rainfall_service_status']
+  }
+};
+
+/**
+ * Find the most relevant tools for a natural language question.
+ */
+export function discoverTools(question, maxResults = 5) {
+  const q = question.toLowerCase();
+  const scores = {};
+
+  // Score each category by keyword matches
+  for (const [category, config] of Object.entries(TOOL_CATEGORIES)) {
+    let score = 0;
+    for (const keyword of config.keywords) {
+      if (q.includes(keyword)) {
+        score += keyword.split(' ').length; // Multi-word matches score higher
+      }
+    }
+    if (score > 0) {
+      for (const toolName of config.tools) {
+        scores[toolName] = (scores[toolName] || 0) + score;
+      }
+    }
+  }
+
+  // Also score by tool description similarity
+  for (const tool of tools) {
+    const desc = tool.description.toLowerCase();
+    const words = q.split(/\s+/).filter(w => w.length > 3);
+    let descScore = 0;
+    for (const word of words) {
+      if (desc.includes(word)) descScore += 0.5;
+    }
+    if (descScore > 0) {
+      scores[tool.name] = (scores[tool.name] || 0) + descScore;
+    }
+  }
+
+  // Sort by score and return top N
+  const ranked = Object.entries(scores)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, maxResults);
+
+  // Build result with tool details
+  const toolMap = new Map(tools.map(t => [t.name, t]));
+  const results = ranked.map(([name, score]) => {
+    const tool = toolMap.get(name);
+    if (!tool) return null;
+
+    // Build parameter info
+    const params = {};
+    if (tool.parameters) {
+      for (const [pName, pSchema] of Object.entries(tool.parameters)) {
+        params[pName] = {
+          type: pSchema._def?.typeName || 'unknown',
+          required: !pSchema.isOptional?.(),
+          description: pSchema._def?.description || pSchema.description || ''
+        };
+      }
+    }
+
+    return {
+      name: tool.name,
+      description: tool.description.split('.')[0] + '.', // First sentence only
+      method: tool.method,
+      parameters: params,
+      relevanceScore: Math.round(score * 10) / 10
+    };
+  }).filter(Boolean);
+
+  // Find matching categories
+  const matchedCategories = [];
+  for (const [category, config] of Object.entries(TOOL_CATEGORIES)) {
+    let score = 0;
+    for (const keyword of config.keywords) {
+      if (q.includes(keyword)) score++;
+    }
+    if (score > 0) matchedCategories.push({ category, relevance: score });
+  }
+  matchedCategories.sort((a, b) => b.relevance - a.relevance);
+
+  return {
+    question,
+    recommendedTools: results,
+    matchedCategories: matchedCategories.slice(0, 3).map(c => c.category),
+    allCategories: Object.keys(TOOL_CATEGORIES),
+    hint: results.length > 0
+      ? `Start with "${results[0].name}" — it's the best match for your question.`
+      : 'No strong matches found. Try query_address for location-based questions, or list_data_layers to see available data.',
+    totalToolsAvailable: tools.length
+  };
+}

package/src/index.js

@@ -4,12 +4,21 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { tools } from './tools.js';
-import { callApi } from './api.js';
+import { callApi, StructuredApiError } from './api.js';
 import { toolSources } from './sources.js';
+import { capResponse } from './responseCap.js';
+import { generateSummary } from './summaries.js';
+import { convertLatLng } from './latLngHelper.js';
+import { discoverTools } from './discoverTools.js';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const server = new McpServer({
   name: 'geotap',
-  version: '1.2.0',
+  version: '1.3.0',
   description: 'Access 37 US federal environmental and infrastructure data sources. Query flood zones, wetlands, soils, rainfall, watersheds, water quality, endangered species, elevation, land use, and more for any location in the United States.',
   instructions: `You have access to GeoTap, which provides real-time data from 37 US federal agencies (FEMA, USGS, NOAA, EPA, NRCS, USFWS, USACE, and more).
 
@@ -18,15 +27,25 @@ START HERE — CORE TOOLS (use these for 90% of queries):
 2. identify_features_at_point — Same as above but when you already have lat/lng coordinates.
 3. get_rainfall_data — NOAA Atlas 14 precipitation data for any US location.
 4. get_environmental_summary — Quick feature counts for an area (no geometry, just numbers).
-5. geocode_address — Convert address to coordinates (only needed if query_address doesn't cover your use case).
+5. discover_tools — Don't know which tool to use? Describe your question and get the best matches.
 
-These 5 tools handle most questions. Use specialized tools only when these don't cover the request.
+NEW IN v1.3: SMART FEATURES:
+- Every response includes a _summary field with a plain-English description.
+- POST endpoints accept flat lat/lng parameters — no need to construct GeoJSON.
+- Responses are automatically capped to prevent context window overflow.
+- Structured error messages tell you exactly how to fix issues.
+- Use discover_tools to find the right tool from 68+ options.
 
 RESPONSE SIZE MANAGEMENT:
 - query_address and identify_features_at_point always return <5KB (no geometry, just properties + interpretations).
 - For all other spatial tools, ALWAYS set geometry="none" unless the user specifically needs coordinates.
 - Always specify layers (e.g., layers="flood_zones,wetlands") instead of querying all 19 layers.
-- In urban areas, full-geometry responses can exceed 1MB. Geometry="none" reduces this to <10KB.
+- Responses are now auto-capped at 50 features per layer with summaries.
+
+LAT/LNG SHORTCUT:
+- POST tools that normally require GeoJSON now accept { lat, lng } instead.
+- Example: generate_site_analysis({ lat: 32.08, lng: -81.09 }) — auto-converts to GeoJSON Point.
+- For polygon tools, lat/lng creates a ~0.5km bounding box around the point.
 
 COMMON WORKFLOWS:
 - "What flood zone is this address in?" → query_address (one call, done)
@@ -38,14 +57,52 @@ COMMON WORKFLOWS:
 
 IMPORTANT NOTES:
 - All data comes from authoritative federal sources. Always mention the source agency.
-- Responses include _interpretation fields with plain-English summaries — use these in your answers.
+- Responses include _summary with plain-English summaries — use these in your answers.
+- Responses include _interpretation fields with per-feature context — reference these too.
 - This data is for informational purposes. Remind users to verify critical data for engineering/regulatory decisions.
 - Coordinates must be within the United States (including territories).
 - Some tools (watershed delineation, hydrology) can take 10-60 seconds.
 - Layer names use underscores: flood_zones, wetlands, dem_elevation, building_footprints, etc.`
 });
 
-// Register all tools
+// ── Register discover_tools meta-tool ───────────────────────────────
+
+server.tool(
+  'discover_tools',
+  'Find the best GeoTap tools for your question. Describe what you need in plain English and get back the 3-5 most relevant tools with their parameters. Use this when you have 68 tools and aren\'t sure which one to pick.',
+  {
+    question: z.string().describe('Natural language description of what you want to do (e.g., "What flood zone is this property in?" or "I need rainfall data for stormwater design")'),
+    maxResults: z.number().optional().describe('Maximum tools to return (default: 5)')
+  },
+  async (params) => {
+    const result = discoverTools(params.question, params.maxResults || 5);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+
+// ── Register get_llms_txt tool ──────────────────────────────────────
+
+server.tool(
+  'get_llms_txt',
+  'Get the GeoTap API discovery document (llms.txt). Returns a structured description of all API endpoints, data sources, and usage tips optimized for AI agents. Use this to understand the full API before making queries.',
+  {},
+  async () => {
+    try {
+      const content = readFileSync(join(__dirname, 'llms.txt'), 'utf-8');
+      return { content: [{ type: 'text', text: content }] };
+    } catch {
+      return {
+        content: [{ type: 'text', text: 'llms.txt not found. Visit https://geotapdata.com/llms.txt for API documentation.' }],
+        isError: true
+      };
+    }
+  }
+);
+
+// ── Register all API tools ──────────────────────────────────────────
+
 for (const tool of tools) {
   server.tool(
     tool.name,
@@ -53,12 +110,28 @@ for (const tool of tools) {
     tool.parameters,
     async (params) => {
       try {
-        const result = await callApi(tool.endpoint, tool.method, params);
+        // Improvement #3: Convert lat/lng to GeoJSON if needed
+        const convertedParams = convertLatLng(tool.name, params);
+
+        // Strip internal fields before sending to API
+        const apiParams = { ...convertedParams };
+        delete apiParams._latLngConverted;
+
+        const rawResult = await callApi(tool.endpoint, tool.method, apiParams);
 
-        // Enrich response with source attribution and data freshness
+        // Improvement #1: Cap response size
+        const { data: cappedResult, wasCapped, capInfo } = capResponse(tool.name, rawResult);
+
+        // Improvement #2: Generate natural language summary
+        const summary = generateSummary(tool.name, params, cappedResult);
+
+        // Enrich response with source attribution, summary, and metadata
         const sources = toolSources[tool.name] || [];
         const enriched = {
-          ...result,
+          ...(summary ? { _summary: summary } : {}),
+          ...cappedResult,
+          ...(convertedParams._latLngConverted ? { _latLngConverted: convertedParams._latLngConverted } : {}),
+          ...(wasCapped ? { _responseCapped: capInfo } : {}),
           _meta: {
             sources,
             retrievedAt: new Date().toISOString(),
@@ -70,8 +143,21 @@ for (const tool of tools) {
           content: [{ type: 'text', text: JSON.stringify(enriched, null, 2) }]
         };
       } catch (error) {
+        // Improvement #5: Structured error messages
+        if (error instanceof StructuredApiError) {
+          return {
+            content: [{ type: 'text', text: JSON.stringify(error.details, null, 2) }],
+            isError: true
+          };
+        }
+
         return {
-          content: [{ type: 'text', text: `Error: ${error.message}` }],
+          content: [{ type: 'text', text: JSON.stringify({
+            error: true,
+            message: error.message,
+            fix: ['Check that all required parameters are provided and valid.', 'Use discover_tools to find the right tool for your question.'],
+            relatedTools: ['discover_tools', 'check_api_status']
+          }, null, 2) }],
           isError: true
         };
       }

package/src/latLngHelper.js

@@ -0,0 +1,137 @@
+/**
+ * Lat/Lng Convenience Helper
+ *
+ * Automatically converts flat lat/lng parameters to GeoJSON geometry
+ * for POST endpoints that require GeoJSON input. This eliminates the
+ * #1 error pattern where LLMs get GeoJSON wrong (especially lng/lat order).
+ */
+
+/**
+ * Tools that accept geometry/polygon/location as GeoJSON but could
+ * accept lat/lng instead for point-based queries.
+ */
+const GEOMETRY_TOOLS = {
+  // Tools that accept 'polygon' parameter — convert lat/lng to small bounding box
+  get_environmental_data_for_area: { param: 'polygon', type: 'bbox' },
+  get_environmental_summary: { param: 'polygon', type: 'bbox' },
+  find_water_features: { param: 'polygon', type: 'bbox' },
+  export_dem: { param: 'polygon', type: 'bbox' },
+  export_contours: { param: 'polygon', type: 'bbox' },
+  export_land_use: { param: 'polygon', type: 'bbox' },
+  export_satellite_imagery: { param: 'polygon', type: 'bbox' },
+
+  // Tools that accept 'geometry' parameter — convert to Point
+  generate_site_analysis: { param: 'geometry', type: 'point' },
+  generate_constraints_report: { param: 'geometry', type: 'point' },
+  generate_developability_report: { param: 'geometry', type: 'point' },
+  export_data: { param: 'geometry', type: 'point' },
+
+  // Tools that accept 'location' parameter — convert to Point
+  get_water_quality: { param: 'location', type: 'point' },
+
+  // Tools that accept 'catchments' parameter — convert to small polygon FeatureCollection
+  analyze_hydrology: { param: 'catchments', type: 'featureCollection' },
+  analyze_curve_numbers: { param: 'catchments', type: 'featureCollection' },
+};
+
+/** Default radius in km for converting a point to a small bounding box */
+const DEFAULT_RADIUS_KM = 0.5;
+
+/**
+ * If the tool accepts GeoJSON and the user provided lat/lng instead,
+ * convert to the appropriate GeoJSON structure.
+ *
+ * Returns the (possibly modified) params object.
+ */
+export function convertLatLng(toolName, params) {
+  if (!params) return params;
+
+  const config = GEOMETRY_TOOLS[toolName];
+  if (!config) return params;
+
+  // Only convert if lat/lng are present AND the geometry param is missing
+  const hasLatLng = params.lat !== undefined && (params.lng !== undefined || params.lon !== undefined);
+  const hasGeometry = params[config.param] !== undefined;
+
+  if (!hasLatLng || hasGeometry) return params;
+
+  const lat = Number(params.lat);
+  const lng = Number(params.lng ?? params.lon);
+
+  if (isNaN(lat) || isNaN(lng)) return params;
+
+  const newParams = { ...params };
+  delete newParams.lat;
+  delete newParams.lng;
+  delete newParams.lon;
+
+  const radiusKm = params.radius || DEFAULT_RADIUS_KM;
+
+  switch (config.type) {
+    case 'point':
+      newParams[config.param] = {
+        type: 'Point',
+        coordinates: [lng, lat]
+      };
+      break;
+
+    case 'bbox': {
+      const bbox = createBBox(lat, lng, radiusKm);
+      newParams[config.param] = {
+        type: 'Polygon',
+        coordinates: [bbox]
+      };
+      break;
+    }
+
+    case 'featureCollection': {
+      const bbox = createBBox(lat, lng, radiusKm);
+      newParams[config.param] = {
+        type: 'FeatureCollection',
+        features: [{
+          type: 'Feature',
+          properties: { name: 'Area of Interest' },
+          geometry: {
+            type: 'Polygon',
+            coordinates: [bbox]
+          }
+        }]
+      };
+      break;
+    }
+  }
+
+  // Add a note so the LLM knows what happened
+  newParams._latLngConverted = {
+    originalLat: lat,
+    originalLng: lng,
+    convertedTo: config.type,
+    radiusKm: config.type !== 'point' ? radiusKm : undefined,
+    note: `Converted lat/lng to ${config.type === 'point' ? 'GeoJSON Point' : `${radiusKm}km bounding box polygon`}. For custom areas, pass a GeoJSON ${config.param} directly.`
+  };
+
+  return newParams;
+}
+
+/**
+ * Create a bounding box polygon from lat/lng and radius in km.
+ * Returns coordinates array for a GeoJSON Polygon ring.
+ */
+function createBBox(lat, lng, radiusKm) {
+  // Approximate degrees per km
+  const latDeg = radiusKm / 111.32;
+  const lngDeg = radiusKm / (111.32 * Math.cos(lat * Math.PI / 180));
+
+  const south = lat - latDeg;
+  const north = lat + latDeg;
+  const west = lng - lngDeg;
+  const east = lng + lngDeg;
+
+  return [
+    [west, south],
+    [east, south],
+    [east, north],
+    [west, north],
+    [west, south]  // close the ring
+  ];
+}