The Mapbox MCP Server equips AI agents with geospatial intelligence, combining Mapbox APIs and offline calculations.
Search & Discovery: Geocode addresses and coordinates, search for places by keyword or category, reverse geocode, get place details (photos, hours, ratings), and use ground_location_tool to simultaneously reverse geocode, find nearby POIs, and generate isochrones.
Navigation & Routing: Get driving, walking, or cycling directions with traffic, solve the traveling salesman problem for up to 12 stops, compute travel time matrices, snap GPS traces to roads, and generate isochrones for reachable areas.
Spatial Analysis (Offline): Calculate distance, bearing, midpoint, destination, area, buffer, bounding box, centroid, convex hull, simplify geometries, length, nearest point, point-in-polygon, union, intersection, and difference — all without API calls.
Visualization: Create static map images with overlays or render interactive maps directly in supported chat clients.
Resource Access: Retrieve available POI categories via resources.
Provides access to Mapbox's geospatial services including geocoding, points of interest search, multi-modal routing, travel time matrices, route optimization, map matching, isochrone generation, static map images, and offline geospatial calculations.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Mapbox MCP Server Find coffee shops near the Empire State Building"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Node.js server implementing Model Context Protocol (MCP) for Mapbox APIs.
The Mapbox MCP Server transforms any AI agent or application into a geospatially-aware system by providing seamless access to Mapbox's comprehensive location intelligence platform. With this server, your AI can understand and reason about places, navigate the physical world, and access rich geospatial data including:
Global geocoding to convert addresses and place names to coordinates and vice versa
Points of interest (POI) search across millions of businesses, landmarks, and places worldwide
Multi-modal routing for driving, walking, and cycling with real-time traffic
Travel time matrices to analyze accessibility and optimize logistics
Route optimization to find the optimal visiting order for multiple stops (traveling salesman problem)
Map matching to snap GPS traces to the road network for clean route visualization
Isochrone generation to visualize areas reachable within specific time or distance constraints
Live, interactive map rendering (render_map_tool) to display routes, search results, and your own custom GeoJSON on a real Mapbox GL JS map directly inside the chat
Static map images to create visual representations of locations, routes, and geographic data
Offline geospatial calculations for distance, area, bearing, buffers, and spatial analysis without requiring API calls
Whether you're building an AI travel assistant, logistics optimizer, location-based recommender, or any application that needs to understand "where", the Mapbox MCP Server provides the spatial intelligence to make it possible. You can also enable it on popular clients like Claude Desktop and VS Code. See below for details
A Mapbox access token is required to use this MCP server.
Related MCP server: Mapbox MCP Server
For quick access, you can use our hosted MCP endpoint:
Endpoint: https://mcp.mapbox.com/mcp
For detailed setup instructions for different clients and API usage, see the Hosted MCP Server Guide.
To get a Mapbox access token:
Sign up for a free Mapbox account at mapbox.com/signup
Navigate to your Account page
Create a new token or use the default public token
For more information about Mapbox access tokens, see the Mapbox documentation on access tokens.
For detailed setup instructions for different integrations, refer to the following guides:
Claude Desktop Setup - Instructions for configuring Claude Desktop to work with this MCP server
Goose Setup - Setting up Goose AI agent framework
VS Code Setup - Setting up a development environment in Visual Studio Code
Cursor AI IDE Setup - Setting up a development environment in Cursor AI IDE
Smolagents Integration - Example showing how to connect Smolagents AI agents to Mapbox's tools
Importing Tools Directly - Use Mapbox tools in your own applications without running the MCP server
render_map_tool Guide - The map visualization primitive: full payload schema and how to render your own data standalone, without any other Mapbox tool
Elicitations - How search_and_geocode_tool and directions_tool ask the user to disambiguate results or pick a route, and how they fall back gracefully when the client doesn't support it
Try these prompts with Claude Desktop or other MCP clients after setup:
For coordinate-first queries — "what's near me", "what neighborhood is this", "what's reachable in N minutes" — use ground_location_tool. It composes reverse geocoding, category search, and isochrone in a single call, adaptively choosing the right strategy based on the query, and returns typed records (names, addresses, coordinates, distances, reachability polygons) with citations.
Each of the four prompts below exercises a different strategy in one tool call:
Neighborhood — "What neighborhood is 47.6097, -122.3408, and what's around me?"
POI — "Coffee shops within a 10-minute walk of 40.7580, -73.9855"
Region — "What can I reach in a 15-minute walk from 37.7749, -122.4194?"
Routing — "Closest routable point to drop someone off at 34.0522, -118.2437"
"Find coffee shops within walking distance of the Empire State Building"
"I want to go from Seattle to Portland, is there a Starbucks along the way?"
"Show me gas stations along the route from Boston to New York"
"What restaurants are near Times Square?"
"Get driving directions from LAX to Hollywood with current traffic"
"How long would it take to walk from Central Park to Times Square?"
"Calculate travel time from my hotel (Four Seasons) to JFK Airport by taxi during rush hour"
"Using the Mapbox map render tool, show me directions from the Golden Gate Bridge to Union Square in San Francisco" — renders a live, interactive route on a real Mapbox map
"Create a map image showing the route from Golden Gate Bridge to Fisherman's Wharf with markers at both locations"
"Show me a satellite view of Manhattan with key landmarks marked"
"Generate a map highlighting all Starbucks locations within a mile of downtown Seattle"
"Show a fill polygon over these coordinates: [...], with a marker labeled 'Warehouse' at [...]" — renders your own GeoJSON directly via render_map_tool, no other Mapbox tool needed
"Show me areas reachable within 30 minutes of downtown Portland by car"
"Calculate a travel time matrix between these 3 hotel locations (Marriott, Sheraton and Hilton) and the convention center in Denver"
"Find the optimal route visiting these 3 tourist attractions (Golden Gate, Musical Stairs and Fisherman's Wharf) in San Francisco"
"Optimize a delivery route for these 8 addresses: [list of addresses]"
"Clean up this GPS trace and show the actual route on roads: [list of coordinates with timestamps]"
"Snap this recorded bicycle ride to the cycling network: [GPS coordinates]"
"Match this driving route to the road network and show traffic congestion levels"
"What's the distance in miles between these two coordinates?"
"Calculate the area of this polygon in square kilometers"
"Is the point at 37.7749°N, 122.4194°W inside this service area polygon?"
"What's the bearing from San Francisco to New York?"
"Find the midpoint between London and Paris"
"Create a 5-mile buffer zone around this location"
"Calculate the centroid of this neighborhood boundary"
"What's the bounding box for these route coordinates?"
"Simplify this complex polygon to reduce the number of points"
Be specific about locations (use full addresses or landmark names)
Specify your preferred travel method (driving, walking, cycling)
Include time constraints when relevant ("during rush hour", "at 3 PM")
Ask for specific output formats when needed ("as a map image", "in JSON format")
Detailed examples: See examples/search-along-route.md for comprehensive examples of the search-along-route prompt with different use cases and MCP Inspector testing instructions.
The MCP server exposes static reference data as MCP resources. Resources provide read-only access to data that clients can reference directly without making tool calls.
URI Pattern: mapbox://categories or mapbox://categories/{language}
Access the complete list of available category IDs for use with the category search tool. Categories can be used to filter search results by type (e.g., "restaurant", "hotel", "gas_station").
Examples:
mapbox://categories - Default (English) category list
mapbox://categories/ja - Japanese category names
mapbox://categories/es - Spanish category names
Accessing Resources:
Clients with native MCP resource support: Use the resources/read MCP protocol method
Clients without resource support: Use the resource_reader_tool with the resource URI
render_map_tool)Every geospatial tool in this server (directions, isochrone, search, and more) can display its result as a live, interactive Mapbox GL JS map via render_map_tool — the server's single visualization primitive. It renders through the MCP Apps protocol (@modelcontextprotocol/ext-apps) as a self-contained HTML panel directly inside the chat, with a Fullscreen toggle, in supported clients:
Claude Desktop ✅
VS Code with GitHub Copilot ✅
Claude Code ✅
Goose ✅
You don't need any of this server's other tools to use it. render_map_tool also accepts hand-composed GeoJSON directly — your own polygons, markers, and routes — with no dependency on directions_tool, isochrone_tool, or any other Mapbox API call. See the full render_map_tool guide for the payload schema and a complete standalone example.
If you need a guaranteed static image in clients without MCP Apps support, use static_map_image_tool instead — it returns a base64-encoded PNG/JPEG that every client can display.
Resource Fallback Tools (Opt-In for Non-Compliant Clients)
Resources are a core MCP feature supported by most clients (Claude Desktop, VS Code, MCP Inspector, etc.). However, some clients (like smolagents) don't support resources at all. For these clients, the server can provide "resource fallback tools" that deliver the same content as resources but via tool calls.
Fallback Tools:
resource_reader_tool - Generic fallback for reading any resource by URI
category_list_tool - Provides access to category list (mapbox://categories)
By default, these tools are NOT included (assumes your client supports resources). If your client doesn't support resources, enable the fallback tools:
export CLIENT_NEEDS_RESOURCE_FALLBACK=trueWhen to set this:
✅ Set to true if using smolagents or other clients without resource support
❌ Leave unset (default) if using Claude Desktop, VS Code, MCP Inspector, or any resource-capable client
❌ Leave unset if unsure (most clients support resources)
Provides access to MCP resources for clients that don't support the native MCP resource API. Use this tool to read resources like the category list.
Parameters:
uri: The resource URI to read (e.g., mapbox://categories, mapbox://categories/ja)
Example Usage:
Read default categories: {"uri": "mapbox://categories"}
Read Japanese categories: {"uri": "mapbox://categories/ja"}
Note: If your MCP client supports native resources, prefer using the resource API directly for better performance.
These tools perform geospatial calculations completely offline without requiring Mapbox API calls. They use Turf.js for accurate geographic computations and work anywhere, even without internet connectivity.
Calculate the distance between two geographic coordinates using the Haversine formula.
Features:
Supports multiple units: kilometers, miles, meters, feet, nautical miles
Accurate great-circle distance calculation
No API calls required
Example Usage: "What's the distance between San Francisco (37.7749°N, 122.4194°W) and New York (40.7128°N, 74.0060°W)?"
Test one or more points against a polygon or multipolygon, returning only those inside. Handles a single point or a batch in one call.
Features:
Works with complex polygons including holes
Supports multipolygons
Batch-tests any number of points in one call
Useful for geofencing, delivery zone validation, and customer segmentation
Example Usage: "Which of these delivery addresses are inside our service area?"
Calculate a destination point given a starting point, bearing, and distance using geodesic (great-circle) offset.
Features:
Straight-line offset, not a routed path
Useful for "find a point 5km north of X" or constructing search offsets
No API calls required
Example Usage: "What's the point 10km northeast of the Space Needle?"
Calculate the compass direction (bearing) from one coordinate to another.
Features:
Returns bearing in degrees (0-360°)
Provides cardinal direction (N, NE, E, SE, S, SW, W, NW)
Useful for navigation and directional queries
Example Usage: "What direction should I head to go from here to the airport?"
Find the geographic midpoint between two coordinates along the great circle path.
Features:
Calculates true midpoint on Earth's curved surface
Useful for meeting point suggestions
Handles long-distance calculations correctly
Example Usage: "What's halfway between San Francisco and New York?"
Calculate the geometric center (centroid) of a polygon or multipolygon.
Features:
Works with complex shapes
Returns arithmetic mean of all points
Useful for placing labels or markers
Example Usage: "Where should I place a marker for this neighborhood boundary?"
Calculate the area of a polygon.
Features:
Supports multiple units: square meters, square kilometers, acres, hectares, square miles, square feet
Accurate area calculation on Earth's surface
Works with polygons of any size
Example Usage: "What's the area of this park in acres?"
Calculate the minimum bounding box (bbox) that contains a geometry.
Features:
Works with points, lines, polygons, and multipolygons
Returns [minLongitude, minLatitude, maxLongitude, maxLatitude]
Useful for viewport calculations and spatial indexing
Example Usage: "What's the bounding box for this route?"
Create a buffer zone (polygon) around a point, line, or polygon.
Features:
Supports multiple distance units
Creates circular buffers around points
Useful for proximity analysis and creating zones of influence
Example Usage: "Show me a 5km buffer zone around this location"
Reduce the number of vertices in a line or polygon using the Douglas-Peucker algorithm.
Features:
Configurable tolerance for detail level
Preserves overall shape while reducing complexity
Useful for reducing file sizes and improving rendering performance
Option to maintain topology (prevent self-intersections)
Example Usage: "Simplify this complex boundary to reduce the number of points"
Measure the total length of a line defined by a series of coordinates.
Features:
Supports kilometers, miles, meters, and feet
Useful for measuring a drawn route, path, or boundary without a routing API call
Example Usage: "How long is this hiking trail?"
Compute the convex hull of a set of points — the smallest convex polygon containing all of them.
Features:
Useful for bounding-area analysis or estimating coverage area
Works offline without API calls
Example Usage: "What's the smallest polygon that contains all of these store locations?"
Find the nearest point in a collection to a given target point.
Features:
More efficient than calling distance_tool for each candidate and sorting
Useful for finding the closest store, stop, or landmark to a location
Example Usage: "Which of these stores is closest to my current location?"
Snap a point to the nearest position on a line or route, returning that point and the distance to it.
Features:
Useful for "which point on this route is closest to my location?" or map-matching without an API call
Example Usage: "Where on this hiking trail am I closest to right now?"
Combine or compare two or more polygons — union_tool merges them into one geometry, intersect_tool finds the area they share, and difference_tool subtracts one from another.
Features:
Useful for combining service areas, finding coverage overlap, or computing exclusion zones (e.g. "what's covered by zone A but not zone B?")
Works entirely offline — no API calls required
Each returns a render_map_tool reference so the result can be visualized directly
Example Usage: "Combine these two delivery zones into one coverage area" / "Where do these two isochrones overlap?" / "What part of this service area isn't covered by our 15-minute isochrone?"
⚠️ Deprecated: Use the resource_reader_tool with URI mapbox://categories instead, or access the mapbox://categories resource directly if your client supports MCP resources.
This tool is maintained for backward compatibility with clients that don't support MCP resources or the resource_reader_tool.
Calculates travel times and distances between multiple points using Mapbox Matrix API. Features include:
Efficient one-to-many, many-to-one or many-to-many routing calculations
Support for different travel profiles (driving-traffic, driving, walking, cycling)
Departure time specification for traffic-aware calculations
Route summarization with distance and duration metrics
Control approach (curb/unrestricted) and range of allowed departure bearings
Generates static map images using the Mapbox static image API. Features include:
Custom map styles (streets, outdoors, satellite, etc.)
Adjustable image dimensions and zoom levels
Support for multiple markers with custom colors and labels
Overlay options including polylines and polygons
Auto-fitting to specified coordinates
Performs a category search using the Mapbox Search Box category search API. Features include:
Search for points of interest by category (restaurants, hotels, gas stations, etc.)
Filtering by geographic proximity
Customizable result limits
Rich metadata for each result
Support for multiple languages
Performs reverse geocoding using the Mapbox geocoding V6 API. Features include:
Convert geographic coordinates to human-readable addresses
Customizable levels of detail (street, neighborhood, city, etc.)
Results filtering by type (address, poi, neighborhood, etc.)
Support for multiple languages
Rich location context information
Answers "what's near this coordinate" questions in a single call — place name, nearby points of interest, and travel-time reachability — sourced from live Mapbox data with citations. Use this instead of chaining reverse_geocode_tool with a web search.
Features:
Classifies the query (routing, neighborhood context, POI search, or region/reachability) and fetches only the relevant data
Nearby POI search by category, when requested
Travel-time reachability summary (isochrone-based)
Returns a render_map_tool reference with the grounded location and nearby POIs plotted
Example Usage: "What neighborhood is this coordinate in, and are there any coffee shops nearby?"
Retrieves detailed information about a specific place using its Mapbox ID — photos, opening hours, ratings, phone numbers, and website URLs. Use after search_and_geocode_tool, category_search_tool, or reverse_geocode_tool to get more detail on a specific result.
Example Usage: "Tell me more about that first coffee shop result — hours, phone number, and website"
Fetches routing directions using the Mapbox Directions API. Features include:
Support for different routing profiles: driving (with live traffic or typical), walking, and cycling
Route from multiple waypoints (2-25 coordinate pairs)
Alternative routes option
Route annotations (distance, duration, speed, congestion)
Scheduling options:
Future departure time (depart_at) for driving and driving-traffic profiles
Desired arrival time (arrive_by) for driving profile only
Profile-specific optimizations:
Driving: vehicle dimension constraints (height, width, weight)
Exclusion options for routing:
Common exclusions: ferry routes, cash-only tolls
Driving-specific exclusions: tolls, motorways, unpaved roads, tunnels, country borders, state borders
Custom point exclusions (up to 50 geographic points to avoid)
GeoJSON geometry output format
Computes areas that are reachable within a specified amount of times from a location using Mapbox Isochrone API. Features include:
Support for different travel profiles (driving, walking, cycling)
Customizable travel times or distances
Multiple contour generation (e.g., 15, 30, 45 minute ranges)
Optional departure or arrival time specification
Color customization for visualization
Uses the Mapbox Search Box Text Search API endpoint to power searching for and geocoding POIs, addresses, places, and any other types supported by that API. This tool consolidates the functionality that was previously provided by the ForwardGeocodeTool and PoiSearchTool (from earlier versions of this MCP server) into a single tool.
Snaps GPS traces to the road network using the Mapbox Map Matching API. Features include:
Convert noisy GPS traces to clean routes on the road network
Support for different travel profiles (driving, driving-traffic, walking, cycling)
Handle up to 100 coordinate pairs per request
Optional timestamps for improved accuracy based on speed
Configurable snap radiuses for different GPS quality levels
Route annotations (speed limits, distance, duration, traffic congestion)
Multiple geometry output formats (GeoJSON, polyline)
Example Usage: "Clean up this GPS trace and snap it to roads: [coordinates with timestamps]"
Finds the optimal route through multiple locations using the Mapbox Optimization API. Features include:
Solve traveling salesman problem (TSP) for 2-12 locations
Support for different travel profiles (driving, driving-traffic, walking, cycling)
Flexible start and end point configuration
Roundtrip or one-way trip optimization
Turn-by-turn navigation instructions (optional)
Route annotations (distance, duration, speed)
Multiple geometry output formats (GeoJSON, polyline)
Example Usage: "Find the optimal route to visit these 5 stops: [list of addresses or coordinates]"
Note: A V2 API with advanced features (time windows, capacity constraints, multiple vehicles) is available but requires beta access. The V2 implementation is included in the codebase but not registered by default.
# Run the built image
npm run inspect:build# Build the Docker image
docker build -t mapbox-mcp-server .
# Run and inspect the server
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-servernpx plop create-tool
# provide tool name without suffix (e.g. Search)# 1. Bump version in package.json
npm version <new-version> --no-git-tag-version
# 2. Sync version to manifest.json and server.json
npm run sync-manifest
# 3. Prepare CHANGELOG (replaces "Unreleased" with version and date)
npm run changelog:prepare-release <new-version>
# 4. Update package-lock.json
npm install
# 5. Review changes, then commit and tag
git add package.json package-lock.json manifest.json server.json CHANGELOG.md
git commit -m "Release v<new-version>"
git tag v<new-version>
git push && git push --tagsImportant: The publisher workflow validates that package.json and server.json versions match the release version. Skipping the version bump or manifest sync will cause publish failures.
This MCP server includes comprehensive OpenTelemetry tracing for production observability:
# 1. Copy the example configuration
cp .env.example .env
# 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing
# 3. Start Jaeger for local development
npm run tracing:jaeger:start
# 4. Run the server (it will automatically use .env configuration)
npm run inspect:build
# 5. View traces at http://localhost:16686
# 6. Stop Jaeger when done
npm run tracing:jaeger:stopNote: The server automatically loads configuration from your .env file at startup. The .env.example file includes configuration examples for multiple observability platforms.
Configuration examples included in .env.example for:
Cloud Providers:
☁️ AWS X-Ray
☁️ Azure Monitor (Application Insights)
☁️ Google Cloud Trace
SaaS Platforms:
📊 Datadog
📊 New Relic
📊 Honeycomb
📊 Any OTLP-compatible backend
See docs/tracing.md for complete setup instructions including:
🔧 Platform-specific configuration guides
📊 Authentication and endpoint setup
🎯 Custom trace attributes and context
🚀 Performance optimization (minimal overhead)
🔍 Troubleshooting and debugging
Tracing Features:
✅ Configuration loading tracing (.env file loading)
✅ Automatic tool execution tracing
✅ HTTP request instrumentation with CloudFront correlation IDs
✅ Configurable exporters (console, OTLP)
✅ Security-conscious (data protection, JWT validation)
✅ Production-ready (<1% CPU overhead)
We welcome contributions to the Mapbox MCP Server! Please read CONTRIBUTING.md before submitting a pull request.
Full standards and guidelines:
CONTRIBUTING.md - Getting started, PR process, quick reference
Engineering Standards (docs/engineering_standards.md) - Complete code quality, testing, documentation, and collaboration standards
Claude Code Guide (CLAUDE.md) - Standards and patterns for contributors using Claude Code
AI Agent Instructions (AGENTS.md) - Guide for other AI coding assistants (Cursor, Continue, Aider, etc.)
GitHub Copilot Guidelines - Best practices for using GitHub Copilot responsibly
Fork the repository and clone your fork
Install dependencies: npm install
Make your changes following our coding standards
Run tests and linting: npm test && npm run lint
Add tests for any new functionality
Submit a pull request with a clear description
All contributions must pass our CI checks and code review process. See docs/engineering_standards.md for detailed requirements.
When you use the MCP server tools, the following data is sent directly from your environment to Mapbox APIs:
Geocoding tools: Address/location text, coordinates, country/region filters
Search tools: Search queries, location coordinates for proximity, category filters
Directions tool: Start/end coordinates, waypoints, routing preferences, vehicle constraints
Matrix tool: Multiple coordinate pairs, travel profile, departure times
Static map tool: Coordinates, zoom level, styling preferences, marker information
Isochrone tool: Origin coordinates, time/distance parameters, travel profile
Local execution: All API calls are made directly from your environment to Mapbox APIs
Token security: Your Mapbox API token remains on your local machine and is never transmitted to or stored by this MCP server
No data storage: This MCP server does not store, log, or collect any of your data or API requests
Direct communication: There is no intermediary server between you and Mapbox APIs
Mapbox's privacy policy governs data sent to their APIs: https://www.mapbox.com/legal/privacy/
API usage: Standard Mapbox API terms apply to all requests made through these tools
Data retention: Refer to Mapbox's documentation for their data retention policies
Email: mcp-feedback@mapbox.com
GitHub Issues: Report bugs and feature requests
Mapbox Support: https://support.mapbox.com/
Documentation: https://docs.mapbox.com/
API Status: https://status.mapbox.com/
This MCP server is officially maintained by Mapbox, Inc. We provide:
Regular updates for new Mapbox API features
Bug fixes and security updates
Compatibility with latest MCP protocol versions
Community support through GitHub issues
Calculate the area of a polygon or multipolygon. Supports various units including square meters, kilometers, acres, and hectares. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| units | No | Unit of measurement for area | meters |
| geometry | Yes | Polygon or MultiPolygon coordinates. Polygon: array of rings (first is outer, rest are holes). MultiPolygon: array of polygons. |
| Name | Required | Description |
|---|---|---|
| area | Yes | Calculated area |
| units | Yes | Unit of measurement |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds valuable context: 'Works offline without API calls' and 'Supports various units', which go beyond what annotations provide. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core function, and contains no unnecessary words. Highly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the geometry parameter and the existence of an output schema, the description covers essential aspects: offline capability, units, and geometry type. It could mention return value, but output schema fills that gap. Slightly incomplete but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with detailed descriptions for both geometry and units. The description only reiterates the units support without adding new meaning. Baseline 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Calculate the area of a polygon or multipolygon', which is a specific verb and resource. It distinguishes from sibling tools like length_tool or distance_tool by focusing on area.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for area calculations but does not explicitly state when to use this tool versus alternatives (e.g., when to use area_tool vs bbox_tool or length_tool). No when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the bounding box (extent) of any geometry. Returns the minimum and maximum longitude and latitude that encompass the geometry. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| geometry | Yes | Geometry coordinates (Point, LineString, Polygon, or MultiPolygon) |
| Name | Required | Description |
|---|---|---|
| bbox | Yes | Bounding box as [minLon, minLat, maxLon, maxLat] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by stating it works offline without API calls, which is a behavioral trait not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every sentence adds necessary information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (handling multiple geometry types), the description explains the output and offline capability. Output schema exists, so return value details are not needed. Lacks only a brief note on expected geometry formats, but schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions of the geometry parameter. The description adds 'any geometry' but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it calculates the bounding box of any geometry and returns min/max longitude and latitude. It uses a specific verb and resource, distinguishing it from sibling tools like area_tool or centroid_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it works offline, hinting at usage when API calls are not desired, but it does not explicitly state when to use this tool versus alternatives or provide any exclusions or prerequisites. Minimal guidance beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the bearing (compass direction) from one point to another. Returns bearing in degrees where 0° is North, 90° is East, 180° is South, and 270° is West. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Ending coordinate | |
| from | Yes | Starting coordinate |
| Name | Required | Description |
|---|---|---|
| to | Yes | |
| from | Yes | |
| bearing | Yes | Bearing in degrees (0-360, where 0 is North) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the specific bearing output format (0°=North, etc.) and offline capability, which provide some behavioral context beyond annotations but no mention of error handling or precision.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences cover purpose, output format, and a key advantage (offline). No wasted words; every sentence adds value. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two required params, no enums) and the presence of an output schema (not repeated in description), the description is complete. It explains the return unit and offline capability, leaving no obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with full type and bound descriptions. The description does not add any additional meaning beyond what the schema provides; it only restates the general purpose. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Calculate the bearing (compass direction) from one point to another' with specific verb and resource. It also explains the output format (degrees with cardinal directions), distinguishing it from sibling tools like distance_tool and directions_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions 'Works offline without API calls', providing a usage advantage, but offers no explicit guidance on when not to use or alternatives among siblings (e.g., directions_tool for complex routes). The usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a buffer zone (polygon) around a point, line, or polygon at a specified distance. Useful for proximity analysis, service areas, or creating zones of influence. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| units | No | Unit of measurement for distance | kilometers |
| distance | Yes | Buffer distance | |
| geometry | Yes | Geometry coordinates (Point, LineString, or Polygon) |
| Name | Required | Description |
|---|---|---|
| units | Yes | |
| distance | Yes | |
| bufferedPolygon | Yes | Buffer polygon as array of rings |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds the valuable behavioral detail 'Works offline without API calls,' which goes beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The purpose is stated first, followed by use cases and a key feature. Perfectly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, an output schema, and annotations, the description covers the essential functionality, use cases, and an important operational detail (offline capability). No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters well. The description adds context about geometry types (point, line, polygon) but does not provide significant additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a buffer zone around point, line, or polygon geometry. It specifies the action and resource, but does not explicitly differentiate from sibling tools like distance_tool or area_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases: 'proximity analysis, service areas, or creating zones of influence.' While it does not mention when not to use or name alternatives, the context is sufficient for an AI agent to understand appropriate applications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return all places that match a category (industry, amenity, or NAICS‑style code). Use when the user asks for a type of place, plural or generic terms like 'museums', 'coffee shops', 'electric‑vehicle chargers', or when the query includes is‑a phrases such as 'any', 'all', 'nearby'. Do not use when a unique name or brand is provided. Supports both JSON and text output formats.
| Name | Required | Description | Default |
|---|---|---|---|
| bbox | No | Bounding box to limit results within specified bounds | |
| limit | No | Maximum number of results to return (1-25) | |
| format | No | Output format: "json_string" returns raw GeoJSON data as a JSON string that can be parsed; "formatted_text" returns human-readable text with place names, addresses, and coordinates. Both return as text content but json_string contains parseable JSON data while formatted_text is for display. | formatted_text |
| country | No | Array of ISO 3166 alpha 2 country codes to limit results | |
| category | Yes | The canonical place category name to search for (e.g., "restaurant", "hotel", "cafe"). To get the full list of supported categories, use the category_list_tool. | |
| language | No | IETF language tag for the response (e.g., "en", "es", "fr", "de", "ja") | |
| proximity | No | Location to bias results towards as {longitude, latitude}. If not provided, defaults to IP-based location. | |
| poi_category_exclusions | No | Array of POI categories to exclude from results |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| features | Yes | |
| attribution | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that it returns places, supports JSON and text output, and mentions category types, providing useful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose, efficient and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 100% schema coverage, annotations, and an output schema, the description covers purpose, usage guidance, and output formats adequately. Lacks pagination details but limit parameter is clear. Generally complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 8 parameters. The description only restates output format options, adding no new parameter semantics beyond what's already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns places by category, specifies types of categories (industry, amenity, NAICS), and provides usage examples that distinguish it from sibling tools like search_and_geocode_tool by instructing not to use when a unique name is given.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (generic terms, plural, 'any', 'all', 'nearby') and when not to use (unique name or brand), offering clear decision criteria for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the geometric center (centroid) of a polygon or multipolygon. The centroid is the arithmetic mean position of all points in the shape. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| geometry | Yes | Polygon or MultiPolygon coordinates. Polygon: array of rings (first is outer, rest are holes). MultiPolygon: array of polygons. |
| Name | Required | Description |
|---|---|---|
| centroid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safe behavior is clear. The description adds an explanation of centroid definition but no additional behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the purpose, second provides definition and offline nature. No superfluous words, front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no side effects) and the existence of an output schema, the description is largely complete. It lacks mention of the return type, but that is covered by output schema. Overall sufficient for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the single parameter 'geometry' completely. The description does not add any further parameter-level semantics, which is acceptable given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates the centroid of a polygon or multipolygon, using a specific verb and resource. It distinguishes itself from sibling tools like area_tool or midpoint_tool by focusing on geometric center computation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions 'works offline without API calls' which implies it can be used when network is unavailable, but provides no explicit guidance on when to use this tool versus alternatives, nor any conditions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute the convex hull of a set of points — the smallest convex polygon that contains all the points. Useful for bounding area analysis, estimating coverage area, or wrapping a set of locations. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| points | Yes | Points to compute the convex hull from (minimum 3) |
| Name | Required | Description |
|---|---|---|
| geometry | Yes | GeoJSON Polygon geometry of the convex hull, or null if hull could not be computed |
| num_points | Yes | Number of input points used |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds that it works offline, which is behavioral context beyond annotations. No contradictions, and the description is consistent with the non-destructive, read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, no redundancy. It front-loads the primary definition, then adds use cases and an offline note. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter, comprehensive annotations, and an output schema (mentioned in context), the description provides sufficient context. It covers what, why, and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the points parameter well-described in the schema (type, minItems, nested structure). The description does not add further parameter details, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Compute the convex hull of a set of points — the smallest convex polygon that contains all the points.' It provides a specific verb and resource, and distinguishes from sibling tools like area_tool or bbox_tool by defining its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases: 'Useful for bounding area analysis, estimating coverage area, or wrapping a set of locations.' It also notes 'Works offline without API calls,' which helps with context. However, it does not directly contrast with specific sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate a destination point given a starting point, bearing, and distance using geodesic (great-circle) straight-line offset. Useful for "find a point 5km north of X", constructing search offsets, or computing waypoints. Bearing: 0=north, 90=east, 180/-180=south, -90=west. Note: this calculates a straight-line geographic offset, not road-network distance. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| units | No | Units for the distance | meters |
| origin | Yes | Starting point | |
| bearing | Yes | Direction of travel in degrees (0=north, 90=east, -90=west, 180=south) | |
| distance | Yes | Distance to travel |
| Name | Required | Description |
|---|---|---|
| units | Yes | Distance units |
| bearing | Yes | Bearing used |
| distance | Yes | Distance traveled |
| destination | Yes | The calculated destination point |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool works offline without API calls and uses straight-line geographic offset, which is valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. The primary purpose is stated first, followed by use cases and an important caveat (no road-network). Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers purpose, behavior, and offline capability. It could mention that coordinates are in decimal degrees or WGS84, but the schema already specifies numeric ranges. Overall, sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description reinforces bearing direction and units but does not add new meaning beyond the schema descriptions. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates a destination point from origin, bearing, and distance using geodesic straight-line offset. It provides concrete examples like 'find a point 5km north of X' and contrasts with road-network distance, distinguishing it from sibling tools like distance_tool or directions_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases (search offsets, waypoints) and clarifies that it does not compute road-network distances. However, it does not explicitly state when to avoid this tool in favor of siblings like nearest_point_tool or map_matching_tool, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subtract one polygon from another, returning the area in polygon1 that is not covered by polygon2. Useful for computing exclusion zones, finding uncovered service areas, or "what is in zone A but not zone B?". Returns null geometry if polygon2 fully covers polygon1. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| polygon1 | Yes | The polygon to subtract from | |
| polygon2 | Yes | The polygon to subtract |
| Name | Required | Description |
|---|---|---|
| geometry | Yes | GeoJSON geometry of the remaining area (polygon1 minus polygon2), or null if polygon2 fully covers polygon1 |
| has_difference | Yes | Whether any area remains after subtracting polygon2 from polygon1 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds critical behavioral details beyond annotations: null geometry return when polygon2 fully covers polygon1, and offline operation. No contradiction with readOnlyHint=true or other annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: operation, use cases, behavior. Front-loaded with main action. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all key aspects: operation purpose, usage scenarios, edge case (null return), and offline capability. Output schema exists so return format is handled. Complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. Description reinforces which polygon is the base and which is subtracted, but does not add significant new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Subtract one polygon from another' with specific verb-resource pairing. Examples of exclusion zones and uncovered service areas distinguish it from sibling tools like intersect_tool and union_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides use cases ('computing exclusion zones, finding uncovered service areas') and behavior notes ('returns null if fully covered'). Lacks explicit contrast with siblings like intersect_tool, but context is sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches directions from Mapbox API based on provided coordinates and direction method. For route planning and distance calculations, use geometries="none" to get compact responses. Only request full geometry (geometries="geojson") when you need to visualize the route on a map or provide detailed turn-by-turn navigation instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| exclude | No | Whether to exclude certain road types and custom locations from routing. Multiple values can be specified as a comma-separated list. Available options: - All profiles: ferry, cash_only_tolls - Driving/Driving-traffic profiles only: motorway, toll, unpaved, tunnel, country_border, state_border or point(<lng> <lat>) For custom locations you can use Point exclusions (note lng and lat are space separated and at most 50 points are allowed) Note: country_border excludes all controlled country borders; borders within the Schengen Area are not excluded. | |
| arrive_by | No | The desired arrival time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mmss±hh:mm, or YYYY-MM-DDThh:mm). This parameter is only available for the driving profile and is not supported by other profiles, not even driving-traffic. The travel time will be calculated based on historical and real-time traffic data. | |
| depart_at | No | The departure time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mmss±hh:mm, or YYYY-MM-DDThh:mm). This parameter is only available for the driving and driving-traffic profiles. The travel time will be calculated based on historical and real-time traffic data. | |
| max_width | No | The max vehicle width, in meters. The Directions API will compute a route that includes only roads with a width limit greater than or equal to the max vehicle width. Must be between 0 and 10 meters. The default value is 1.9 meters. Only available for driving and driving-traffic profiles. | |
| geometries | No | The format of the returned geometry. Options: - none (default): no geometry object is returned at all, use this if you do not need all of the intermediate coordinates. - geojson: as GeoJSON LineString (might be very long as there could be a lot of points) | none |
| max_height | No | The max vehicle height, in meters. The Directions API will compute a route that includes only roads with a height limit greater than or equal to the max vehicle height. Must be between 0 and 10 meters. The default value is 1.6 meters. Only available for driving and driving-traffic profiles. | |
| max_weight | No | The max vehicle weight, in metric tons (1000 kg). The Directions API will compute a route that includes only roads with a weight limit greater than or equal to the max vehicle weight. Must be between 0 and 100 metric tons. The default value is 2.5 metric tons. Only available for driving and driving-traffic profiles. | |
| coordinates | Yes | Array of coordinate objects with longitude and latitude properties to visit in order. Must include at least 2 coordinate pairs (starting and ending points). Up to 25 coordinates total are supported. | |
| alternatives | No | Whether to try to return alternative routes (true) or not (false, default). Up to two alternatives may be returned. | |
| routing_profile | No | Routing profile for different modes of transport. Options: - mapbox/driving-traffic (default): automotive with current traffic conditions - mapbox/driving: automotive based on typical traffic - mapbox/walking: pedestrian/hiking - mapbox/cycling: bicycle | mapbox/driving-traffic |
| Name | Required | Description |
|---|---|---|
| code | No | |
| uuid | No | |
| routes | No | |
| waypoints | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by explaining performance implications of geometry options (compact vs detailed responses) and referencing the external Mapbox API, which is beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, no extraneous information, and front-loaded with the core purpose. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (10 parameters all described), annotations, and presence of output schema, the description is fairly complete. It lacks only a comparison to sibling tools, which falls under usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having detailed descriptions. The description adds minimal extra meaning, mainly reinforcing the geometries parameter's use cases. Baseline is 3, and it does not significantly exceed that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches directions based on coordinates and direction method, which distinguishes it from other tools. However, it does not explicitly differentiate from sibling tools like distance_tool or map_matching_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only provides usage guidance for the geometries parameter (when to use 'none' vs 'geojson'), but lacks any guidance on when to use this tool versus alternative tools (e.g., distance_tool, map_matching_tool). No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the distance between two geographic coordinates. Supports various units including kilometers, miles, meters, feet, and nautical miles. Uses the Haversine formula for accurate great-circle distance calculations. This tool works offline without requiring API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Ending coordinate with longitude and latitude | |
| from | Yes | Starting coordinate with longitude and latitude | |
| units | No | Unit of measurement for distance | kilometers |
| Name | Required | Description |
|---|---|---|
| to | Yes | Ending coordinate |
| from | Yes | Starting coordinate |
| units | Yes | Unit of measurement |
| distance | Yes | Calculated distance between points |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds useful context: offline operation and use of Haversine formula, which goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is three sentences with no fluff. It front-loads the main action and each sentence adds value: purpose, unit support, formula, and offline capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers purpose, behavior, and offline capability. With an output schema present, it doesn't need to describe return values. Could mention coordinate order or precision, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description mentions supported units and coordinates but does not add significant new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates distance between two geographic coordinates. It distinguishes from sibling tools like area_tool or bearing_tool implicitly through its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions it uses the Haversine formula and works offline, which implies use for great-circle distance, but no explicit guidance on when to use this tool versus alternatives like the bearing_tool or directions_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer questions about what is near a location, what neighborhood a coordinate is in, or what places are within walking/driving distance. Use this as the FIRST and ONLY tool when given coordinates and asked about nearby places, neighborhood context, local discovery, or area summaries — do NOT also call reverse_geocode_tool or search the web for places. Pass the place category (e.g. "restaurant", "coffee", "park") as the query parameter to get nearby POIs in the same call. Returns place name, nearby POIs matching the query, and travel-time reachability — all sourced from live Mapbox data with citations.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of nearby POIs to return (1-25) | |
| query | No | Optional category or type of places to search for nearby (e.g., "restaurant", "coffee", "park"). If omitted, returns general place context only. | |
| profile | No | Travel profile for isochrone calculation. Use "mapbox/driving-traffic" for traffic-aware driving. Defaults to "mapbox/walking". | mapbox/walking |
| language | No | IETF language tag for the response (e.g., "en", "es", "fr", "de", "ja") | |
| latitude | Yes | Latitude of the location to ground responses around | |
| longitude | Yes | Longitude of the location to ground responses around | |
| contours_minutes | No | Travel-time thresholds in minutes for the isochrone. Max 4 values, each between 1-60. |
| Name | Required | Description |
|---|---|---|
| place | Yes | Human-readable place name from reverse geocoding |
| latitude | Yes | |
| citations | Yes | Mapbox APIs used to produce this grounded response |
| isochrone | No | Travel-time reachability summary |
| longitude | Yes | |
| nearby_pois | No | Nearby points of interest matching the query |
| full_address | No | Full address if available |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description discloses that it returns place names, nearby POIs, travel-time reachability, and uses live Mapbox data with citations. This adds valuable context about what the tool does and its side-effect-free nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences that efficiently convey purpose, usage guidance, and output. It is front-loaded with the core functionality and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, output schema), the description covers use case, when to use, what to pass, and what to expect. The output schema exists, so return values are not needed. It is fully complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema description coverage, the description adds meaning by explaining that the query parameter is for place categories and that omitting it returns general context. It also clarifies that limit, profile, and contours_minutes are related to isochrone calculations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool answers questions about nearby places, neighborhoods, and walking/driving distance. It differentiates itself from siblings by instructing not to call reverse_geocode_tool and to use this as the first and only tool for such queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly tells when to use (given coordinates and asked about nearby places) and when not to use (do not also call reverse_geocode_tool or search the web). It also provides guidance on passing categories via the query parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the intersection geometry of two polygons — the area they share in common. Useful for coverage overlap analysis, finding shared service areas, or zone overlap. Returns null geometry if the polygons do not overlap. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| polygon1 | Yes | First polygon | |
| polygon2 | Yes | Second polygon |
| Name | Required | Description |
|---|---|---|
| geometry | Yes | GeoJSON geometry of the intersection, or null if no overlap |
| intersects | Yes | Whether the two polygons overlap |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; the description adds the null return behavior for non-overlapping polygons and offline operation, providing useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, instantly front-loading the core purpose and essential use cases without any extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the two parameters, existing output schema, and clear description covering purpose, use cases, null behavior, and offline capability, the description is complete for an AI agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are well-described in the schema. The description does not add additional parameter-level details, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds the intersection geometry of two polygons, specifies the common area, and distinguishes from siblings like union_tool and difference_tool by focusing on shared area.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases such as coverage overlap analysis and shared service areas, but does not explicitly mention when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Computes areas that are reachable within a specified amount of time from a location, and returns the reachable regions as contours of Polygons or LineStrings in GeoJSON format that you can display on a map. Common use cases: - Show a user how far they can travel in X minutes from their current location - Determine whether a destination is within a certain travel time threshold - Compare travel ranges for different modes of transportation'
| Name | Required | Description | Default |
|---|---|---|---|
| denoise | No | A floating point value that can be used to remove smaller contours. A value of 1.0 will only return the largest contour for a given value. | |
| exclude | No | Exclude certain road types and custom locations from routing. | |
| profile | No | Mode of travel. | mapbox/driving-traffic |
| polygons | No | Whether to return Polygons (true) or LineStrings (false). | |
| depart_at | No | An ISO 8601 date-time string representing the time to depart (format string: YYYY-MM-DDThh:mmss±hh:mm). | |
| generalize | Yes | Positive number in meters that is used to simplify geometries. - Walking: use 0-500. Prefer 50-200 for short contours (minutes < 10 or meters < 5000), 300-500 as they grow. - Driving: use 1000-5000. Start at 2000, use 3000 if minutes > 10 or meters > 20000. Use 4000-5000 if near 60 minutes or 100000 meters. | |
| coordinates | Yes | A coordinate object with longitude and latitude properties around which to center the isochrone lines. Longitude: -180 to 180, Latitude: -85.0511 to 85.0511 | |
| contours_colors | No | Contour colors as hex strings without starting # (for example ff0000 for red. must match contours_minutes or contours_meters length if provided). | |
| contours_meters | No | Distances in meters. Distances must be in increasing order. Must be specified either contours_minutes or contours_meters. | |
| contours_minutes | No | Contour times in minutes. Times must be in increasing order. Must be specified either contours_minutes or contours_meters. |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| features | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds that output is in GeoJSON format suitable for map display, which is useful. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear introductory sentence and bullet-pointed use cases. It is front-loaded with the core functionality. However, there is a minor typo (extra quote at the end).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers common use cases and output format, but omits that the tool also supports distance-based contours (contours_meters) in addition to time-based ones. Given high schema coverage and existence of an output schema, the description is mostly complete but has this notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema itself provides detailed parameter information. The description adds some context (e.g., return format) but does not significantly enhance understanding of individual parameters beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool computes reachable areas within a specified time and returns them as Polygons or LineStrings in GeoJSON. It provides common use cases that illustrate the tool's purpose. However, it does not explicitly differentiate this tool from siblings like buffer_tool or directions_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes common use cases that imply when to use the tool (e.g., showing travel time areas, threshold checks). However, it lacks explicit guidance on when not to use it or how it compares to alternative tools such as distance_tool or buffer_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Measure the total length of a line defined by a series of coordinates. Useful for measuring a drawn route, path, or boundary without a routing API call. Supports kilometers, miles, meters, and feet. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| units | No | Units for the length measurement | meters |
| coordinates | Yes | LineString coordinates as [longitude, latitude] pairs |
| Name | Required | Description |
|---|---|---|
| units | Yes | Units of measurement |
| length | Yes | Total length of the line |
| num_coordinates | Yes | Number of coordinate points in the line |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by mentioning offline capability and that no API call is made, providing context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear sentences with no filler. Front-loaded purpose, followed by usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given rich annotations, 100% schema coverage, and presence of output schema (not shown but indicated), description is adequate. It provides purpose, usage context, offline capability. Could mention output format (e.g., returns number in selected units) but not necessary since output schema likely covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description mentions units and coordinates but does not add meaningfully beyond schema descriptions. It lists units but schema already has enum and default. No additional detail on coordinate format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool measures total length of a line from coordinates. It distinguishes from siblings like distance_tool (point-to-point) and area_tool by specifying 'line defined by a series of coordinates' and context of measuring routes/paths.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides context: useful for drawn routes, paths, boundaries, and emphasizes no routing API call needed. This implies it's for geodesic vs road distances, but doesn't explicitly contrast with alternatives like distance_tool or directions_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Snap GPS traces to roads using Mapbox Map Matching API. Takes noisy/inaccurate coordinate sequences (2-100 points) and returns clean routes aligned with actual roads, bike paths, or walkways. Useful for analyzing recorded trips, cleaning fleet tracking data, or processing fitness activity traces. Returns confidence scores, matched geometry, and optional traffic/speed annotations.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | Routing profile for different modes of transport. Options: - driving: automotive based on road network - driving-traffic: automotive with current traffic conditions - walking: pedestrian/hiking - cycling: bicycle | driving |
| overview | No | Format of the returned geometry. Options: - full: Returns full geometry with all points - simplified: Returns simplified geometry - false: No geometry returned | full |
| radiuses | No | Array of maximum distances (in meters) each coordinate can snap to the road network. If provided, must have the same length as coordinates array. Default is unlimited. Use smaller values (5-25m) for high-quality GPS, larger values (50-100m) for noisy GPS traces. | |
| geometries | No | Format of the returned geometry. Options: - geojson: GeoJSON LineString (recommended) - polyline: Polyline with precision 5 - polyline6: Polyline with precision 6 | geojson |
| timestamps | No | Array of Unix timestamps (in seconds) corresponding to each coordinate. If provided, must have the same length as coordinates array. Used to improve matching accuracy based on speed. | |
| annotations | No | Additional data to include in the response. Options: - speed: Speed limit per segment (km/h) - distance: Distance per segment (meters) - duration: Duration per segment (seconds) - congestion: Traffic level per segment (low, moderate, heavy, severe) | |
| coordinates | Yes | Array of coordinate objects with longitude and latitude properties representing a GPS trace. Must include at least 2 and up to 100 coordinate pairs. Coordinates should be in the order they were recorded. |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| matchings | Yes | |
| tracepoints | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint, idempotentHint, and nondestructive behavior. The description adds that the tool returns confidence scores, matched geometry, and optional traffic/speed annotations, beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: first states primary function, second describes inputs/outputs, third lists use cases and return details. Each sentence earns its place with specific, valuable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and the presence of an output schema, the description covers the main return values (confidence, geometry, optional annotations). It does not mention error handling or performance, but is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. The description adds practical guidance for the radiuses parameter (recommended values for GPS quality), enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool snaps GPS traces to roads using a specific API, listing realistic use cases (recorded trips, fleet tracking, fitness traces). This differentiates it from sibling tools like directions_tool or area_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context ('useful for analyzing recorded trips...') and implies when to use it (noisy GPS data), but does not explicitly list when not to use it or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculates travel times and distances between multiple points using Mapbox Matrix API.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | Yes | Routing profile for different modes of transport. Options: - mapbox/driving-traffic (default): automotive with current traffic conditions (limited to 10 coordinates) - mapbox/driving: automotive based on typical traffic - mapbox/walking: pedestrian/hiking - mapbox/cycling: bicycle | |
| sources | No | Use the coordinates at given indices as sources. Possible values are: a semicolon-separated list of 0-based indices, or "all" (default). The option "all" allows using all coordinates as sources. | |
| bearings | No | A semicolon-separated list of headings and allowed deviation indicating the direction of movement. Input as two comma-separated values per location: a heading course measured clockwise from true north between 0 and 360, and the range of degrees by which the angle can deviate (recommended value is 45° or 90°), formatted as {angle,degrees}. If provided, the number of bearings must equal the number of coordinates. You can skip a coordinate and show its position in the list with the ; separator. | |
| approaches | No | A semicolon-separated list indicating the side of the road from which to approach waypoints. Accepts "unrestricted" (default, route can arrive at the waypoint from either side of the road) or "curb" (route will arrive at the waypoint on the driving_side of the region). If provided, the number of approaches must be the same as the number of waypoints. You can skip a coordinate and show its position with the ; separator. | |
| annotations | No | Specifies the resulting matrices. Possible values are: duration (default), distance, or both values separated by a comma. | |
| coordinates | Yes | Array of coordinate objects with longitude and latitude properties. Must include at least 2 coordinate pairs. Up to 25 coordinates total are supported for most profiles (10 for driving-traffic). | |
| destinations | No | Use the coordinates at given indices as destinations. Possible values are: a semicolon-separated list of 0-based indices, or "all" (default). The option "all" allows using all coordinates as destinations. |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| message | No | |
| sources | Yes | |
| distances | No | |
| durations | No | |
| destinations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds only the API source (Mapbox Matrix) but no additional behavioral context (e.g., API limits, pricing, or error handling). It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it could be slightly more structured with additional context, but it is appropriately brief for a straightforward tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, output schema exists, many siblings) the description is minimal. It does not explain return values but output schema covers that. Still, it misses nuances like coordinate limits or profile constraints already in schema, so overall adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific details beyond what the schema already provides, so it meets the baseline without improvement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Calculates' and the resource 'travel times and distances between multiple points using Mapbox Matrix API'. It distinguishes from siblings like directions_tool (point-to-point) by emphasizing 'multiple points' (matrix computation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as directions_tool or distance_tool. It lacks explicit when-not-to-use or alternative suggestions, which is a significant gap given the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the geographic midpoint between two coordinates. Returns the point that is halfway between the two input points along the great circle path. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Ending coordinate | |
| from | Yes | Starting coordinate |
| Name | Required | Description |
|---|---|---|
| to | Yes | |
| from | Yes | |
| midpoint | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description adds behavioral context: the calculation follows the great circle path and the tool works offline without API calls. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. Front-loaded with purpose, then provides return detail and offline capability. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required parameters) and the presence of an output schema, the description is complete. It explains what the tool does, what it returns, and an additional capability (offline).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters fully described). The description only mentions 'between two coordinates' which maps to the parameters but adds no additional detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Calculate the geographic midpoint between two coordinates', using a specific verb and resource. It distinguishes from sibling tools like centroid_tool (polygon center) and distance_tool by focusing on midpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a midpoint between two coordinates is needed, but it does not explicitly state when to use this tool over alternatives or mention any exclusions. No comparison with sibling tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Snap a point to the nearest position on a line or route. Returns the closest point on the line and the distance to it. Useful for "which point on this route is closest to my location?" or map-matching without the API. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| line | Yes | LineString coordinates as [longitude, latitude] pairs | |
| point | Yes | The point to snap to the line | |
| units | No | Units for the distance result | kilometers |
| Name | Required | Description |
|---|---|---|
| units | Yes | Distance units |
| nearest | Yes | The nearest point on the line |
| distance | Yes | Distance from the input point to the nearest point on the line |
| location | Yes | Distance along the line to the nearest point |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it is safe and idempotent. The description adds that it works offline without API calls, which is helpful but not critical. No contradictions between description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no unnecessary words. The first sentence states the purpose, the second describes the return value, and the third gives use cases. Information is front-loaded and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (3 parameters with full schema coverage, existing output schema, and informative annotations), the description covers all necessary context: purpose, return value, offline capability, and use cases. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters. The description adds high-level context (snapping to a line) but does not provide additional detail or examples beyond the schema. A baseline score of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Snap a point to the nearest position on a line or route.' The verb is specific (snap) and the resource is well-defined (line or route), making the purpose immediately understandable. It also distinguishes itself from sibling tools like 'nearest_point_tool' by focusing on lines and routes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful use cases: 'which point on this route is closest to my location?' and map-matching without the API. However, it does not specify when not to use this tool or explicitly mention alternative tools (e.g., map_matching_tool for full matching), leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the nearest point in a collection to a given target point. More efficient than calling distance_tool for each candidate and sorting. Useful for finding the closest store, stop, or landmark to a location. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| units | No | Distance units for the result | meters |
| points | Yes | Candidate points to search | |
| target | Yes | The reference point to measure from |
| Name | Required | Description |
|---|---|---|
| index | Yes | Index of the nearest point in the input array |
| units | Yes | Distance units |
| nearest | Yes | The nearest point |
| distance | Yes | Distance from target to nearest point |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds 'Works offline without API calls' which is a useful behavioral trait. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise at 4 sentences with no redundant information. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, presence of annotations, and existence of output schema, the description covers purpose, efficiency, use cases, and offline capability comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Find' and the resource 'nearest point in a collection'. It distinguishes itself from the sibling tool 'distance_tool' by noting efficiency gains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear use cases (closest store, stop, landmark) and explicitly compares to distance_tool. Does not mention when to use alternative like nearest_point_on_line_tool, but still gives solid guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the optimal (shortest by travel time) route through a set of 2-12 coordinates. Solves the Traveling Salesman Problem to determine the best visiting order. Supports options for starting point, ending point, and whether to return to start.
| Name | Required | Description | Default |
|---|---|---|---|
| steps | No | Whether to include turn-by-turn instructions | |
| source | No | Location to start the trip. "any" allows any coordinate, "first" forces the first coordinate as start. | any |
| profile | No | Routing profile to use for optimization | mapbox/driving |
| language | No | Language for instructions (if steps=true). ISO 639-1 code (e.g., "en", "es"). | |
| overview | No | Detail level of route geometry | simplified |
| roundtrip | No | Whether to return to the starting point. Set to false for one-way trips. | |
| geometries | No | Format for route geometry | geojson |
| annotations | No | Additional metadata to include for each route segment | |
| coordinates | Yes | Array of {longitude, latitude} coordinate pairs to optimize a route through. The V1 API supports 2-12 coordinates and returns the optimal visiting order. | |
| destination | No | Location to end the trip. "any" allows any coordinate, "last" forces the last coordinate as end. | any |
| Name | Required | Description |
|---|---|---|
| code | Yes | Status code (e.g., "Ok" for success, error code otherwise) |
| trips | Yes | Array containing the optimized trip (typically 1 trip for all waypoints) |
| message | No | Error message if code is not "Ok" |
| waypoints | Yes | Input coordinates snapped to the road network in optimized order |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare safe read-only behavior (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds the TSP solving and coordinate constraints but does not go beyond what annotations provide, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-loaded with core purpose, TSP explanation, and options list. No wasted words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and high schema coverage, the description is nearly complete. It lacks some behavioral edge cases but is sufficient for an agent to understand usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description adds little beyond schema. It notes support for starting/ending points and roundtrip, which maps to parameters, but does not compensate significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool solves TSP to find the shortest route through coordinates, with explicit mention of 'shortest by travel time' and 'best visiting order.' It distinguishes itself from siblings like directions_tool by focusing on optimization rather than sequential directions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for optimizing multi-stop routes but does not explicitly state when to use this tool vs alternatives like directions_tool or matrix_tool. It mentions supported options but lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve detailed information about a specific place using its Mapbox ID. Use after search_and_geocode_tool, category_search_tool, or reverse_geocode_tool to get additional details such as photos, opening hours, ratings, phone numbers, and website URLs. Requires the mapbox_id field from a previous search result.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | BCP 47 language tag for localized results (e.g. "en", "fr", "de", "ja"). Affects place names and address formatting. | |
| mapbox_id | Yes | The Mapbox ID of the place to retrieve details for. Obtained from search results returned by search_and_geocode_tool, category_search_tool, or reverse_geocode_tool (the mapbox_id field in properties). | |
| worldview | No | Worldview for geopolitically sensitive content such as disputed borders. Options: "ar" (Argentina), "cn" (China), "in" (India), "jp" (Japan), "ma" (Morocco), "ru" (Russia), "tr" (Turkey), "us" (United States, default). | |
| attribute_sets | No | Which attribute sets to include in the response. Options: "basic" (address/coordinates, always included), "photos" (place photo URLs), "visit" (opening hours, rating, price level, popularity), "venue" (phone number, website URL, social media links). When not specified, only basic attributes are returned. |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| geometry | Yes | |
| properties | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by listing specific details returned (photos, opening hours, ratings, phone numbers, website URLs) and mentioning attribute sets, providing behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences: first states purpose, second provides usage guidelines. Every sentence earns its place, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description need not detail return values. It covers prerequisites, usage flow, and available attribute sets, making it complete for a retrieval tool with multiple optional features.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds contextual meaning: mapbox_id 'obtained from search results', language affects place names/addresses, worldview for geopolitical sensitivity, and attribute_sets lists what each set includes. Enhances understanding beyond schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve detailed information about a specific place using its Mapbox ID,' specifying the verb (retrieve) and resource (place details). It distinguishes from sibling search tools by indicating it is used after them to get additional details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to use after search_and_geocode_tool, category_search_tool, or reverse_geocode_tool, and requires the mapbox_id field. Provides clear context for when to use this tool. No explicit when-not-to-use or alternatives, but sufficient given sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test one or more geographic points against a polygon, returning only those inside. Handles a single point or a batch of points in one call. Useful for delivery zone validation, fleet geofencing, and customer segmentation. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| points | Yes | Array of points to test against the polygon | |
| polygon | Yes | Polygon coordinates as array of rings (first is outer, rest are holes). Each ring is [longitude, latitude] pairs. |
| Name | Required | Description |
|---|---|---|
| count | Yes | Number of points inside the polygon |
| total | Yes | Total number of input points tested |
| points_within | Yes | Points that are inside the polygon |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it 'handles a single point or a batch of points in one call' and 'works offline without API calls,' which provides useful behavioral context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding distinct value: purpose, batch capability, and use cases/offline nature. It is front-loaded with the core function and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and the presence of an output schema, the description covers essential aspects: purpose, batch handling, use cases, and offline operation. It could explicitly mention coordinate system (assumed WGS84), but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('points' and 'polygon'). The description adds minimal extra meaning beyond echoing the schema (e.g., 'batch of points'). With full schema coverage, a baseline of 3 is appropriate as the description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Test one or more geographic points against a polygon, returning only those inside.' The title 'Points Within Polygon' is also descriptive. It distinguishes itself from sibling tools like area_tool or distance_tool by focusing on point-in-polygon testing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'delivery zone validation, fleet geofencing, and customer segmentation' and notes that it 'works offline without API calls.' While it doesn't explicitly state when not to use it or give alternatives, the context is clear and sufficient for most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert geographic coordinates (longitude, latitude) into a human-readable address or place name. Use only when you need an address/place name alone. If you also need nearby places, neighborhood context, or travel-time reachability, use ground_location_tool instead — it already includes reverse geocoding plus POI search and isochrone in one call. This tool cannot reverse geocode businesses, landmarks, or POIs. Supports JSON and text output formats.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (1-5). Use 1 for best results. If you need more than 1 result, you must specify exactly one type in the types parameter. | |
| types | No | Array of feature types to filter results | |
| format | No | Output format: "json_string" returns raw GeoJSON data as a JSON string that can be parsed; "formatted_text" returns human-readable text with place names, addresses, and coordinates. Both return as text content but json_string contains parseable JSON data while formatted_text is for display. | formatted_text |
| country | No | Array of ISO 3166 alpha 2 country codes to limit results | |
| language | No | IETF language tag for the response (e.g., "en", "es", "fr", "de", "ja") | |
| latitude | Yes | Latitude coordinate to reverse geocode | |
| longitude | Yes | Longitude coordinate to reverse geocode | |
| permanent | No | Whether results can be stored permanently | |
| worldview | No | Returns features from a specific regional perspective | us |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| features | Yes | |
| attribution | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, etc. Description adds that it supports JSON and text output formats, clarifies it cannot reverse geocode businesses/landmarks, and does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences plus a hint. Front-loaded with purpose and usage guidance. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, full schema coverage, and an output schema, the description is complete. It covers purpose, usage guidelines, limitations, and output formats. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what is already in the schema parameter descriptions; it only mentions output formats briefly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool converts geographic coordinates into a human-readable address or place name. Distinguishes from ground_location_tool by specifying that this tool is only for address/place name, not for nearby places or travel-time reachability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use only when you need an address/place name alone' and contrasts with ground_location_tool which includes reverse geocoding plus POI search and isochrone. Also states limitation: cannot reverse geocode businesses, landmarks, or POIs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for POIs, brands, chains, geocode cities, towns, addresses. Do not use for generic place types such as 'museums', 'coffee shops', 'tacos', etc, because category_search_tool is better for that. Setting a proximity point is strongly encouraged for more local results.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query text. Limited to 256 characters. | |
| bbox | No | Bounding box to limit results within [minLon, minLat, maxLon, maxLat] | |
| types | No | Array of feature types to filter results (e.g., ["poi", "address", "place"]) | |
| origin | No | ||
| country | No | Array of ISO 3166 alpha 2 country codes to limit results | |
| eta_type | No | Request estimated time of arrival (ETA) to results | |
| language | No | ISO language code for the response (e.g., "en", "es", "fr", "de", "ja") | |
| proximity | No | Location to bias results towards as {longitude, latitude}. If not provided, defaults to IP-based location. STRONGLY ENCOURAGED for relevant results. | |
| poi_category | No | Array of POI categories to include (e.g., ["restaurant", "cafe"]) | |
| auto_complete | No | Enable partial and fuzzy matching | |
| navigation_profile | No | Routing profile for ETA calculations |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| features | Yes | |
| attribution | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond annotations: it encourages proximity for local results and implies search results are limited to specific entities. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no unnecessary words. First sentence states purpose, second sentence gives usage guidelines. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 11 parameters, high schema coverage, and existence of output schema, the description provides sufficient context for tool selection and basic usage. It does not elaborate on all parameters or return format, but the schema and annotations fill gaps. Could be slightly more comprehensive but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 91%, so the input schema already provides detailed descriptions for most parameters. The description reinforces the proximity parameter by stating it is 'strongly encouraged' but does not add new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for POIs, brands, chains, and geocodes cities, towns, addresses. It distinguishes from the sibling category_search_tool by explicitly listing what not to use it for (generic place types), providing a specific verb ('Search for', 'geocode') and resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly advises against using for generic place types and directs to category_search_tool as a better alternative. It encourages setting a proximity point for local results, giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simplify a LineString or Polygon by reducing the number of vertices while preserving the general shape. Uses the Douglas-Peucker algorithm. Useful for reducing file sizes and improving rendering performance. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| geometry | Yes | LineString or Polygon coordinates | |
| tolerance | No | Simplification tolerance (higher values = more simplification). Default: 0.01 | |
| highQuality | No | Use high quality simplification (slower but more accurate). Default: false |
| Name | Required | Description |
|---|---|---|
| simplified | Yes | Simplified geometry coordinates |
| originalVertexCount | Yes | |
| reductionPercentage | Yes | |
| simplifiedVertexCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by naming the Douglas-Peucker algorithm and stating offline capability, which are not in annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is four concise sentences with no redundancies. Each sentence adds information: operation, algorithm, use case, and offline capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, description does not need to explain return values. It covers algorithm, use cases, and offline behavior. Minor gap: no mention of coordinate system, but this is standard for such tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description does not add parameter-specific details beyond the schema, but it contextualizes the tolerance parameter by mentioning the algorithm.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it simplifies LineString or Polygon by reducing vertices while preserving shape, using the Douglas-Peucker algorithm. It distinguishes from siblings like area, centroid, and buffer tools, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions usefulness for reducing file sizes and improving rendering performance, and that it works offline. While it does not explicitly exclude cases, the context is clear and implies appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generates a static map image from Mapbox Static Images API. Supports center coordinates, zoom level (0-22), image size (up to 1280x1280), various Mapbox styles, and overlays (markers, paths, GeoJSON). Returns PNG for vector styles, JPEG for raster-only styles.
| Name | Required | Description | Default |
|---|---|---|---|
| size | Yes | Image size as object with width and height properties in pixels. Each dimension must be between 1 and 1280 pixels | |
| zoom | Yes | Zoom level (0-22). Fractional zoom levels are rounded to two decimal places | |
| style | No | Mapbox style ID in the format username/style-id (e.g., mapbox/streets-v12, mapbox/satellite-v9, mapbox/dark-v11) | mapbox/streets-v12 |
| center | Yes | Center point of the map as coordinate object with longitude and latitude properties. Longitude: -180 to 180, Latitude: -85.0511 to 85.0511 | |
| overlays | No | Array of overlays to add to the map. Overlays are rendered in order (last item appears on top) | |
| highDensity | No | Whether to return a high-density (2x) image |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying return image formats (PNG for vector styles, JPEG for raster-only styles) and overlay rendering order. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the main purpose and capabilities. It front-loads the core function. Could be slightly improved with bullet points for readability but is still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and no output schema, the description covers the return format (PNG/JPEG) and mentions overlays. It is adequate for an agent to understand what the tool produces, though it does not specify the exact binary or encoding format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description lists features but does not add significant meaning beyond what is in the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool generates a static map image from Mapbox Static Images API, specifying key features like center, zoom, size, styles, and overlays. It is specific with a verb and resource, and is easily distinguished from sibling tools which are spatial analysis and geocoding tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (generating static map images). However, it does not explicitly state when not to use it or provide alternatives, though sibling tools are so different that confusion is unlikely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge two or more polygons into a single unified geometry. Useful for combining service areas, delivery zones, isochrones, or coverage regions. Returns a Polygon or MultiPolygon if the inputs do not overlap. Works offline without API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| polygons | Yes | Array of polygons to merge into a single union geometry |
| Name | Required | Description |
|---|---|---|
| type | Yes | Geometry type: Polygon or MultiPolygon |
| geometry | Yes | GeoJSON geometry of the merged polygon (Polygon or MultiPolygon) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior beyond annotations: returns Polygon or MultiPolygon if inputs do not overlap, works offline without API calls. Annotations already mark readOnlyHint, idempotentHint, destructiveHint, so description adds useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a purpose: purpose, use cases, behavioral note. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations and full schema coverage, the description provides complete context: purpose, usage, behavioral trait, and offline capability. Output schema exists, so return value details are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the description repeats that polygons are merged but adds no new details about the parameter itself. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Merge') and resource ('polygons'). Mentions specific use cases like combining service areas, delivery zones, isochrones, coverage regions. Distinguishes from sibling tools like difference_tool and intersect_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use (e.g., combining coverage regions) and notes offline capability. Does not explicitly say when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.12.6area_toolbbox_toolbearing_toolbuffer_toolcategory_search_toolcentroid_toolconvex_tooldestination_tooldifference_tooldirections_tooldistance_toolground_location_toolintersect_toolisochrone_toollength_toolmap_matching_toolmatrix_toolmidpoint_toolnearest_point_on_line_toolnearest_point_tooloptimization_toolplace_details_toolpoints_within_polygon_toolreverse_geocode_toolsearch_and_geocode_toolsimplify_toolstatic_map_image_toolunion_toolMost tools have distinct purposes, but there is potential confusion among search/geocode tools (category_search, search_and_geocode, reverse_geocode, ground_location). Detailed descriptions help, but an agent might still mismatch, e.g., using reverse_geocode when ground_location is more appropriate.
All tool names follow a consistent snake_case verb_noun_tool pattern. Examples include area_tool, directions_tool, and nearest_point_tool. No deviations or mixed conventions.
With 28 tools, the set is on the higher end of reasonable. While each tool serves a clear purpose, the count feels slightly heavy for an MCP server, potentially overwhelming an agent. The number is justified by the breadth of Mapbox capabilities but exceeds the typical 3-15 tool sweet spot.
The tool set covers major Mapbox functionalities: geocoding, directions, geometry operations, static maps, and spatial analysis. Minor gaps exist (e.g., no tile or style management), but for a conversational agent, the surface is comprehensive and leaves few dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Provides AI assistants with direct access to Mapbox developer APIs and documentation.
AI access to Mapbox docs, API references, style specs, and guides. No token required.
Mapbox geocode, directions, matrix, isochrones, map-matching, tilequery, static URL.
Real-world data for agents: air quality, geocoding, quakes, holidays, web search
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mapbox/mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server