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. 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)	INLINECODE0	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"	INLINECODE8 + 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. 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	INLINECODE17	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 → INLINECODE23
• Just need to know "it's northeast" → INLINECODE24

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	INLINECODE25	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	INLINECODE32 (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. 1. Search stores → category_search_tool (returns distances automatically)
2. Create coverage zone → buffer_tool (5km geometric circle)
3. Visualize → INLINECODE43

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. 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. 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. 1. Clean GPS trace → map_matching_tool (snap to bike paths)
2. Get distance → Use API response or calculate with INLINECODE54

Why: Need road/path matching; distance calculation either way works

Scenario 5: Coverage Analysis

User: "What's our total service area?"

Optimal approach:

1. 1. Create buffers around each location → INLINECODE55
2. Calculate total area → INLINECODE56
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

CODEBLOCK0

Why wrong: As the crow flies ≠ as the crow drives

❌ Don't: Use routing APIs for geometric operations

CODEBLOCK1

Why wrong: Routing APIs don't do geometric containment

❌ Don't: Confuse "near" with "reachable"

CODEBLOCK2

Why wrong: Roads aren't straight lines; traffic varies

❌ Don't: Use routing when bearing is sufficient

CODEBLOCK3

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

CODEBLOCK4

Use case: "Find gas stations along my route"

Pattern 2: Routing + Distance Calculation

CODEBLOCK5

Use case: Quickly narrow down, then get precise routing for finalists

Pattern 3: Isochrone + Containment

CODEBLOCK6

Use case: "Which customers are in our delivery zone?"

Decision Algorithm

When user asks a geospatial question:

CODEBLOCK7

Key Decision Questions

Before choosing a tool, ask:

1. 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

1. 2. Does the user need travel time?

- Yes → routing APIs (only they know speeds/traffic) - No → geometric tools may suffice

1. 3. Is this about roads/paths or pure spatial relationships?

- Roads/paths → routing APIs - Spatial relationships → geometric tools

1. 4. Does this need to happen in real-time with low latency?

- Yes + geometric problem → offline tools (instant) - Yes + routing problem → use routing APIs (still fast)

1. 5. Is accuracy critical, or is approximation OK?

- Critical + routing → routing APIs - Approximation OK → geometric tools may work

Terminology Guide

Understanding what users mean:

User Says	Usually Means	Tool Type
"Distance"	Context-dependent! Ask: crow flies or crow drives?	Varies
"How far"

Often as the crow drives (road distance) | Routing API |
| "Nearby" | Usually as the crow flies (straight-line radius) | Geometric |
| "Close" | Could be either - clarify! | Ask |
| "Reachable" | Travel-time based (crow drives with traffic) | Routing API |
| "Inside/contains" | Geometric containment | Geometric |
| "Navigate/directions" | Turn-by-turn routing | Routing API |
| "Bearing/direction" | Compass direction (crow flies) | Geometric |

Quick Reference

Geometric Operations (Offline Tools)

• - distance_tool - Straight-line distance between two points
• INLINECODE59 - Compass direction from A to B
• INLINECODE60 - Midpoint between two points
• INLINECODE61 - Is point inside polygon?
• INLINECODE62 - Calculate polygon area
• INLINECODE63 - Create circular buffer/zone
• INLINECODE64 - Geometric center of polygon
• INLINECODE65 - Min/max coordinates of geometry
• INLINECODE66 - Reduce geometry complexity

Routing & Navigation (APIs)

• - directions_tool - Turn-by-turn routing
• INLINECODE68 - Many-to-many travel times
• INLINECODE69 - Route optimization (TSP)
• INLINECODE70 - Travel-time zones
• INLINECODE71 - Snap GPS to roads

When to Use Each Category

Use Geometric Tools When:

• - Problem is spatial/mathematical (containment, area, bearing)
• Straight-line distance is appropriate
• Need instant results for real-time checks
• Pure geometry (no roads/traffic involved)

Use Routing APIs When:

• - Need actual driving/walking/cycling distances
• Need travel times
• Need to consider road networks
• Need traffic awareness
• Need route optimization
• Need turn-by-turn directions

Integration with Other Skills

Works with:

• - mapbox-search-patterns: Search for locations, then use geospatial operations
• mapbox-web-performance-patterns: Optimize rendering of geometric calculations
• mapbox-token-security: Ensure requests use properly scoped tokens

Resources

• - Mapbox MCP Server
• Turf.js Documentation (Powers geometric tools)
• Mapbox Directions API
• Mapbox Isochrone API
• Mapbox Matrix API
• Mapbox Optimization API