Provides AI assistants with direct access to Mapbox developer APIs, enabling management of Mapbox styles, tokens, and other services for building Mapbox applications.
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 Developer MCP Server List my Mapbox styles"
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.
A Model Context Protocol (MCP) server that provides AI assistants with direct access to Mapbox developer APIs. This server enables AI models to interact with Mapbox services, helping developers build Mapbox applications more efficiently.
Looking for Mapbox documentation access? Use mcp-docs-server alongside this server — it provides AI assistants with access to Mapbox documentation, guides, and API references from docs.mapbox.com.
https://github.com/user-attachments/assets/8b1b8ef2-9fba-4951-bc9a-beaed4f6aff6
Related MCP server: Mapbox MCP Server
Get started by integrating with your preferred AI development environment:
Claude Code Integration - Command-line development with Claude
Claude Desktop Integration - Desktop application integration
Cursor Integration - Cursor IDE integration
VS Code Integration - Visual Studio Code with GitHub Copilot
This MCP server can be packaged as a DXT (Desktop Extension) file for easy distribution and installation. DXT is a standardized format for distributing local MCP servers, similar to browser extensions.
To create a DXT package:
# Install the DXT CLI tool
npm install -g @anthropic-ai/dxt
# Build the server first
npm run build
# Create the DXT package
npx @anthropic-ai/dxt packThis will generate mcp-devkit-server.dxt using the configuration in manifest.json.
The DXT package includes:
Pre-built server code (dist/esm/index.js)
Server metadata and configuration
User configuration schema for the Mapbox access token
Automatic environment variable setup
For quick access, you can use our hosted MCP endpoint:
Endpoint: https://mcp-devkit.mapbox.com/mcp
For detailed setup instructions for different clients and API usage, see the Hosted MCP Server Guide. Note: This guide references the standard MCP endpoint - you'll need to update the endpoint URL to use the devkit endpoint above.
A Mapbox access token is required to use this MCP server.
Sign up for a free Mapbox account at mapbox.com/signup
Navigate to your Account page
Create a new token with the required scopes for your use case
For more information about Mapbox access tokens, see the Mapbox documentation on access tokens.
⚠️ IMPORTANT: Token Privileges Required
The MAPBOX_ACCESS_TOKEN environment variable is required. Each tool requires specific token scopes/privileges to function properly. For example:
Reading styles requires styles:read scope
Creating styles requires styles:write scope
Managing tokens requires tokens:read and tokens:write scopes
Accessing feedback requires user-feedback:read scope
Reference data is exposed as MCP Resources (see Resources section). MCP clients that support the resources protocol can access them directly.
Available References:
resource://mapbox-style-layers - Mapbox GL JS style specification reference guide covering all layer types (fill, line, symbol, circle, fill-extrusion) and their properties
resource://mapbox-streets-v8-fields - Complete field definitions for all Mapbox Streets v8 source layers, including enumerated values for each field (useful for building filters)
resource://mapbox-token-scopes - Comprehensive token scope reference explaining what each scope allows and which scopes are needed for different operations
resource://mapbox-layer-type-mapping - Mapping of Mapbox Streets v8 source layers to compatible GL JS layer types, with common usage patterns
Example prompts:
"What fields are available for the landuse layer?"
"Show me the token scopes reference"
"What layer type should I use for roads?"
"Get the Streets v8 fields reference"
"What scopes do I need to display a map?"
Complete set of tools for managing Mapbox styles via the Styles API:
Style Builder Tool - Create and modify Mapbox styles programmatically through conversational prompts
📖 See the Style Builder documentation for detailed usage and examples →
ListStylesTool - List all styles for a Mapbox account
Input: limit (optional - max number of styles), start (optional - pagination token)
Returns: Array of style metadata with optional pagination info
CreateStyleTool - Create a new Mapbox style
Input: name, style (Mapbox style specification)
Returns: Created style details with ID
RetrieveStyleTool - Retrieve a specific style by ID
Input: styleId
Returns: Complete style specification
UpdateStyleTool - Update an existing style
Input: styleId, name (optional), style (optional)
Returns: Updated style details
DeleteStyleTool - Delete a style by ID
Input: styleId
Returns: Success confirmation
PreviewStyleTool - Generate preview URL for a Mapbox style using an existing public token
Input: styleId, title (optional), zoomwheel (optional), zoom (optional), center (optional), bearing (optional), pitch (optional)
Returns: URL to open the style preview in browser
Note: This tool automatically fetches the first available public token from your account for the preview URL. Requires at least one public token with styles:read scope.
ValidateStyleTool - Validate Mapbox style JSON against the Mapbox Style Specification
Input: style (Mapbox style JSON object or JSON string)
Returns: Validation results including errors, warnings, info messages, and style summary
Performs comprehensive offline validation checking:
Required fields (version, sources, layers)
Valid layer and source types
Source references and layer IDs
Common configuration issues
Note: This is an offline validation tool that doesn't require API access or token scopes
⚠️ Required Token Scopes:
All style tools require a valid Mapbox access token with specific scopes. Using a token without the correct scope will result in authentication errors.
ListStylesTool: Requires styles:list scope
CreateStyleTool: Requires styles:write scope
RetrieveStyleTool: Requires styles:download scope
UpdateStyleTool: Requires styles:write scope
DeleteStyleTool: Requires styles:write scope
PreviewStyleTool: Requires tokens:read scope (to list tokens) and at least one public token with styles:read scope
Note: The username is automatically extracted from the JWT token payload.
Example prompts:
"Can you create a Christmas themed Style for me?"
"Please generate a preview link for this style"
"Can you change the background to snow style?"
Create a new Mapbox access token with specified scopes and optional URL restrictions.
Parameters:
note (string, required): Description of the token
scopes (array of strings, required): Array of scopes/permissions for the token. Must be valid Mapbox scopes (see below)
allowedUrls (array of strings, optional): URLs where the token can be used (max 100)
expires (string, optional): Expiration time in ISO 8601 format (maximum 1 hour in the future)
Available Scopes:
Available scopes for public tokens:
styles:tiles - Read styles as raster tiles
styles:read - Read styles
fonts:read - Read fonts
datasets:read - Read datasets
vision:read - Read Vision API
Example:
{
"note": "Development token for my app",
"scopes": ["styles:read", "fonts:read"],
"allowedUrls": ["https://myapp.com"]
}Example prompts:
"Create a new Mapbox token for my web app with styles:read and fonts:read permissions"
"Generate a token that expires in 30 minutes with styles:tiles and vision:read scopes"
"Create a restricted token that only works on https://myapp.com with styles:read, fonts:read, and datasets:read"
List Mapbox access tokens for the authenticated user with optional filtering and pagination.
Parameters:
default (boolean, optional): Filter to show only the default public token
limit (number, optional): Maximum number of tokens to return per page (1-100)
sortby (string, optional): Sort tokens by "created" or "modified" timestamp
start (string, optional): The token ID after which to start the listing (when provided, auto-pagination is disabled)
usage (string, optional): Filter by token type: "pk" (public)
Pagination behavior:
When no start parameter is provided, the tool automatically fetches all pages of results
When a start parameter is provided, only the requested page is returned (for manual pagination control)
Example:
{
"limit": 10,
"sortby": "created",
"usage": "pk"
}Example prompts:
"List all my Mapbox tokens"
"Show me my public tokens sorted by creation date"
"Find my default public token"
"List the 5 most recently modified tokens"
"Show all public tokens in my account"
Access user feedback items from the Mapbox Feedback API. These tools allow you to retrieve and view user-reported issues, suggestions, and feedback about map data, routing, and POI details.
list_feedback_tool - List user feedback items with comprehensive filtering, sorting, and pagination options.
Parameters:
feedback_ids (array of UUIDs, optional): Filter by one or more feedback item IDs
after (string, optional): Cursor from a previous response for pagination
limit (number, optional): Maximum number of items to return (1-1000, default varies)
sort_by (string, optional): Sort field - received_at (default), created_at, or updated_at
order (string, optional): Sort direction - asc (default) or desc
status (array, optional): Filter by status - received, fixed, reviewed, out_of_scope
category (array, optional): Filter by feedback categories
search (string, optional): Search phrase to match against feedback text
trace_id (array, optional): Filter by trace IDs
created_before, created_after (ISO 8601 string, optional): Filter by creation date range
received_before, received_after (ISO 8601 string, optional): Filter by received date range
updated_before, updated_after (ISO 8601 string, optional): Filter by update date range
format (string, optional): Output format - formatted_text (default) or json_string
Returns: Paginated list of feedback items with pagination cursors.
get_feedback_tool - Get a single user feedback item by its unique ID.
Parameters:
feedback_id (UUID, required): The unique identifier of the feedback item
format (string, optional): Output format - formatted_text (default) or json_string
Returns: Single feedback item with details including status, category, feedback text, location, and timestamps.
⚠️ Required Token Scope:
Both feedback tools: Require user-feedback:read scope on the access token
Example prompts:
"List all feedback items with status 'fixed'"
"Show me feedback items in the 'poi_details' category created after July 1st"
"Get feedback item with ID 40eae4c7-b157-4b49-a091-7e1099bba77e"
"Find feedback items containing 'apartment building' in the feedback text"
"List all routing issue feedback from the last month"
Generate a geojson.io URL to visualize GeoJSON data. This tool:
Validates GeoJSON format (Point, LineString, Polygon, Feature, FeatureCollection, etc.)
Returns a direct URL to geojson.io for instant visualization
Supports both GeoJSON objects and JSON strings as input
Example usage:
{
"geojson": {
"type": "Point",
"coordinates": [-122.4194, 37.7749]
}
}Returns: A single URL string that can be opened in a browser to view the GeoJSON data.
Note: This is a beta feature currently optimized for small to medium-sized GeoJSON files. Large GeoJSON files may result in very long URLs and slower performance. We plan to optimize this in future versions by implementing alternative approaches for handling large datasets.
Example prompts:
"Generate a preview URL for this GeoJSON data"
"Create a geojson.io link for my uploaded route.geojson file"
Validates GeoJSON objects for correctness, checking structure, coordinates, and geometry types. This offline validation tool performs comprehensive checks on GeoJSON data without requiring API access.
Parameters:
geojson (string or object, required): GeoJSON object or JSON string to validate
What it validates:
GeoJSON type validity (Feature, FeatureCollection, Point, LineString, Polygon, etc.)
Required properties (type, coordinates, geometry, features)
Coordinate array structure and position validity
Longitude ranges [-180, 180] and latitude ranges [-90, 90]
Polygon ring closure (first and last coordinates should match)
Minimum position requirements (LineString needs 2+, Polygon rings need 4+ positions)
Returns:
Validation results including:
valid (boolean): Overall validity
errors (array): Critical errors that make the GeoJSON invalid
warnings (array): Non-critical issues (e.g., unclosed polygon rings, out-of-range coordinates)
info (array): Informational messages
statistics: Object with type, feature count, geometry types, and bounding box
Each issue includes:
severity: "error", "warning", or "info"
message: Description of the issue
path: JSON path to the problem (optional)
suggestion: How to fix the issue (optional)
Example:
{
"geojson": {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [102.0, 0.5]
},
"properties": {
"name": "Test Point"
}
}
}Returns:
{
"valid": true,
"errors": [],
"warnings": [],
"info": [],
"statistics": {
"type": "Feature",
"featureCount": 1,
"geometryTypes": ["Point"],
"bbox": [102.0, 0.5, 102.0, 0.5]
}
}Example prompts:
"Validate this GeoJSON file and tell me if there are any errors"
"Check if my GeoJSON coordinates are valid"
"Is this Feature Collection properly formatted?"
Note: This is an offline validation tool that doesn't require API access or token scopes.
Validates Mapbox style expressions for syntax, operators, and argument correctness. This offline validation tool performs comprehensive checks on Mapbox expressions without requiring API access.
Parameters:
expression (array or string, required): Mapbox expression to validate (array format or JSON string)
What it validates:
Expression syntax and structure
Valid operator names
Correct argument counts for each operator
Nested expression validation
Expression depth (warns about deeply nested expressions)
Returns:
Validation results including:
valid (boolean): Overall validity
errors (array): Critical errors that make the expression invalid
warnings (array): Non-critical issues (e.g., deeply nested expressions)
info (array): Informational messages
metadata: Object with expressionType, returnType, and depth
Each issue includes:
severity: "error", "warning", or "info"
message: Description of the issue
path: Path to the problem in the expression (optional)
suggestion: How to fix the issue (optional)
Supported expression types:
Data: get, has, id, geometry-type, feature-state, properties
Lookup: at, in, index-of, slice, length
Decision: case, match, coalesce
Ramps & interpolation: interpolate, step
Math: +, -, *, /, %, ^, sqrt, log10, log2, ln, abs, etc.
String: concat, downcase, upcase, is-supported-script
Color: rgb, rgba, to-rgba, hsl, hsla
Type: array, boolean, collator, format, image, literal, number, number-format, object, string, to-boolean, to-color, to-number, to-string, typeof
Camera: zoom, pitch, distance-from-center
Variable binding: let, var
Example:
{
"expression": ["get", "population"]
}Returns:
{
"valid": true,
"errors": [],
"warnings": [],
"info": [
{
"severity": "info",
"message": "Expression validated successfully"
}
],
"metadata": {
"expressionType": "data",
"returnType": "any",
"depth": 1
}
}Example prompts:
"Validate this Mapbox expression: ["get", "population"]"
"Check if this interpolation expression is correct"
"Is this expression syntax valid for Mapbox styles?"
Note: This is an offline validation tool that doesn't require API access or token scopes.
Convert coordinates between different coordinate reference systems (CRS), specifically between WGS84 (EPSG:4326) and Web Mercator (EPSG:3857).
Parameters:
coordinates (array, required): Array of coordinate pairs to convert. Each coordinate pair should be [longitude, latitude] for WGS84 or [x, y] for Web Mercator
fromCRS (string, required): Source coordinate reference system. Supported values: "EPSG:4326" (WGS84), "EPSG:3857" (Web Mercator)
toCRS (string, required): Target coordinate reference system. Supported values: "EPSG:4326" (WGS84), "EPSG:3857" (Web Mercator)
Returns:
An array of converted coordinate pairs in the target CRS format.
Example:
{
"coordinates": [
[-122.4194, 37.7749],
[-74.006, 40.7128]
],
"fromCRS": "EPSG:4326",
"toCRS": "EPSG:3857"
}Example prompts:
"Convert these coordinates from WGS84 to Web Mercator: [-122.4194, 37.7749] and [-74.006, 40.7128]"
"Convert the coordinates [-13627361.0, 4544761.0] from Web Mercator to WGS84"
Calculates the bounding box of given GeoJSON content, returning coordinates as [minX, minY, maxX, maxY].
Parameters:
geojson (string or object, required): GeoJSON content to calculate bounding box for. Can be provided as:
A JSON string that will be parsed
A GeoJSON object
Supported GeoJSON types:
Point
LineString
Polygon
MultiPoint
MultiLineString
MultiPolygon
GeometryCollection
Feature
FeatureCollection
Returns:
An array of four numbers representing the bounding box: [minX, minY, maxX, maxY]
minX: Western-most longitude
minY: Southern-most latitude
maxX: Eastern-most longitude
maxY: Northern-most latitude
Example:
{
"geojson": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-73.9857, 40.7484]
},
"properties": {}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-74.006, 40.7128]
},
"properties": {}
}
]
}
}Example prompts:
"Calculate the bounding box of this GeoJSON file" (then upload a .geojson file)
"What's the bounding box for the coordinates in the uploaded parks.geojson file?"
Checks color contrast ratios between foreground and background colors for WCAG 2.1 accessibility compliance.
Parameters:
foregroundColor (string, required): Foreground color (text color) in any CSS format (hex, rgb, rgba, named colors)
backgroundColor (string, required): Background color in any CSS format (hex, rgb, rgba, named colors)
level (string, optional): WCAG conformance level to check against ("AA" or "AAA", default: "AA")
fontSize (string, optional): Font size category ("normal" or "large", default: "normal")
Normal: < 18pt or < 14pt bold
Large: ≥ 18pt or ≥ 14pt bold
Color format support:
Hex colors: #RGB, #RRGGBB, #RRGGBBAA
RGB/RGBA: rgb(r, g, b), rgba(r, g, b, a)
Named colors: black, white, red, blue, gray, etc.
WCAG 2.1 requirements:
WCAG AA: 4.5:1 for normal text, 3:1 for large text
WCAG AAA: 7:1 for normal text, 4.5:1 for large text
Returns:
A JSON object with:
contrastRatio: Calculated contrast ratio (e.g., 21 for black on white)
passes: Whether the combination meets the specified WCAG level
level: WCAG level checked ("AA" or "AAA")
fontSize: Font size category ("normal" or "large")
minimumRequired: Minimum contrast ratio required for the level and font size
wcagRequirements: Complete WCAG contrast requirements for all levels
recommendations: Array of suggestions (only included when contrast fails)
Example:
{
"contrastRatio": 21,
"passes": true,
"level": "AA",
"fontSize": "normal",
"minimumRequired": 4.5,
"wcagRequirements": {
"AA": { "normal": 4.5, "large": 3.0 },
"AAA": { "normal": 7.0, "large": 4.5 }
}
}Example prompts:
"Check if black text on white background is WCAG AA compliant"
"What's the contrast ratio between #4264fb and white?"
"Does gray text (#767676) on white meet AAA standards for large text?"
"Check color contrast for rgb(51, 51, 51) on rgb(245, 245, 245)"
"Is this color combination accessible: foreground 'navy' on background 'lightblue'?"
Compares two Mapbox styles and reports structural differences, including changes to layers, sources, and properties. This offline comparison tool performs deep object comparison without requiring API access.
Parameters:
styleA (string or object, required): First Mapbox style to compare (JSON string or style object)
styleB (string or object, required): Second Mapbox style to compare (JSON string or style object)
ignoreMetadata (boolean, optional): If true, ignores metadata fields (id, owner, created, modified, draft, visibility) when comparing
Comparison features:
Deep recursive comparison of nested structures
Layer comparison by ID (not array position)
Detailed diff reporting with JSON paths
Identifies additions, removals, and modifications
Optional metadata filtering
Returns:
{
"identical": false,
"differences": [
{
"path": "layers.water.paint.fill-color",
"type": "modified",
"valueA": "#a0c8f0",
"valueB": "#b0d0ff",
"description": "Modified property at layers.water.paint.fill-color"
}
],
"summary": {
"totalDifferences": 1,
"added": 0,
"removed": 0,
"modified": 1
}
}Example prompts:
"Compare these two Mapbox styles and show me the differences"
"What changed between my old style and new style?"
"Compare styles ignoring metadata fields"
Optimizes Mapbox styles by removing redundancies, simplifying expressions, and reducing file size.
Parameters:
style (string or object, required): Mapbox style to optimize (JSON string or style object)
optimizations (array, optional): Specific optimizations to apply. If not specified, all optimizations are applied. Available optimizations:
remove-unused-sources: Remove sources not referenced by any layer
remove-duplicate-layers: Remove layers that are exact duplicates
simplify-expressions: Simplify boolean expressions (e.g., ["all", true] → true)
remove-empty-layers: Remove layers with no visible properties (excluding background layers)
consolidate-filters: Identify layers with identical filters that could be consolidated
Optimizations performed:
Remove unused sources: Identifies and removes source definitions that aren't referenced by any layer
Remove duplicate layers: Detects layers with identical properties (excluding ID) and removes duplicates
Simplify expressions: Simplifies boolean logic in filters and property expressions:
["all", true] → true
["any", false] → false
["!", false] → true
["!", true] → false
Remove empty layers: Removes layers with no paint or layout properties (background layers are preserved)
Consolidate filters: Identifies groups of layers with identical filter expressions
Returns:
A JSON object with:
optimizedStyle: The optimized Mapbox style
optimizations: Array of optimizations applied
summary: Statistics including size savings and percent reduction
Example:
{
"optimizedStyle": { "version": 8, "sources": {}, "layers": [] },
"optimizations": [
{
"type": "remove-unused-sources",
"description": "Removed 2 unused source(s): unused-source1, unused-source2",
"count": 2
}
],
"summary": {
"totalOptimizations": 2,
"originalSize": 1234,
"optimizedSize": 890,
"sizeSaved": 344,
"percentReduction": 27.88
}
}Example prompts:
"Optimize this Mapbox style to reduce its file size"
"Remove unused sources from my style"
"Simplify the expressions in this style"
"Find and remove duplicate layers in my map style"
"Optimize my style but only remove unused sources and empty layers"
This repository includes Agent Skills that provide domain expertise for building maps with Mapbox. Skills teach AI assistants about map design, security best practices, and common implementation patterns.
Available Skills:
🎨 mapbox-cartography: Map design principles, color theory, visual hierarchy, typography
🔐 mapbox-token-security: Token management, scope control, URL restrictions, rotation strategies
📐 mapbox-style-patterns: Common style patterns and layer configurations for typical scenarios
🔧 mapbox-integration-patterns: Framework-specific integration patterns for React, Vue, Svelte, Angular, and vanilla JS
✅ mapbox-style-quality: Expert guidance on validating, optimizing, and ensuring quality of Mapbox styles through validation, accessibility checks, and optimization
Skills complement the MCP server by providing expertise (how to think about design) while tools provide capabilities (how to execute actions).
For complete documentation and usage instructions, see skills/README.md.
To use these skills in Claude Code, create a symlink:
mkdir -p .claude
ln -s ../skills .claude/skillsOr copy to your global skills directory:
cp -r skills/* ~/.claude/skills/Upload skills as zip files via the Skills API. See Claude API Skills documentation.
MCP Prompts are pre-built workflow templates that guide AI assistants through multi-step tasks. They orchestrate multiple tools in the correct sequence, providing best practices and error handling built-in.
Available Prompts:
Create a new Mapbox map style and generate a shareable preview link with automatic token management.
Arguments:
style_name (required): Name for the new map style
style_description (optional): Description of the style theme or purpose
base_style (optional): Base style to start from (e.g., "streets-v12", "dark-v11")
preview_location (optional): Location to center the preview map
preview_zoom (optional): Zoom level for the preview (0-22, default: 12)
What it does:
Checks for an existing public token with styles:read scope
Creates a new public token if needed
Creates the map style
Generates a preview link
Example usage:
Use prompt: create-and-preview-style
Arguments:
style_name: "My Custom Map"
style_description: "A dark-themed map for nighttime navigation"
base_style: "dark-v11"
preview_location: "San Francisco"
preview_zoom: "13"Use conversational AI to build a custom styled map based on a theme description.
Arguments:
theme (required): Theme description (e.g., "dark cyberpunk", "nature-focused", "minimal monochrome")
emphasis (optional): Features to emphasize (e.g., "parks and green spaces", "transit lines")
preview_location (optional): Location to center the preview map
preview_zoom (optional): Zoom level for the preview (0-22, default: 12)
What it does:
Uses the Style Builder tool to create a themed style based on your description
Creates the style in your Mapbox account
Generates a preview link
Example usage:
Use prompt: build-custom-map
Arguments:
theme: "retro 80s neon"
emphasis: "nightlife and entertainment venues"
preview_location: "Tokyo"
preview_zoom: "14"Analyze and visualize GeoJSON data with automatic validation and bounding box calculation.
Arguments:
geojson_data (required): GeoJSON object or string to analyze
show_bounds (optional): Calculate and display bounding box (true/false, default: true)
convert_coordinates (optional): Provide Web Mercator conversion examples (true/false, default: false)
What it does:
Validates GeoJSON format
Calculates bounding box (if requested)
Provides coordinate conversion examples (if requested)
Generates an interactive visualization link
Example usage:
Use prompt: analyze-geojson
Arguments:
geojson_data: {"type":"FeatureCollection","features":[...]}
show_bounds: "true"
convert_coordinates: "false"Complete setup workflow for a new Mapbox project with proper token security and style initialization.
Arguments:
project_name (required): Name of the project or application
project_type (optional): Type of project: "web", "mobile", "backend", or "fullstack" (default: "web")
production_domain (optional): Production domain for URL restrictions (e.g., "myapp.com")
style_theme (optional): Initial style theme: "light", "dark", "streets", "outdoors", "satellite" (default: "light")
What it does:
Creates development token with localhost URL restrictions
Creates production token with domain URL restrictions (if provided)
Creates backend secret token for server-side operations (if needed)
Creates an initial map style using the specified theme
Generates preview link and provides integration guidance
Example usage:
Use prompt: setup-mapbox-project
Arguments:
project_name: "Restaurant Finder"
project_type: "fullstack"
production_domain: "restaurantfinder.com"
style_theme: "light"Systematic troubleshooting workflow for diagnosing and fixing Mapbox integration issues.
Arguments:
issue_description (required): Description of the problem (e.g., "map not loading", "401 error")
error_message (optional): Exact error message from console or logs
style_id (optional): Mapbox style ID being used, if applicable
environment (optional): Where the issue occurs: "development", "production", "staging"
What it does:
Verifies token validity and required scopes
Checks style configuration and existence
Analyzes error messages and provides specific solutions
Tests API endpoints to isolate the problem
Provides step-by-step fix instructions
Offers prevention strategies
Example usage:
Use prompt: debug-mapbox-integration
Arguments:
issue_description: "Getting 401 errors when map loads"
error_message: "401 Unauthorized"
style_id: "my-style-id"
environment: "production"Create a map style with data-driven properties that respond dynamically to feature data using expressions.
Arguments:
style_name (required): Name for the data-driven style
data_description (required): Description of the data (e.g., "population by city", "earthquake magnitudes")
property_name (required): Name of the data property to visualize (e.g., "population", "magnitude")
visualization_type (optional): How to visualize: "color", "size", "both", "heatmap" (default: "color")
color_scheme (optional): Color scheme: "sequential", "diverging", "categorical" (default: "sequential")
What it does:
Explains data-driven styling concepts and expressions
Provides appropriate expression templates for your use case
Offers color scales and size ranges based on visualization type
Creates the style with data-driven layers
Includes advanced expression examples (zoom-based, conditional)
Provides best practices for accessibility and performance
Example usage:
Use prompt: design-data-driven-style
Arguments:
style_name: "Population Density Map"
data_description: "City population data"
property_name: "population"
visualization_type: "both"
color_scheme: "sequential"Comprehensive quality validation workflow for Mapbox styles before production deployment.
Arguments:
style_id_or_json (required): Either a Mapbox style ID or complete style JSON
skip_optimization (optional): Set to "true" to skip style optimization (default: false)
wcag_level (optional): WCAG compliance level: "AA" or "AAA" (default: "AA")
What it does:
Loads the style (retrieves from Mapbox or parses JSON)
Validates all expressions (filters, paint properties, layout properties)
Validates GeoJSON sources for coordinate and structure errors
Checks color contrast for text layers (WCAG compliance)
Optimizes the style (removes redundancies, simplifies expressions)
Generates a comprehensive quality report with deployment readiness assessment
Example usage:
Use prompt: prepare-style-for-production
Arguments:
style_id_or_json: "username/my-style-id"
wcag_level: "AA"
skip_optimization: "false"Related:
See the mapbox-style-quality skill for detailed guidance on when to use validation tools, best practices, and optimization strategies.
This server exposes static reference documentation as MCP Resources. MCP clients that support the resources protocol can access them directly.
Available Resources:
Mapbox Style Specification Guide (resource://mapbox-style-layers)
Complete reference for Mapbox GL JS layer types and properties
Covers fill, line, symbol, circle, and fill-extrusion layers
Includes paint and layout properties for each layer type
Mapbox Streets v8 Fields Reference (resource://mapbox-streets-v8-fields)
Field definitions for all Streets v8 source layers
Enumerated values for filterable fields
Essential for building accurate style filters
Example: landuse layer has class field with values like park, cemetery, hospital, etc.
Mapbox Token Scopes Reference (resource://mapbox-token-scopes)
Comprehensive documentation of token scopes
Explains public vs. secret token scopes
Common scope combinations for different use cases
Best practices for token management
Mapbox Layer Type Mapping (resource://mapbox-layer-type-mapping)
Maps Streets v8 source layers to compatible GL JS layer types
Organized by geometry type (polygon, line, point)
Includes common usage patterns and examples
Helps avoid incompatible layer type/source layer combinations
Note: Resources provide static reference data that doesn't change frequently, while tools provide dynamic, user-specific data (like listing your styles or tokens) and perform actions (like creating styles or tokens).
This server includes comprehensive distributed tracing using OpenTelemetry (OTEL) for production-ready observability.
Opt-in Configuration: Tracing is disabled by default, enabling it requires only setting an OTLP endpoint
Tool Execution Tracing: Automatic instrumentation of all tool executions with timing, success/failure status, and error details
HTTP Request Instrumentation: Complete request/response tracing for Mapbox API calls with CloudFront correlation IDs
Configuration Tracing: Startup configuration loading with error tracking
Security: Input/output sizes logged but content is protected
Low Overhead: <1% CPU impact, ~10MB memory for trace buffers
# 1. Start Jaeger (Docker required)
npm run tracing:jaeger:start
# 2. Configure environment
cp .env.example .env
# Edit .env to add MAPBOX_ACCESS_TOKEN
# OTEL_EXPORTER_OTLP_ENDPOINT is already set to http://localhost:4318
# 3. Run the server
npm run inspect:build
# 4. View traces at http://localhost:16686
# 5. Stop Jaeger when done
npm run tracing:jaeger:stopThe server supports any OTLP-compatible backend including:
Development: Jaeger (local Docker)
Cloud Providers: AWS X-Ray, Azure Monitor, Google Cloud Trace
SaaS Platforms: Datadog, New Relic, Honeycomb
See .env.example for configuration examples for each platform.
Complete Tracing Guide - Detailed configuration, features, and integration examples
Verification Guide - Step-by-step verification and troubleshooting
# Enable tracing (required)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
# Optional configuration
OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
OTEL_TRACES_SAMPLER=traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1 # Sample 10% for high-volumeThe project includes snapshot tests to ensure tool integrity and prevent accidental additions or removals of tools. These tests automatically discover all tools and create a snapshot of their metadata.
What the snapshot test covers:
Tool class names (TypeScript classes follow PascalCaseTool convention, e.g., ListStylesTool)
Tool names (MCP identifiers must follow snake_case_tool convention, e.g., list_styles_tool)
Tool descriptions
When to update snapshots:
Adding a new tool: After creating a new tool, run the test with snapshot update flag:
npm test -- test/tools/tool-naming-convention.test.ts --updateSnapshotRemoving a tool: After removing a tool, update the snapshot:
npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshotModifying tool metadata: If you change a tool's name or description, update the snapshot:
npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshotRunning snapshot tests:
# Run all tests (snapshot will fail if tools have changed)
npm test
# Update snapshots after intentional changes
npm test -- --updateSnapshotImportant: Only update snapshots when you have intentionally added, removed, or modified tools. Unexpected snapshot failures indicate accidental changes to the tool structure.
# Run the built image
npm run inspect:build# Build the Docker image
docker build -t mapbox-mcp-devkit .
# Run and inspect the server
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-devkitnpx plop create-tool
# 1. Choose tool type:
# - Mapbox tool (makes API calls to Mapbox services)
# - Local tool (local processing, no API calls)
# 2. Provide tool name without suffix using PascalCase (e.g. Search)Generated file structure:
The plop generator creates three files for each new tool:
src/tools/your-tool-name-tool/
├── YourToolNameTool.schema.ts # Input schema definition and types
├── YourToolNameTool.ts # Main tool implementation
└── YourToolNameTool.test.ts # Unit testsAfter creating a new tool:
Update the input schema in YourToolNameTool.schema.ts:
Define the input parameters using Zod schema
Export both the schema and the inferred TypeScript type
Update the tool description in YourToolNameTool.ts:
Provide a clear description of what the tool does
Implement the tool logic in the execute method
Update test cases with actual test data in YourToolNameTool.test.ts
Update the snapshot test to include the new tool:
npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshotRun all tests to ensure everything works:
npm testSchema separation benefits:
Better code organization with separate schema files
Easier maintenance when schema changes
Consistent with existing tools in the project
Enhanced TypeScript type safety
Set VERBOSE_ERRORS=true to get detailed error messages from the MCP server. This is useful for debugging issues when integrating with MCP clients.
By default, the server returns generic error messages. With verbose errors enabled, you'll receive the actual error details, which can help diagnose API connection issues, invalid parameters, or other problems.
Interactive Previews: MCP Apps (primary) & MCP-UI (compatibility)
This server actively invests in MCP Apps as its primary interactive preview protocol, delivering self-contained HTML app panels directly inside the chat. MCP Apps is supported by Claude Desktop, VS Code with GitHub Copilot, and Claude Code — no configuration needed.
MCP-UI (@mcp-ui/server) is also maintained for backwards compatibility with clients like Goose. It is not being removed, but new interactive preview development is focused on MCP Apps.
Supported Tools:
preview_style_tool - Interactive Mapbox style preview panel
geojson_preview_tool - Interactive GeoJSON visualization panel
style_comparison_tool - Side-by-side style comparison panel
Client support:
Client | MCP Apps | MCP-UI |
Claude Desktop | ✅ | |
VS Code with GitHub Copilot | ✅ | |
Claude Code | ✅ | |
Goose | ✅ | ✅ |
Other clients |
Disabling MCP-UI (Optional):
MCP Apps support is always active. If you want to disable the MCP-UI UIResource (used by Goose):
Via environment variable:
export ENABLE_MCP_UI=falseOr via command-line flag:
node dist/esm/index.js --disable-mcp-uiNote: You typically don't need to disable this. All clients receive a usable text URL regardless; interactive previews are a progressive enhancement on top.
Issue: Tools fail with authentication errors
Solution: Check that your MAPBOX_ACCESS_TOKEN has the required scopes for the tool you're using. See the token scopes section above.
Issue: Large GeoJSON files cause slow performance
Solution: The GeoJSON preview tool may be slow with very large files. Consider simplifying geometries or using smaller datasets for preview purposes.
Follow these steps to publish a new release:
Bump the version in package.json to the target version (e.g., 1.0.0).
Sync versions across manifest.json and server.json:
node scripts/sync-manifest-version.cjsThis reads the version from package.json and updates manifest.json and server.json (including packages[0].version) to match.
Prepare the changelog — this replaces the "Unreleased" heading with the version and date:
npm run changelog:prepare-release 1.0.0Commit, tag, and push:
git add package.json manifest.json server.json CHANGELOG.md
git commit -m "Release v1.0.0"
git tag v1.0.0
git push && git push --tagsPublish via the mcp-server-publisher workflow:
Go to the Actions tab in the mcp-server-publisher repo
Select "Release MCP Server"
Choose mcp-devkit-server from the repository dropdown
Enter the version — it must exactly match the package.json version
Leave the branch field empty for stable releases (or specify a branch for dev releases)
The workflow will: build, test, publish to NPM (@mapbox/mcp-devkit-server), publish to the MCP Registry, create a DXT package, and create a GitHub Release
The following files must have matching versions before publishing:
File | Fields |
|
|
|
|
|
|
The sync-manifest-version.cjs script handles syncing these automatically from package.json.
To publish a pre-release from a feature branch:
Set the version in package.json with a pre-release suffix -dev (e.g., 1.0.0-dev)
Run node scripts/sync-manifest-version.cjs
In the publisher workflow, enter the version and specify the branch name
The package will be published to NPM under the dev tag (won't affect latest)
We welcome contributions to the Mapbox Development MCP Server! Please review our documentation:
Engineering Standards (docs/engineering_standards.md) - Comprehensive guidelines for all contributors
CLAUDE.md - Architecture and technical patterns
AGENTS.md - Critical patterns and common errors for AI agents
GitHub Copilot Guidelines - Copilot-specific development practices
Calculates bounding box of given GeoJSON content, returns as [minX, minY, maxX, maxY]
| Name | Required | Description | Default |
|---|---|---|---|
| geojson | Yes | GeoJSON content to calculate bounding box for |
| Name | Required | Description |
|---|---|---|
| bbox | Yes | Bounding box as [minX, minY, maxX, maxY] |
| message | No | Status or error message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the return format, which is useful but doesn't disclose additional behavioral traits 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?
Single sentence, front-loaded with verb and resource, no wasted words. Every part 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 only one parameter with full schema description and an existing output schema, the description completely covers what the tool does and the output format. 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 description coverage is 100%; the parameter 'geojson' is fully described in the schema. The description adds no additional meaning or usage details 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 verb 'calculates' and the resource 'bounding box of given GeoJSON content', and specifies the return format [minX, minY, maxX, maxY]. This distinguishes it from sibling tools like country_bounding_box_tool or coordinate_conversion_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?
No explicit guidance on when to use versus alternatives (e.g., country_bounding_box_tool). The purpose is clear, but the description does not provide context for decision-making among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks color contrast ratios between foreground and background colors for WCAG 2.1 accessibility compliance
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | WCAG conformance level to check against (default: AA) | |
| fontSize | No | Font size category: normal (<18pt or <14pt bold) or large (≥18pt or ≥14pt bold) | |
| backgroundColor | Yes | Background color in any CSS format (hex, rgb, rgba, named colors) | |
| foregroundColor | Yes | Foreground color (text color) in any CSS format (hex, rgb, rgba, named colors) |
| Name | Required | Description |
|---|---|---|
| level | Yes | WCAG level checked (AA or AAA) |
| passes | Yes | Whether the contrast ratio meets the specified WCAG level |
| fontSize | Yes | Font size category (normal or large) |
| contrastRatio | Yes | Calculated contrast ratio between foreground and background |
| minimumRequired | Yes | Minimum contrast ratio required for the specified level and font size |
| recommendations | No | Optional recommendations for improvement |
| wcagRequirements | Yes | Complete WCAG contrast requirements for all levels |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds the WCAG compliance context but no further behavioral details (e.g., no mention of input validation, limits). A baseline score 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?
Single, well-structured sentence that front-loads the core purpose. No unnecessary 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 simplicity, the presence of an output schema, and comprehensive annotations, the description is complete. It covers the essential purpose without needing more detail.
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?
Input schema has 100% description coverage for all 4 parameters, including enums and format details. The description adds no additional parameter semantics beyond what the schema provides, so baseline score is correct.
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 checks color contrast ratios for WCAG 2.1 accessibility compliance, with a specific verb ('checks'), resource ('color contrast ratios'), and purpose, distinguishing it from sibling tools like validate_style_tool or preview_style_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 implicitly indicates when to use the tool (for WCAG compliance), but does not explicitly state when not to use it or mention alternatives. Given the sibling context, the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compares two Mapbox styles and reports differences in structure, layers, sources, and properties
| Name | Required | Description | Default |
|---|---|---|---|
| styleA | Yes | First Mapbox style (JSON string or style object) | |
| styleB | Yes | Second Mapbox style (JSON string or style object) | |
| ignoreMetadata | No | Ignore metadata fields like id, owner, created, modified |
| Name | Required | Description |
|---|---|---|
| summary | Yes | Summary of differences |
| identical | Yes | Whether the styles are identical |
| differences | Yes | List of differences found |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. Description adds that it reports differences but does not detail output format or potential edge cases. 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?
Single sentence, front-loaded with the core action, no redundant words. Efficiently conveys purpose.
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, the return format is documented elsewhere. The description covers what the tool does and how it compares, though it could briefly differentiate from the similarly named sibling style_comparison_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%, with each parameter already explained. The description does not add additional meaning beyond what the schema provides, so baseline score 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?
Clearly states the action (compares), resource (two Mapbox styles), and what is reported (differences in structure, layers, sources, and properties). Distinguishes from siblings by specifying a focused comparison vs. other style 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?
No guidance on when to use this tool versus alternatives like style_comparison_tool or validate_style_tool. Does not mention prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Converts coordinates between WGS84 (longitude/latitude) and EPSG:3857 (Web Mercator) coordinate systems
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Target coordinate system: wgs84 (longitude/latitude) or epsg3857 (Web Mercator) | |
| from | Yes | Source coordinate system: wgs84 (longitude/latitude) or epsg3857 (Web Mercator) | |
| coordinates | Yes | Array of two numbers representing coordinates |
| Name | Required | Description |
|---|---|---|
| to | Yes | Target coordinate system |
| from | Yes | Source coordinate system |
| input | Yes | Input coordinates |
| output | Yes | Converted coordinates |
| message | No | Conversion status message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. Description adds specificity about coordinate systems and conversion direction. No contradictions, and no additional behavioral traits (e.g., error cases) are disclosed, but annotations cover the core safety profile.
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?
Single sentence that is front-loaded and contains no superfluous information. Every word contributes to understanding the tool's core function.
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 and annotations provided, the description is sufficient for a straightforward conversion tool. It lacks details about edge cases (e.g., invalid coordinates) but overall covers the essential purpose.
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 descriptions for all three parameters. Description does not add any new semantics beyond what the schema provides. 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?
Description clearly states verb ('converts') and specific resources ('coordinates between WGS84 and EPSG:3857'). No sibling tools perform this function, so it is well-distinguished.
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 does not provide explicit when-to-use or when-not-to-use guidance. However, since no other tool handles coordinate conversion, usage is implicitly clear. Lacks exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets bounding box for a country by its ISO 3166-1 country code, returns as [minX, minY, maxX, maxY].
| Name | Required | Description | Default |
|---|---|---|---|
| iso_3166_1 | Yes | ISO 3166-1 country code (2-10 characters, e.g., "CN", "US", "AE" ) |
| Name | Required | Description |
|---|---|---|
| bbox | Yes | Bounding box as [minX, minY, maxX, maxY] |
| message | No | Status or error message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only and idempotent. The description adds transparency about the return format as [minX, minY, maxX, maxY], which is useful 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?
Single sentence that is perfectly front-loaded and concise, with 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?
For a simple one-parameter tool with an output schema, the description covers the purpose, input, and output format adequately, leaving no major 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%, and the schema already describes the parameter well. The description adds the return format but does not provide additional parameter-level 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 gets a bounding box for a country using an ISO code, distinguishing it from sibling tools like bounding_box_tool which is more generic.
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 specifies the input is an ISO 3166-1 country code, indicating when to use this tool, but does not explicitly mention when not to use it or alternatives like bounding_box_tool for custom areas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Mapbox style
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name for the style | |
| style | Yes | Complete Mapbox Style Specification object. Must include: version (8), sources, layers. Optional: sprite, glyphs, center, zoom, bearing, pitch, metadata, etc. See https://docs.mapbox.com/mapbox-gl-js/style-spec/ |
| Name | Required | Description |
|---|---|---|
| id | Yes | Unique style identifier |
| fog | No | Fog properties |
| name | Yes | Human-readable name for the style |
| zoom | No | Default zoom level |
| draft | No | Whether this is a draft version |
| light | No | Global light source (deprecated, use lights) |
| owner | Yes | Username of the style owner |
| pitch | No | Default pitch in degrees |
| center | No | Default map center [longitude, latitude] |
| glyphs | No | URL template for glyph sets |
| layers | Yes | Layers in draw order |
| lights | No | Array of 3D light sources |
| sprite | No | Base URL for sprite image and metadata |
| bearing | No | Default bearing in degrees |
| created | Yes | ISO 8601 timestamp when style was created |
| imports | No | Imported styles |
| sources | Yes | Data source specifications |
| terrain | No | Global terrain elevation |
| version | Yes | Style specification version number. Must be 8 |
| metadata | No | Arbitrary properties for tracking |
| modified | Yes | ISO 8601 timestamp when style was last modified |
| protected | No | Whether style is protected from modifications |
| projection | No | Map projection |
| transition | No | Default transition timing |
| visibility | Yes | Style visibility setting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It states 'Create' which is consistent with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), but does not disclose side effects, limits, or response behavior. Given annotations are present, the description fails to add supplementary value.
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. It is front-loaded and appropriate for a simple create operation, but could be expanded slightly without sacrificing brevity (e.g., noting required fields).
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?
Despite having an output schema, the description does not explain what the tool returns (e.g., the created style object ID). The tool expects a complex nested object (style specification) without any usage hints. For a create operation with two required parameters, the description is insufficiently informative.
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 covers both parameters with descriptions, achieving 100% schema description coverage. The description does not add meaning beyond what the schema provides; it simply implies the purpose. A score of 3 reflects adequate schema coverage but no additional insight from the description.
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 new Mapbox style, but it does not differentiate from sibling tools like style_builder_tool, which may also create styles. The verb 'Create' and resource 'Mapbox style' are specific enough for basic understanding, but lack explicit distinction.
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?
No guidance is provided on when to use this tool versus alternatives such as style_builder_tool or update_style_tool. There is no mention of prerequisites, use cases, or exclusions, leaving the agent without decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Mapbox public access token with specified scopes and optional URL restrictions.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | Description of the token | |
| scopes | Yes | Array of scopes/permissions for the public token. Valid scopes: styles:tiles, styles:read, fonts:read, datasets:read, vision:read. | |
| expires | No | Optional expiration time in ISO 8601 format (maximum 1 hour in the future) | |
| allowedUrls | No | Optional array of URLs where the token can be used (max 100) |
| Name | Required | Description |
|---|---|---|
| id | Yes | The token's unique identifier |
| note | Yes | Human-readable description of the token |
| token | Yes | The actual access token string |
| usage | Yes | Token usage type: pk (public), sk (secret), or tk (temporary) |
| client | Yes | The client for the token |
| scopes | Yes | Array of scopes granted to the token |
| created | Yes | ISO 8601 creation timestamp |
| default | Yes | Whether this is the default token |
| expires | No | Expiration time in ISO 8601 format (temporary tokens only) |
| modified | Yes | ISO 8601 last modified timestamp |
| allowedUrls | No | URLs that the token is restricted to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a safe write operation. The description adds no additional behavioral context beyond what annotations provide (e.g., rate limits, reversibility, or activation status). Since annotations carry the burden, 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?
The description is a single sentence that efficiently conveys the tool's purpose, verb, resource, and key attributes. It is front-loaded with the most important information and contains no unnecessary 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 that an output schema exists (though not shown), the description does not need to explain return values. It adequately defines the tool's function for a creation operation. However, it could mention constraints like maximum number of tokens per account, but this is not essential for basic 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?
Schema description coverage is 100%, with each parameter clearly described (e.g., 'note', 'scopes', 'expires', 'allowedUrls'). The description's mention of 'scopes and optional URL restrictions' does not add meaningful semantics beyond the schema, so the baseline of 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 the verb 'Create', the resource 'Mapbox public access token', and specifies key attributes ('with specified scopes and optional URL restrictions'). This distinguishes it from sibling tools like list_tokens_tool (which lists tokens) and other create tools for different resources (e.g., create_style_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 implies usage for creating a new token with scopes and URL restrictions but does not explicitly state when to use this tool versus alternatives like list_tokens_tool (for listing) or other create tools. No when-not-to-use guidance is provided, leaving some ambiguity for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Mapbox style by ID
| Name | Required | Description | Default |
|---|---|---|---|
| styleId | Yes | Style ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds no extra context beyond 'Delete', such as irreversibility or side effects, so it does not enhance transparency.
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, which is concise. However, it could be slightly more structured with bullet points for key details, but brevity is acceptable.
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 (one param, no output schema), the description covers the basic action but omits important details like permanence of deletion and requirement that the style exists, leaving gaps for the agent.
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 sole parameter 'styleId' having a description. The tool description does not add additional meaning beyond the schema, so 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?
Description clearly states 'Delete a Mapbox style by ID' with specific verb and resource, distinguishing it from sibling tools like create_style_tool or update_style_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?
No explicit guidance on when or when not to use this tool. While the purpose is clear, it lacks prerequisites or alternatives, falling short of best practices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a geojson.io URL to visualize GeoJSON data. Returns only the URL link.
| Name | Required | Description | Default |
|---|---|---|---|
| geojson | Yes | GeoJSON data as a JSON string (e.g., {"type": "Point", "coordinates": [-122.4194, 37.7749]}) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by stating it 'returns only the URL link,' clarifying the output format. However, it does not disclose behavior for invalid GeoJSON or rate limits, but given annotation coverage, a 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?
Two sentences, zero fluff. Every word contributes meaning. Ideal length and structure for a simple 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 low complexity (one parameter, no output schema, no nested objects), the description fully covers what the tool does and what it returns. No additional context is needed.
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% for the single parameter 'geojson', with a clear example in the schema. The description does not add extra parameter details beyond what the schema provides, so 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 the tool generates a geojson.io URL to visualize GeoJSON data, specifying the verb ('preview' from name, 'generate' in description) and resource (GeoJSON data as URL). This distinctly separates it from sibling tools like validate_geojson_tool or style preview 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 no guidance on when to use this tool versus alternatives, lacks context on prerequisites (e.g., valid GeoJSON), and does not mention when not to use it. It only states the tool's function without recommending scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single user feedback item from the Mapbox Feedback API by its unique ID. Use this tool to retrieve detailed information about a specific user-reported issue, suggestion, or feedback about map data, routing, or POI details. Requires user-feedback:read scope on the access token.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format: "json_string" returns raw JSON data as a JSON string that can be parsed; "formatted_text" returns human-readable text. Both return as text content but json_string contains parseable JSON data while formatted_text is for display. | formatted_text |
| feedback_id | Yes | The unique identifier of the feedback item |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a critical behavioral detail: the required OAuth scope ('user-feedback:read'), which goes beyond 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 two concise sentences: one stating the core purpose and one adding usage context and auth requirements. No fluff, 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?
For a simple get-by-id tool with comprehensive annotations and high schema coverage, the description provides enough context (source, purpose, scope). It lacks details about the returned data structure, but the output schema is absent and the purpose implies retrieving 'detailed information' without specifying fields.
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%, and the parameter descriptions in the schema are already detailed (e.g., format enum with explanations). The tool description does not add any additional parameter semantics beyond what the schema provides, 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 verb ('Get') and resource ('a single user feedback item by its unique ID'), specifying the API source. It implies differentiation from list_feedback_tool by focusing on a single item, but does not explicitly contrast with siblings.
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 tells when to use it ('to retrieve detailed information about a specific...feedback'), but does not mention when not to use it or suggest alternatives like list_feedback_tool for fetching multiple items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List user feedback items from the Mapbox Feedback API with filtering, sorting, and pagination. Use this tool to access user-reported issues, suggestions, and feedback about map data, routing, and POI details. Supports comprehensive filtering by status, category, date ranges, trace IDs, and search text. Requires user-feedback:read scope on the access token.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | A cursor from a previous response. Use this to fetch the next page of results. | |
| limit | No | The maximum number of feedback items to return (1-1000) | |
| order | No | The sort direction: asc (ascending, default) or desc (descending) | asc |
| format | No | Output format: "json_string" returns raw JSON data as a JSON string that can be parsed; "formatted_text" returns human-readable text. Both return as text content but json_string contains parseable JSON data while formatted_text is for display. | formatted_text |
| search | No | A search phrase. Returns items where the feedback text contains the phrase. | |
| status | No | Filter by one or more feedback statuses. Options: received, fixed, reviewed, out_of_scope | |
| sort_by | No | The field to sort results by. Options: received_at (default), created_at, or updated_at | received_at |
| category | No | Filter by one or more feedback categories | |
| trace_id | No | Filter by one or more trace_id values. At least one must match. | |
| feedback_ids | No | Filter by one or more feedback item IDs. At least one must match. | |
| created_after | No | Return items created after the specified time. Use ISO 8601 format: YYYY-MM-DDTHH:mm:ss.SSSZ | |
| updated_after | No | Return items last updated after the specified time. Use ISO 8601 format: YYYY-MM-DDTHH:mm:ss.SSSZ | |
| created_before | No | Return items created before the specified time. Use ISO 8601 format: YYYY-MM-DDTHH:mm:ss.SSSZ | |
| received_after | No | Return items received by Mapbox after the specified time. Use ISO 8601 format: YYYY-MM-DDTHH:mm:ss.SSSZ | |
| updated_before | No | Return items last updated before the specified time. Use ISO 8601 format: YYYY-MM-DDTHH:mm:ss.SSSZ | |
| received_before | No | Return items received by Mapbox before the specified time. Use ISO 8601 format: YYYY-MM-DDTHH:mm:ss.SSSZ |
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 the scope requirement and the types of feedback accessible. It does not contradict annotations and builds upon them.
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 (4 sentences), front-loaded with the core action, and contains no redundant information. Every sentence serves a purpose.
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 16 parameters and no output schema, the description covers the tool's purpose, scope, and authorization. It could be improved by explicitly noting the two output formats (json_string and formatted_text) and clarifying that the response is a list of items. Nonetheless, it is largely 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 baseline is 3. The description provides context about the API and feedback types but adds minimal value beyond the individual parameter descriptions 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?
The description clearly states the verb 'List', the resource 'user feedback items', and elaborates on the scope (map data, routing, POI) and capabilities (filtering, sorting, pagination). It effectively distinguishes from siblings like get_feedback_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 clearly states when to use the tool and lists filtering options. It mentions the required scope ('user-feedback:read'). However, it does not explicitly exclude cases or recommend alternatives, such as using get_feedback_tool for single items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List styles for a Mapbox account. Use limit parameter to avoid large responses (recommended: limit=5-10). Use start parameter for pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of styles to return (recommended: 5-10 to avoid token limits, default: no limit) | |
| start | No | Start token for pagination (use the "start" value from previous response) |
| Name | Required | Description |
|---|---|---|
| styles | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive. Description adds value by warning about large responses and explaining pagination behavior, which the annotations do not cover.
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, front-loaded with the main action (list styles), 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 complete input schema descriptions and an output schema, the description provides essential context for usage, making the tool fully understood.
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 meaningful guidance: recommends specific limit values and explains start as pagination token, enhancing the schema descriptions.
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 lists styles for a Mapbox account, using the specific verb 'list' and resource 'styles'. It distinguishes from siblings like create, retrieve, update, delete 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?
Provides clear usage context: recommends limit=5-10 to avoid large responses and explains start for pagination. Does not explicitly state when not to use, but adequate for a listing tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Mapbox access tokens for the authenticated user with optional filtering and pagination. Returns metadata for all tokens (public and secret), but the actual token value is only included for public tokens (secret token values are omitted for security). When using pagination, the "start" parameter must be obtained from the "next_start" field of the previous response (it is not a token ID)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of tokens to return (1-100) | |
| start | No | Token ID to start pagination from | |
| usage | No | Filter by token type: pk (public) | |
| sortby | No | Sort tokens by created or modified timestamp | |
| default | No | Filter to show only the default public token |
| Name | Required | Description |
|---|---|---|
| count | Yes | Total number of tokens returned |
| tokens | Yes | |
| next_start | No | Pagination token for next page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: secret token values are omitted for security, and pagination uses next_start field. These details go beyond the annotations, providing valuable transparency.
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 serving a purpose: stating the main action, explaining security behavior, and clarifying pagination mechanics. No redundant or unnecessary text.
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 (5 parameters, pagination, security nuance) and the presence of an output schema, the description covers all essential aspects: listing, filtering, pagination, and behavioral details. It is complete for an agent to correctly invoke the 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?
All parameters are documented in the schema (100% coverage). The description adds specific insight into the start parameter's behavior (must come from previous response's next_start), which is not clear from the schema alone. This augmentation justifies above baseline.
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 lists Mapbox access tokens for the authenticated user with optional filtering and pagination. It explains the distinction between public and secret token values, which adds specificity. This purpose is distinct from sibling tools like create_token_tool, making it unambiguous.
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 optional filtering and pagination, including crucial pagination guidance (start parameter from next_start). However, it does not explicitly state when to use this tool versus alternatives or when not to use it, though the listing context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Optimizes Mapbox styles by removing unused sources, duplicate layers, and simplifying expressions
| Name | Required | Description | Default |
|---|---|---|---|
| style | Yes | Mapbox style to optimize (JSON string or style object) | |
| optimizations | No | Specific optimizations to apply (if not specified, all optimizations are applied) |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| optimizations | Yes | List of optimizations that were applied |
| optimizedStyle | Yes | The optimized Mapbox style |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds specific optimizations performed, which is helpful. However, it does not explicitly state that the tool returns an optimized style without modifying the original, which would align with 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?
The description is a single, well-structured sentence that conveys the core functionality without any unnecessary words. It is front-loaded with the main purpose and specific optimizations.
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 that the schema has 2 parameters with 100% coverage and an output schema exists, the description is sufficiently complete for an AI to understand the tool's purpose. It could briefly mention that the output is an optimized style, but the output schema likely 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%, so baseline is 3. The description does not add any additional parameter-specific meaning beyond what the schema provides. It mentions the general actions but not the parameter constraints or formats.
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 specifies the action 'Optimizes' and the resource 'Mapbox styles', listing specific optimizations: removing unused sources, duplicate layers, and simplifying expressions. This distinguishes the tool from sibling tools like validate_style_tool or preview_style_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 implies when to use (to optimize a style) but does not provide explicit guidance on when not to use, prerequisites, or alternatives. For example, it doesn't suggest validating before optimizing or mention that optimization might alter the visual output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate preview URL for a Mapbox style using an existing public token
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Show title in the preview | |
| styleId | Yes | Style ID to preview | |
| zoomwheel | No | Enable zoom wheel control | |
| accessToken | Yes | Mapbox public access token (required, must start with pk.* and have styles:read permission). Secret tokens (sk.*) cannot be used as they cannot be exposed in browser URLs. Please use an existing public token or get one from list_tokens_tool or create one with create_token_tool with styles:read permission. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, which the description aligns with ('Generate preview URL'). Beyond annotations, the description adds context about using an existing public token, and the accessToken parameter description clarifies that secret tokens cannot be used—a behavioral constraint not in 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, front-loaded sentence with no wasted words. It efficiently conveys the tool's core function.
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 simple URL-generation tool with no output schema, the description is mostly complete. It could optionally state the return value (e.g., 'Returns a preview URL'), but the purpose is clear from the title and description.
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 main description does not add parameter meanings beyond the schema; the only extra context ('using an existing public token') is already covered by the accessToken parameter description.
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 (generate preview URL) and resource (Mapbox style), with a specific condition (using existing public token). It distinguishes itself from sibling tools like geojson_preview_tool and style_builder_tool by focusing solely on style preview.
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 preview but does not explicitly state when to use this tool over alternatives. It does mention the token requirement but lacks comparison with siblings like update_style_tool or create_style_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific Mapbox style by ID
| Name | Required | Description | Default |
|---|---|---|---|
| styleId | Yes | Style ID to retrieve |
| Name | Required | Description |
|---|---|---|
| id | Yes | Unique style identifier |
| fog | No | Fog properties |
| name | Yes | Human-readable name for the style |
| zoom | No | Default zoom level |
| draft | No | Whether this is a draft version |
| light | No | Global light source (deprecated, use lights) |
| owner | Yes | Username of the style owner |
| pitch | No | Default pitch in degrees |
| center | No | Default map center [longitude, latitude] |
| glyphs | No | URL template for glyph sets |
| layers | Yes | Layers in draw order |
| lights | No | Array of 3D light sources |
| sprite | No | Base URL for sprite image and metadata |
| bearing | No | Default bearing in degrees |
| created | Yes | ISO 8601 timestamp when style was created |
| imports | No | Imported styles |
| sources | Yes | Data source specifications |
| terrain | No | Global terrain elevation |
| version | Yes | Style specification version number. Must be 8 |
| metadata | No | Arbitrary properties for tracking |
| modified | Yes | ISO 8601 timestamp when style was last modified |
| protected | No | Whether style is protected from modifications |
| projection | No | Map projection |
| transition | No | Default transition timing |
| visibility | Yes | Style visibility setting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description does not add further behavioral context, but 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?
A single sentence of 8 words with no filler, front-loading the key 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?
For a simple read operation with one parameter and an existing output schema, the description is minimally adequate. However, it does not explain what 'retrieve' returns or differentiate from similar tools like preview_style_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% and the parameter 'styleId' is already described in the schema. The tool description adds no 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 'Retrieve a specific Mapbox style by ID' uses a specific verb and resource, clearly distinguishing it from siblings like list_styles_tool or create_style_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?
No guidance is provided on when to use this tool versus alternatives such as preview_style_tool or list_styles_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate Mapbox style JSON for creating new styles or updating existing ones.
The tool intelligently resolves layer types and filter properties using Streets v8 data. You don't need exact layer names - the tool automatically finds the correct layer based on your filters.
BASE STYLES: • standard: ALWAYS THE DEFAULT - Modern Mapbox Standard with best performance • Classic styles: streets-v12/light-v11/dark-v11/satellite-v9/outdoors-v12/satellite-streets-v12/navigation-day-v1/navigation-night-v1 Only use Classic when user explicitly says "create a classic style" or working with existing Classic style
STANDARD STYLE CONFIG: Use standard_config to customize the basemap: • Theme: default/faded/monochrome • Light: day/night/dawn/dusk • Show/hide: labels, roads, 3D buildings • Colors: water, roads, parks, etc.
LAYER ORDERING: • Layers are rendered in order - last layer in the array appears visually on top • The 'slot' parameter is OPTIONAL - by default, layer order in the array determines visibility • For Standard style, you can optionally use 'slot' to control placement:
No slot (default): Above all existing layers in the style
'top': Behind Place and Transit labels
'middle': Between basemap and labels
'bottom': Below most basemap features
LAYER RENDERING: • render_type controls HOW to visualize the layer (line, fill, symbol, etc.) • Most important: Use render_type:"line" for outlines/borders even on polygon features • Default "auto" picks based on geometry, but override for specific effects:
Building outlines → render_type:"line" (not fill!)
Solid buildings → render_type:"fill" or "fill-extrusion" (3D)
Road lines → render_type:"line" (auto works too)
POI dots → render_type:"circle"
Labels → render_type:"symbol"
LAYER ACTIONS: • color: Apply a specific color • highlight: Make prominent • hide: Remove from view • show: Display with defaults
AUTO-DETECTION: The tool automatically finds the correct layer from your filter_properties. Examples: • { class: 'park' } → finds 'landuse' layer • { type: 'wetland' } → finds 'landuse_overlay' layer • { maki: 'restaurant' } → finds 'poi_label' layer • { toll: true } → finds 'road' layer • { admin_level: 0 } → finds 'admin' layer (for country boundaries) • { admin_level: 1 } → finds 'admin' layer (for state/province boundaries)
IMPORTANT LAYER NAMES: • Use "admin" for all boundaries (countries, states, etc.) • Use "building" (singular, not "buildings") • Use "road" for all streets, highways, paths
If a layer type is not recognized, the tool will provide helpful suggestions showing: • All available source layers from Streets v8 • Which fields are available in each layer • Examples of how to properly specify layers and filters
| Name | Required | Description | Default |
|---|---|---|---|
| layers | Yes | Layer configurations based on the mapbox-style-layers resource | |
| base_style | No | Base style template. ALWAYS use "standard" as the default for all new styles. Standard style provides the best performance and modern features. Only use Classic styles (streets/light/dark/satellite/outdoors/navigation) when explicitly requested with "create a classic style" or when working with an existing Classic style. | standard |
| style_name | No | Name for the style | Custom Style |
| global_settings | No | Global style settings | |
| standard_config | No | Configuration for the base Mapbox Standard style. These properties customize the underlying Standard style features - you can still add your own custom layers on top using the layers parameter. The Standard style provides a rich basemap that you can configure and enhance with additional layers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: auto-detection of layers, layer ordering, rendering types, and base style configuration. It does not contradict any annotations and provides transparency about tool behavior beyond what annotations offer.
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 long but well-structured with clear sections (base styles, config, layer ordering, rendering, actions, auto-detection, important names). It is front-loaded with purpose and each section adds value. Some redundancy in examples could be trimmed, but overall it is efficient given the tool's complexity.
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?
Despite having no output schema, the description thoroughly explains the tool's output: Mapbox style JSON. It covers all major aspects: base style selection, layer configuration, global settings, standard style customization, and auto-detection. The description is comprehensive for a complex tool, leaving no significant gaps 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?
Schema coverage is 100%, but the description adds substantial meaning beyond schema descriptions. For example, it explains slot placement in layering, render_type choices with specific use cases, filter_properties with examples, and layer_type usage. This enhances the agent's understanding of how to use parameters effectively.
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 generates Mapbox style JSON for creating or updating styles. It specifies the tool resolves layer types and properties using Streets v8 data, and auto-detects layers. This effectively distinguishes it from sibling tools like create_style_tool or update_style_tool which handle other aspects of style management.
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 extensive guidance: when to use standard vs classic styles, how layer ordering works, how to use render_type, and auto-detection examples. While it doesn't explicitly state when not to use the tool, it gives clear context and effectively differentiates from siblings. The description implies that classic styles should only be used on explicit request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a comparison URL for comparing two Mapbox styles side-by-side
| Name | Required | Description | Default |
|---|---|---|---|
| zoom | No | Initial zoom level for the map view (0-22). If provided along with latitude and longitude, sets the initial map position. | |
| after | Yes | Mapbox style for the "after" side. Accepts: full style URL (mapbox://styles/username/styleId), username/styleId format, or just styleId if using your own styles | |
| before | Yes | Mapbox style for the "before" side. Accepts: full style URL (mapbox://styles/username/styleId), username/styleId format, or just styleId if using your own styles | |
| latitude | No | Latitude coordinate for the initial map center (-90 to 90). Must be provided together with longitude and zoom. | |
| longitude | No | Longitude coordinate for the initial map center (-180 to 180). Must be provided together with latitude and zoom. | |
| accessToken | Yes | Mapbox public access token (required, must start with pk.* and have styles:read permission). Secret tokens (sk.*) cannot be used as they cannot be exposed in browser URLs. Please use a public token or create one with styles:read permission. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, confirming it's non-destructive. The description adds that it generates a URL, implying no side effects beyond that. No contradictions, but could clarify that the URL is meant for browser viewing.
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?
Single sentence of 14 words, extremely concise and front-loaded with the key purpose. 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 6 parameters and no output schema, the description does not explain what the returned URL contains or how to use it (e.g., open in browser). The agent may lack context on the output. However, for a simple URL generation tool, the basic purpose is 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?
All 6 parameters have schema descriptions covering 100%. The description adds no additional parameter-level meaning beyond the schema, so 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?
Title and description clearly state the tool generates a comparison URL for two Mapbox styles. Verb 'generate' is specific, and 'comparison URL' distinguishes from comparable sibling tools like 'compare_styles_tool' which likely does an inline comparison.
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 no guidance on when to use this tool versus alternatives like 'compare_styles_tool', or any prerequisites or exclusions. The agent must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query vector and raster data from Mapbox tilesets at geographic coordinates
| Name | Required | Description | Default |
|---|---|---|---|
| bands | No | Specific band names to query (for rasterarray tilesets) | |
| limit | No | Number of features to return (1-50, default: 5) | |
| dedupe | No | Whether to deduplicate identical features (default: true) | |
| layers | No | Specific layer names to query from the tileset | |
| radius | No | Radius in meters to search for features (default: 0) | |
| geometry | No | Filter results by geometry type | |
| latitude | Yes | Latitude coordinate to query | |
| longitude | Yes | Longitude coordinate to query | |
| tilesetId | No | Tileset ID to query (default: mapbox.mapbox-streets-v8) | mapbox.mapbox-streets-v8 |
| 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, so the tool's non-destructive, idempotent nature is clear. The description adds that it queries tile data, which is consistent but does not disclose further behavioral details.
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 at one sentence and front-loads the core purpose. However, it lacks any structure such as usage examples or parameter grouping, which could improve clarity.
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 that an output schema exists (per context signals), the description need not explain return values. However, for a tool with 9 parameters, a brief usage note or link to documentation would enhance completeness. Current description is adequate but minimal.
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%, meaning each parameter is fully described in the input schema. The tool description does not add additional parameter semantics beyond what the schema provides, so 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 uses a specific verb 'query' and identifies the resource 'vector and raster data from Mapbox tilesets at geographic coordinates', clearly distinguishing this tool from sibling tools that deal with styles, tokens, or coordinate conversion.
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 (e.g., bounding_box_tool or geojson_preview_tool) and does not mention any prerequisites or restrictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Mapbox style
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name for the style | |
| style | No | Complete Mapbox Style Specification object to update. Must include: version (8), sources, layers. Optional: sprite, glyphs, center, zoom, bearing, pitch, metadata, etc. See https://docs.mapbox.com/mapbox-gl-js/style-spec/ | |
| styleId | Yes | Style ID to update |
| Name | Required | Description |
|---|---|---|
| id | Yes | Unique style identifier |
| fog | No | Fog properties |
| name | Yes | Human-readable name for the style |
| zoom | No | Default zoom level |
| draft | No | Whether this is a draft version |
| light | No | Global light source (deprecated, use lights) |
| owner | Yes | Username of the style owner |
| pitch | No | Default pitch in degrees |
| center | No | Default map center [longitude, latitude] |
| glyphs | No | URL template for glyph sets |
| layers | Yes | Layers in draw order |
| lights | No | Array of 3D light sources |
| sprite | No | Base URL for sprite image and metadata |
| bearing | No | Default bearing in degrees |
| created | Yes | ISO 8601 timestamp when style was created |
| imports | No | Imported styles |
| sources | Yes | Data source specifications |
| terrain | No | Global terrain elevation |
| version | Yes | Style specification version number. Must be 8 |
| metadata | No | Arbitrary properties for tracking |
| modified | Yes | ISO 8601 timestamp when style was last modified |
| protected | No | Whether style is protected from modifications |
| projection | No | Map projection |
| transition | No | Default transition timing |
| visibility | Yes | Style visibility setting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, but the description adds no behavioral context. It does not clarify whether the update is incremental or a full replacement, auth requirements, side effects, or rate limits. The description fails to compensate for the lack of behavioral detail in 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 that conveys the core purpose efficiently. It is front-loaded and free of unnecessary words, though it could include more context without losing conciseness.
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 (3 params, nested object, output schema exists), the description is incomplete. It does not mention the output, behavior on missing styleId, version handling, or any side effects. The schema partially fills the gap, but the description alone is insufficient.
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 schema includes good descriptions for each parameter (e.g., the 'style' parameter links to the style spec). The description itself does not add parameter information, so it meets the baseline but does not exceed.
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 ('update') and resource ('Mapbox style'), which distinguishes it from create, delete, retrieve, and list tools. However, it does not differentiate from similar modification tools like style_builder_tool or optimize_style_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 no guidance on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites, or context for choosing between siblings like style_builder_tool or create_style_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validates Mapbox style expressions for syntax, operators, and argument correctness
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Context where the expression will be used | |
| expression | Yes | Mapbox expression to validate (JSON string or expression array) |
| Name | Required | Description |
|---|---|---|
| info | Yes | Informational messages |
| valid | Yes | Whether the expression is valid |
| errors | Yes | Critical errors |
| metadata | Yes | Expression metadata |
| warnings | Yes | Non-critical warnings |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context by detailing what is validated (syntax, operators, arguments), going beyond the schema.
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?
Single sentence that efficiently conveys the tool's purpose with no wasted words. 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 existence of an output schema and the tool's straightforward nature, the description covers the necessary behavioral aspects. 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 coverage is 100%, with both parameters described adequately. The description does not add extra meaning beyond the schema, so baseline score 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 the verb 'validates' and the resource 'Mapbox style expressions', specifying syntax, operators, and argument correctness. It distinguishes the tool from siblings like validate_style_tool by focusing on expressions only.
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?
No explicit guidance on when to use this tool versus alternatives such as validate_style_tool or preview_style_tool. The description omits context for when expression validation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validates GeoJSON objects for correctness, checking structure, coordinates, and geometry types
| Name | Required | Description | Default |
|---|---|---|---|
| geojson | Yes | GeoJSON object or JSON string to validate |
| Name | Required | Description |
|---|---|---|
| info | Yes | Informational messages |
| valid | Yes | Whether the GeoJSON is valid |
| errors | Yes | Critical errors |
| warnings | Yes | Non-critical warnings |
| statistics | Yes | GeoJSON statistics |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe behavior. The description adds value by specifying the aspects checked (structure, coordinates, geometry types), providing context 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?
The description is a single, well-structured sentence with no unnecessary words. It efficiently conveys the tool's purpose without 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?
Given the tool's simplicity and the presence of an output schema, the description adequately covers the core behavior. However, it does not mention validation error output or edge cases, which could be added for completeness.
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 coverage, the schema already describes the 'geojson' parameter as a 'GeoJSON object or JSON string to validate'. The description adds no additional meaning, so 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 verb 'validates' and the resource 'GeoJSON objects', and specifies what it checks (structure, coordinates, geometry types). It effectively distinguishes from sibling tools like validate_expression_tool and validate_style_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 implies usage for validating GeoJSON but provides no explicit guidance on when to use this tool versus alternatives (e.g., geojson_preview_tool) or prerequisites. Usage 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.
Validates Mapbox style JSON against the Mapbox Style Specification, checking for errors, warnings, and providing suggestions for improvement
| Name | Required | Description | Default |
|---|---|---|---|
| style | Yes | Mapbox style JSON object or JSON string to validate against the Mapbox Style Specification |
| Name | Required | Description |
|---|---|---|
| info | Yes | Informational messages and suggestions for improvement |
| valid | Yes | Whether the style is valid |
| errors | Yes | Critical errors that prevent the style from working |
| summary | Yes | Summary of style structure |
| warnings | Yes | Non-critical issues that may cause unexpected behavior |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by specifying that it checks for errors, warnings, and suggestions, which is helpful 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 a single, well-structured sentence that front-loads the tool's purpose. Every word contributes meaning, with no unnecessary filler.
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 validation tool with a single well-defined parameter and an output schema (not shown), the description is sufficiently complete. It covers the tool's core function without needing to explain return values since the output schema handles 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 description coverage is 100% (the 'style' parameter is well-described in the schema). The description does not add extra semantics beyond what the schema provides, so the 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 that the tool validates Mapbox style JSON against the Mapbox Style Specification, checking for errors, warnings, and suggestions. This distinguishes it from sibling tools like validate_expression_tool and validate_geojson_tool, which focus on specific sub-formats.
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 preview_style_tool, optimize_style_tool, or style_builder_tool. An agent would have no information about context or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but there is potential confusion between style_builder_tool and create_style_tool (both involve style creation) and between compare_styles_tool and style_comparison_tool (both compare styles). These pairs could cause an agent to select the wrong tool.
All tool names use underscores and end with '_tool', but naming patterns are mixed: some follow verb_noun (e.g., list_styles_tool) while others are noun_noun (e.g., style_builder_tool). This inconsistency makes it harder to predict tool names.
With 23 tools, the server covers a broad range of Mapbox developer operations including style management, tokens, feedback, geojson utilities, and validation. While slightly heavy, the count is reasonable for the domain.
The tool set covers CRUD for styles and tokens, feedback retrieval, validation, optimization, comparison, and geojson utilities. Minor gaps exist (e.g., no asset upload or tileset creation), but overall it provides a fairly complete surface for style development.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Give your AI agents the tools to build, manage, and run automation workflows.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mapbox/mcp-devkit-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
