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:
- Offline Geometric Tools - Use Turf.js for pure geometric/spatial calculations
- 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?"
- Create zone →
isochrone_tool (routing API - need travel time)
- 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:
- Search stores →
category_search_tool (returns distances automatically)
- Create coverage zone →
buffer_tool (5km geometric circle)
- 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:
- 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.
- 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:
- Create delivery zone →
isochrone_tool (30-minute driving)
- 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:
- Clean GPS trace →
map_matching_tool (snap to bike paths)
- 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:
- Create buffers around each location →
buffer_tool
- Calculate total area →
area_tool
- 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
distance_tool({ from: A, to: B });
directions_tool({
coordinates: [
{ longitude: A[0], latitude: A[1] },
{ longitude: B[0], latitude: B[1] }
],
routing_profile: 'mapbox/driving'
});
Why wrong: As the crow flies ≠ as the crow drives
❌ Don't: Use routing APIs for geometric operations
point_in_polygon_tool({ point: location, polygon: boundary });
Why wrong: Routing APIs don't do geometric containment
❌ Don't: Confuse "near" with "reachable"
distance_tool + calculate 20min * avg_speed
isochrone_tool({
coordinates: {longitude: startLng, latitude: startLat},
contours_minutes: [20],
profile: "mapbox/driving"
})
Why wrong: Roads aren't straight lines; traffic varies
❌ Don't: Use routing when bearing is sufficient
directions_tool({
coordinates: [
{ longitude: hotel[0], latitude: hotel[1] },
{ longitude: airport[0], latitude: airport[1] }
]
});
bearing_tool({ from: hotel, to: airport });
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
1. directions_tool → Get route geometry
2. buffer_tool → Create corridor around route
3. category_search_tool → Find POIs in corridor
4. point_in_polygon_tool → Filter to those actually along route
Use case: "Find gas stations along my route"
Pattern 2: Routing + Distance Calculation
1. category_search_tool → Find 10 nearby locations
2. distance_tool → Calculate straight-line distances (geometric)
3. For top 3, use directions_tool → Get actual driving time
Use case: Quickly narrow down, then get precise routing for finalists
Pattern 3: Isochrone + Containment
1. isochrone_tool → Create travel-time zone (routing)
2. point_in_polygon_tool → Check hundreds of addresses (geometric)
Use case: "Which customers are in our delivery zone?"
Decision Algorithm
When user asks a geospatial question:
1. Does it require routing, roads, or travel times?
