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"
Optimal approach:
Geocode addresses →
search_and_geocode_tool
Optimize route →
optimization_tool
(TSP solver with routing)
Why:
Need actual routing for turn-by-turn delivery, not geometric distances
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
// WRONG: User asks "how long to drive there?"
distance_tool
(
{
from
:
A
,
to
:
B
}
)
;
// Returns 10km as the crow flies, but actual drive is 15km
// CORRECT: Need routing for driving distance
directions_tool
(
{
coordinates
:
[
{
longitude
:
A
[
0
]
,
latitude
:
A
[
1
]
}
,
{
longitude
:
B
[
0
]
,
latitude
:
B
[
1
]
}
]
,
routing_profile
:
'mapbox/driving'
}
)
;
// Returns actual road distance and drive time as the crow drives
Why wrong:
As the crow flies ≠ as the crow drives
❌ Don't: Use routing APIs for geometric operations
// WRONG: Check if point is in polygon
// (Can't do this with routing APIs)
// CORRECT: Pure geometric operation
point_in_polygon_tool
(
{
point
:
location
,
polygon
:
boundary
}
)
;
Why wrong:
Routing APIs don't do geometric containment
❌ Don't: Confuse "near" with "reachable"
// User asks: "What's reachable in 20 minutes?"
// WRONG: 20-minute distance at average speed
distance_tool
+
calculate 20min
*
avg_speed
// CORRECT: Actual routing with road network
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
// User asks: "Which direction is the airport?"
// OVERCOMPLICATED: Full routing
directions_tool
(
{
coordinates
:
[
{
longitude
:
hotel
[
0
]
,
latitude
:
hotel
[
1
]
}
,
{
longitude
:
airport
[
0
]
,
latitude
:
airport
[
1
]
}
]
}
)
;
// BETTER: Just need bearing
bearing_tool
(
{
from
:
hotel
,
to
:
airport
}
)
;
// Returns: "Northeast (45°)"
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
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?
YES → Use routing API (directions, matrix, isochrone, optimization)
NO → Continue
2. Does it require traffic awareness?
YES → Use directions_tool or isochrone_tool with traffic profile
NO → Continue
3. Is it a geometric/spatial operation?
- Distance between points (straight-line) → distance_tool
- Point containment → point_in_polygon_tool
- Area calculation → area_tool
- Buffer/zone → buffer_tool
- Direction/bearing → bearing_tool
- Geometric center → centroid_tool
- Bounding box → bounding_box_tool
- Simplification → simplify_tool
4. Is it a search/discovery operation?
YES → Use search tools (search_and_geocode, category_search)
Key Decision Questions
Before choosing a tool, ask:
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
Does the user need travel time?
Yes → routing APIs (only they know speeds/traffic)
No → geometric tools may suffice
Is this about roads/paths or pure spatial relationships?
Roads/paths → routing APIs
Spatial relationships → geometric tools
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)
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
bearing_tool
- Compass direction from A to B
midpoint_tool
- Midpoint between two points
point_in_polygon_tool
- Is point inside polygon?
area_tool
- Calculate polygon area
buffer_tool
- Create circular buffer/zone
centroid_tool
- Geometric center of polygon
bbox_tool
- Min/max coordinates of geometry
simplify_tool
- Reduce geometry complexity
Routing & Navigation (APIs)
directions_tool
- Turn-by-turn routing
matrix_tool
- Many-to-many travel times
optimization_tool
- Route optimization (TSP)
isochrone_tool
- Travel-time zones
map_matching_tool
- 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