Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs

Mapbox Geospatial Operations Skill Expert guidance for AI assistants on choosing the right geospatial tools from the Mapbox MCP Server. Focuses on selecting tools based on what the problem requires geometric calculations vs routing, straight line vs road network, and accuracy needs. Core Principle: Problem Type Determines Tool Choice The Mapbox MCP Server provides two categories of geospatial tools: 1. Offline Geometric Tools Use Turf.js for pure geometric/spatial calculations 2. Routing & Navigation APIs Use Mapbox APIs when you need real world routing, traffic, or travel times The key question: What does the problem actually require? Decision Framework Problem Characteristic Tool Category Why Straight line distance (as the crow flies) Offline geometric Accurate for geometric distance Road/path distance (as the crow drives) Routing API Only routing APIs know road networks Travel time Routing API Requires routing with speed/traffic data Point containment (is X inside Y?) Offline geometric Pure geometric operation Geographic shapes (buffers, centroids, areas) Offline geometric Mathematical/geometric operations Traffic aware routing Routing API Requires real time traffic data Route optimization (best order to visit) Routing API Complex routing algorithm High frequency checks (e.g., real time geofencing) Offline geometric Instant response, no latency Decision Matrices by Use Case Distance Calculations User asks: "How far is X from Y?" What They Actually Mean Tool Choice Why Straight line distance (as the crow flies) distance tool Accurate for geometric distance, instant Driving distance (as the crow drives) directions tool Only routing knows actual road distance Walking/cycling distance (as the crow walks/bikes) directions tool Need specific path network Travel time directions tool or matrix tool Requires routing with speed data Distance with current traffic directions tool (driving traffic) Need real time traffic consideration Example: "What's the distance between these 5 warehouses?" As the crow flies → distance tool (10 calculations, instant) As the crow drives → matrix tool (5×5 matrix, one API call, returns actual route distances) Key insight: Use the tool that matches what "distance" means in context. Always clarify: crow flies or crow drives? Proximity and Containment User asks: "Which points are near/inside this area?" Query Type Tool Choice Why "Within X meters radius" distance tool + filter Simple geometric radius "Within X minutes drive" isochrone tool → point in polygon tool Need routing for travel time zone, then geometric containment "Inside this polygon" point in polygon tool Pure geometric containment test "Reachable by car in 30 min" isochrone tool Requires routing + traffic "Nearest to this point" distance tool (geometric) or matrix tool (routed) Depends on definition of "nearest" Example: "Are these 200 addresses in our 30 minute delivery zone?" 1. Create zone → isochrone tool (routing API need travel time) 2. Check addresses → point in polygon tool (geometric 200 instant checks) Key insight: Routing for creating travel time zones, geometric for containment checks Routing and Navigation User asks: "What's the best route?" Scenario Tool Choice Why A to B directions directions tool Turn by turn routing Optimal order for multiple stops optimization tool Solves traveling salesman problem Clean GPS trace map matching tool Snaps to road network Just need bearing/compass direction bearing tool Simple geometric calculation Route with traffic directions tool (driving traffic) Real time traffic awareness Fixed order waypoints directions tool with waypoints Routing through specific points Example: "Navigate from hotel to airport" Need turn by turn → directions tool Just need to know "it's northeast" → bearing tool Key insight: Routing tools for actual navigation, geometric tools for directional info Area and Shape Operations User asks: "Create a zone around this location" Requirement Tool Choice Why Simple circular buffer buffer tool Geometric circle/radius Travel time zone isochrone tool Based on routing network Calculate area size area tool Geometric calculation Simplify complex boundary simplify tool Geometric simplification Find center of shape centroid tool Geometric centroid Example: "Show 5km coverage around each store" 5km radius → buffer tool (geometric circles) "What customers can reach in 15 min?" → isochrone tool (routing based) Key insight: Geometric tools for distance based zones, routing tools for time based zones Performance and Scale Considerations When Volume Affects Tool Choice Small operations (< 100 calculations): Geometric tools: Instant, iterate freely Routing APIs: Fast enough for most uses Medium operations (100 1,000 calculations): Geometric tools: Still fast, no concerns Routing APIs: Consider batch operations (matrix tool) Large operations ( 1,000 calculations): Geometric tools: May need optimization but still fast Routing APIs: Definitely use batch tools (matrix tool handles up to 25×25) Key insight: Volume rarely affects geometric tool choice, but routing APIs have batch tools for efficiency Real Time vs Batch Use Case Approach Tool Choice Real time geofencing (every second) Geometric checks point in polygon tool (instant) Route planning (one time) Full routing directions tool or optimization tool Periodic proximity checks Geometric distance distance tool Live traffic routing Routing with traffic directions tool (driving traffic) Architecture note for high frequency geofencing: If the application calls containment checks at very high rates (e.g., 50 vehicles every 2 seconds = 25 checks/second), calling MCP tools over the network adds agent reasoning overhead that makes it impractical. In those cases, recommend using Turf.js directly in process ( turf.booleanPointInPolygon ) for the hot path, and reserve MCP tools for peripheral tasks like zone definition ( isochrone tool ), rerouting ( directions tool ), or visualization ( static map image tool ). Common Scenarios and Optimal Approaches Scenario 1: Store Locator User: "Find the closest store and show 5km coverage" Optimal approach: 1. Search stores → category search tool (returns distances automatically) 2. Create coverage zone → buffer tool (5km geometric circle) 3. Visualize → static map image tool Why: Search already gives distances; geometric buffer for simple radius Scenario 2: Delivery Route Optimization User: "Optimize delivery to 8 addresses / stops" Optimal approach: 1. Geocode addresses (if needed) → Use search and geocode tool to convert any street addresses to coordinates. Even when coordinates are already provided, mention this as an optional pre step — real world delivery lists often contain a mix of addresses and coordinates. 2. Optimize route → optimization tool (TSP solver — reorders stops to minimize total drive time) Why optimization tool and NOT these alternatives: directions tool only routes A → B (or through fixed order waypoints). It does NOT reorder stops — if you pass 8 stops, it routes them in the order given, which is almost never optimal. matrix tool gives travel times between all pairs of stops (8×8 = 64 values), but it does NOT compute the optimal ordering. You'd need to solve TSP yourself on top of the matrix — optimization tool does this for you in one call. Always mention search and geocode tool as a useful companion for geocoding delivery addresses before optimization. Scenario 3: Service Area Validation User: "Which of these 200 addresses can we deliver to in 30 minutes?" Optimal approach: 1. Create delivery zone → isochrone tool (30 minute driving) 2. Check each address → point in polygon tool (200 geometric checks) Why: Routing for accurate travel time zone, geometric for fast containment checks Scenario 4: GPS Trace Analysis User: "How long was this bike ride?" Optimal approach: 1. Clean GPS trace → map matching tool (snap to bike paths) 2. Get distance → Use API response or calculate with distance tool Why: Need road/path matching; distance calculation either way works Scenario 5: Coverage Analysis User: "What's our total service area?" Optimal approach: 1. Create buffers around each location → buffer tool 2. Calculate total area → area tool 3. Or, if time based → isochrone tool for each location Why: Geometric for distance based coverage, routing for time based Anti Patterns: Using the Wrong Tool Type ❌ Don't: Use geometric tools for routing questions Why wrong: As the crow flies ≠ as the crow drives ❌ Don't: Use routing APIs for geometric operations Why wrong: Routing APIs don't do geometric containment ❌ Don't: Confuse "near" with "reachable" Why wrong: Roads aren't straight lines; traffic varies ❌ Don't: Use routing when bearing is sufficient Why better: Simpler, instant, answers the actual question Hybrid Approaches: Combining Tool Types Some problems benefit from using both geometric and routing tools: Pattern 1: Routing + Geometric Filter Use case: "Find gas stations along my route" Pattern 2: Routing + Distance Calculation Use case: Quickly narrow down, then get precise routing for finalists Pattern 3: Isochrone + Containment Use case: "Which customers are in our delivery zone?" Decision Algorithm When user asks a geospatial question: Key Decision Questions Before choosing a tool, ask: 1. Does "distance" mean as the crow flies or as the crow drives? As the crow flies (straight line) → geometric tools As the crow drives (road distance) → routing APIs 2. Does the user need travel time? Yes → routing APIs (only they know speeds/traffic) No → geometric tools may suffice 3. Is this about roads/paths or pure spatial relationships? Roads/paths → routing APIs Spatial relationships → geometric tools 4. Does this

mapbox-geospatial-operations