The Magic Lane MCP Server transforms AI agents into geospatially intelligent assistants by providing tools for location search, routing, round trip planning, reverse geocoding, isochrone analysis, geofence management, static map rendering, and interactive map display.
Location Search: Find addresses, cities, and points of interest (POIs) by name or category (e.g., restaurants, gas stations, pharmacies, parking) using free-text queries and geographic context filtering, returning coordinates and metadata.
Route Planning: Calculate optimized routes between multiple locations supporting car, truck/lorry, bicycle, pedestrian, and public transport modes, with multi-stop routing, waypoint resolution, EV charging and parameters, emergency routing, scenic/fastest/shortest optimization, and dynamic POI integration.
Round Trip Planning: Generate circular routes that start and end at the same location, ideal for jogging loops, cycling routes, or delivery runs, with time-based or distance-based range targets.
Isochrone Analysis: Calculate reachability polygons showing all areas accessible within a given time or distance from a starting point, for any transport mode.
Reverse Geocoding: Convert coordinates or areas into detailed address information, supporting single-point, circular area, bounding box, polygon, and path/corridor searches.
Geofence Management: Create, read, update, and delete geographic boundaries (polygons, circles, rectangles), query geofences by proximity or bounding box, and check whether specific coordinates fall inside defined geofences.
Static Map Rendering: Generate PNG, JPEG, or WebP static map images of routes, isochrones, round trips, or custom location views with automatic viewport fitting and markers.
Interactive Map: Display interactive vector tile maps directly inside the conversation, supporting pan/zoom and overlays for locations, routes, isochrones, round trips, search results, geofences, and custom paths.
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., "@Magic Lane MCP Server plan a cycling route from Central Park to Brooklyn Bridge"
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.
The Magic Lane Model Context Protocol (MCP) Server enables any AI agent or application to become a geospatially intelligent assistant, capable of acting as a reliable companion for pedestrians, cyclists, and drivers alike.
Built on top of Magic Lane's advanced mapping and routing technology, this TypeScript-based MCP server empowers AI agents to:
Understand and process geospatial data,
Interpret user intent in a spatial context,
Deliver accurate, contextually relevant navigation guidance.
By leveraging Magic Lane's global map data and real-time geospatial intelligence, the MCP Server enables deeply personalized navigation and trip-planning experiences through core tools:
Intelligent Search - Find addresses, points of interest (POIs), or coordinates with intelligent search capabilities and POI category filtering.
Smart Routing - Generate optimized routes between multiple waypoints with support for various transport modes, route preferences, and dynamic POI integration.
Round Trip Planning - Create circular routes that start and end at the same location, perfect for jogging routes, cycling loops, or delivery runs.
Reverse Geocoding - Convert geographic coordinates into detailed address information including street name, city, state, country, and postal code.
Isochrone Analysis - Calculate reachability polygons showing areas accessible within specific time or distance constraints.
Route Visualization - Create visual map images of calculated routes, isochrones, and round trips for immediate geographical context and presentation.
Geofence Management - Create, manage, and query geographic boundaries for asset monitoring, location-based alerts, and spatial analysis with support for polygons, circles, and rectangles.
Interactive Map - Display an interactive vector tile map directly inside the conversation using MapLibre GL JS and MagicLane vector tiles. Supports location views, route visualization, isochrone overlays, round trip routes, search result markers, geofence areas, and custom coordinate paths — with one or many overlays per map and pan/zoom interactions.
The map functionalities can be visualized as high-quality map images through our new beta feature:
Static Map Rendering - Generate custom map views with markers, bounding boxes, or location-centered areas without route calculation, complementing route visualization for routes, isochrones, and round trips.
Together, these capabilities enable AI agents to act as true geospatial copilots - understanding spatial context, anticipating user needs, and optimizing every journey with precision and ease.
Transport Options: The server supports both stdio (for MCP-native clients like Claude Desktop) and HTTP (for web applications, serverless deployments, and custom integrations).
Related MCP server: Mapbox MCP Server
The Magic Lane MCP Server integrates seamlessly with any AI application or agent, providing access to geospatial data and navigation functionality. Before setup, ensure you have the following:
System Requirements:
Node.js 22+ installed (Download here)
npm (comes with Node.js)
A valid Magic Lane API Key (for access to map data)
An MCP-compatible AI client, such as:
Visual Studio Code with GitHub Copilot
Verify Prerequisites:
# Check Node.js version (should be 22+)
node --version
# Check npm version
npm --versionFor immediate testing, use npx to run the server without installation:
# Set your API key as environment variable
export MAGICLANE_API_KEY="your_api_key"
# Run the server directly
npx @magiclane/mcp-serverTo obtain a Magic Lane API token, follow our step-by-step guide. The detailed steps are:
Create a Magic Lane Account
Visit developer.magiclane.com/api/register and register for a free account.
Generate an API Key
Log in to your account
Navigate to the Projects Dashboard
Follow the instructions to generate your unique API key, which will serve as your access token for the MCP Server
To explore and integrate the MCP Server locally, follow these steps to install dependencies and build the project:
# Clone or navigate to the Magic Lane MCP Server directory
cd path/to/magiclane-mcp
# Install dependencies
npm install
# Build the TypeScript project
npm run build
# Verify the build was successful
ls dist/ # Should show map-server.esm.js and other compiled filesNote: Ensure Node.js 22+ and npm are properly installed before running these commands.
Standard MCP Server (stdio transport):
# Option 1: Using .env file (recommended)
cp .env.example .env
# Edit .env with your actual API key
npm start
# Option 2: Using Node's built-in env file support
node --env-file=.env dist/map-server.esm.js
# Option 3: Using environment variable directly
MAGICLANE_API_KEY=your_api_key npm startHTTP Server (for web and custom clients):
# Development mode (with auto-reload)
npm run dev:http
# Production mode (after build)
npm run start:httpFor complete HTTP server documentation including endpoints, JSON-RPC examples, and client integration, see the HTTP Server Setup Guide.
Configure your MCP client to connect to the Magic Lane server. Follow the detailed setup guide for your specific AI client:
Claude Desktop Setup Guide - Complete configuration instructions for Claude Desktop
Cursor AI Setup Guide - Step-by-step setup for Cursor IDE
VS Code Setup Guide - Integration guide for Visual Studio Code with GitHub Copilot
Each guide includes:
Client-specific configuration file locations
Multiple installation options (local build, NPM, Docker)
Platform-specific instructions (Windows, macOS, Linux)
Build and run the server using Docker:
# Build the Docker image
docker build -t magiclane-mcp-server .
# Run the container (pass API key via environment variable)
docker run --rm -e MAGICLANE_API_KEY=your_api_key magiclane-mcp-server
# Or use an env file
docker run --rm --env-file .env magiclane-mcp-serverEnvironment Variables:
Variable | Required | Description |
| Yes | Your Magic Lane API key for authentication |
| No | Set to |
| No | Timeout (in seconds) for outgoing Magic Lane API requests. Positive integer. Defaults to |
The container runs with --enable-source-maps for better stack traces in production.
The Magic Lane MCP Server provides several integrated geospatial tools that enable AI systems to search, plan, analyze, and visualize routes and locations.
Looking for rendered map images and live interactive map demos? See Visual Examples.
The Location Search Tool uses the Magic Lane Search REST API to find:
Coordinates, addresses, or administrative areas.
Points of Interest (POIs) around a reference location (restaurants, gas stations, pharmacies, etc.).
Parameter | Type | Default | Description |
| string | - | Free-text query (e.g., POI name, address, or city) |
| string | - | Result type: |
| array | - | POI category filters. Required when |
| object | - | Geographic context: |
| string |
| Response language (ISO 639-2 / ISO 639-3 language code) |
| number |
| Maximum number of results, ranked by relevance |
Urban Exploration & Tourism
"Search for authentic Italian restaurants in downtown Chicago within walking distance of Millennium Park."
"Where are the ATMs near Brandenburg Gate, Berlin?"
Business & Logistics
"Locate the closest 'DHL Service Point' near Berlin Central Station."
"Find all Starbucks locations within 1km of our office at 1 Market Street, San Francisco."
"Where are the parking garages near Amsterdam Central Station?"
Real Estate & Property
"Show all elementary schools near 456 Maple Avenue, Portland, Oregon with their exact distances from the property."
"Locate pharmacies, grocery stores, and public transport stops near the property at Baker Street 221B, London."
The Routing Planner Tool generates optimized routes between multiple points using the Magic Lane Routing REST API and the Magic Lane Fleet Management Rest API. This tool supports the following capabilities:
Point-to-point and multi-stop routing (A -> B -> C).
Inclusion of POIs (e.g., gas stations, restaurants).
Advanced VRP optimization for multi-delivery routes.
Traffic, restriction, and terrain considerations.
Multilingual route instructions.
Parameter | Type | Default | Description |
| string |
| Transport type ( |
| string |
| Optimization objective. |
| string | - | Start location (name or coordinates) |
| string | - | End location (name or coordinates) |
| array |
| List of stops between start and end. Order determines route generation. Each waypoint defines specific preferences and constraints |
| array |
| Elements to avoid ( |
| object |
| Vehicle characteristics including dimensions, weight, fuel type, EV parameters and profile preference. See Vehicle Specification for complete details. |
| string |
| Response detail level: |
| number |
| Number of routes (1-3 for car/truck/bike/pedestrian; 1-11 for public transport) |
| number |
| Bike / pedestrian terrain effort tolerance, 0.0 (easy) to 1.0 (strenuous) |
| boolean |
| Enable emergency-vehicle routing (relaxes certain traffic restrictions) |
| string |
| Turn-by-turn instruction language (ISO 639-2 / ISO 639-3 language code) |
Each entry in intermediate_waypoints represents one stop. The type discriminator determines the shape of waypoint and which fields apply:
Parameter | Type | Default | Description |
| string | - | Stop shape discriminator. One of: |
| object | - | Location data. Shape must match |
| number |
| Maximum perpendicular distance from the route polyline (in meters) to consider POI candidates. Applies only to |
| string |
| Placement hint for |
| number | - | Numeric placement hint. When |
International Travel & Tourism
"Generate a scenic bike route from Vienna to Bratislava, avoiding highways."
"Plan a road trip from Munich to Venice with stops at Innsbruck and Bolzano, optimized for scenic views."
Public Transit & Commuting
"Find a public transport route from London to Oxford with minimal transfers."
"What's the quickest way to get from JFK Airport to Manhattan using public transport?"
Multi-Stop Sightseeing & Events
"Create a walking tour from the Colosseum to the Trevi Fountain, stopping at the Pantheon and a gelato shop."
"I'm at the Eiffel Tower and need to visit Notre-Dame, Louvre Museum, and return to my hotel near Gare du Nord. Plan the best route by car."
Emergency & Priority Routing
"Find the fastest route from St. John Ambulance Station, Westminster to General Hospital, avoiding traffic and roadblocks."
"Calculate the quickest route for emergency services from Fire Station 23 to the reported incident at Pike Place Market."
Electric Vehicle Routing
"I'm driving a Tesla Model 3 with 60% battery from San Francisco to Los Angeles. Find the optimal route with necessary charging stops, ensuring I arrive with at least 20% charge."
"Calculate a route for my electric van (80 kWh battery, 250km range) from Berlin to Prague with fast-charging stops along the way."
The Isochrone Calculator Tool provides spatial analysis to determine all areas reachable from a reference point within specific travel time or distance constraints using the Magic Lane Isochrones REST API. This enables AI systems to analyze accessibility zones, service coverage areas, and reachability studies.
Key Features:
Calculate reachability polygons based on time or distance constraints
Support for multiple transport modes (walking, cycling, driving, public transport)
Departure location resolution through coordinates or geocoding
Multi-range analysis for complex accessibility studies
Parameter | Type | Default | Description |
| string |
| Transport mode ( |
| string |
| Cost model and units for |
| object | - | Origin point: |
| array | - | One or more thresholds. Seconds when |
| array |
| Elements to avoid ( |
| object |
| Vehicle characteristics including dimensions, weight, fuel type, EV parameters and profile preference. See Vehicle Specification for complete details. |
| string |
| Result language (ISO 639-2 / ISO 639-3 language code) |
"Where can I cycle to in 45 minutes from Amsterdam Central Station?"
"Display all areas within a 10-minute walk from Atlantic Avenue-Barclays Center Station in Brooklyn."
"Display the 1-hour driving catchment area from the proposed warehouse location in Frankfurt."
The Round Trip Planner Tool generates circular routes that start and end at the same location. This tool is perfect for creating exploration routes, cycling loops, jogging paths, and delivery runs.
Key Features:
Circular routes with guaranteed return to starting point
Time-based or distance-based route generation
Support for multiple transport modes (walking, cycling, driving)
Terrain and hill skip preferences for cyclists
Customizable route length and complexity
Parameter | Type | Default | Description |
| string |
| Transport mode ( |
| string |
| Optimization objective and units for |
| object | - | Loop start AND end point: |
| number | - | Target loop size. Seconds when |
| array |
| Elements to avoid ( |
| boolean |
| Include elevation/terrain profile in the response |
| number |
| Departure time as Unix epoch seconds; |
| string | - | Top-level sub-profile shortcut for bike ( |
| object |
| Vehicle characteristics including dimensions, weight, fuel type, EV parameters and profile preference. See Vehicle Specification for complete details. |
| number |
| Integer seed for reproducible loop generation |
| string |
| Response language (ISO 639-2 / ISO 639-3 language code) |
Fitness & Recreation
"Create a 10km jogging loop starting from Central Park."
"Design a 90-minute bike ride loop from Stephansplatz."
Tourism & Exploration
"Generate a 45-minute walking loop from the Eiffel Tower."
"Plan a 2-hour walking loop starting from Times Square."
Cycling Routes
"Create a 25km bike loop from Whistler Village, avoiding highways."
"Design a 1-hour cycling loop from Golden Gate Park using the shortest route."
The Reverse Geocoding Tool converts geographic coordinates or areas into detailed address information using the Magic Lane Reverse Geocoding REST API. This tool provides comprehensive address components for various spatial queries.
Key Features:
Point-to-address conversion for specific coordinates
Search around a point, within an area, or along a path
Returns multiple address results with distance ranking
Includes administrative hierarchy (settlement, city, county, state, country)
Identifies nearby points of interest
Parameter | Type | Default | Description |
| object | - | Specific coordinate point |
| object | - | Area definition: bounding box ( |
| object | - | Path definition (encoded polyline or coordinates) with |
| number |
| Maximum number of results to return |
| string |
| Result language (ISO 639-2 / ISO 639-3 language code) |
"What's the address at coordinates 51.5074, -0.1278?"
"Find all addresses within a 500-meter radius of the Brandenburg Gate."
The Geofence Manager Tool provides comprehensive geofence operations for defining and managing geographic boundaries, enabling location-based services and asset monitoring. This tool supports creating, retrieving, updating, deleting geofences, and checking if points fall within defined boundaries.
Key Features:
Create geofences with polygon, circle, or rectangle geometries
Query geofences by ID, within bounding boxes, or by proximity to a point
Update geofence properties (name, keywords)
Delete geofences by ID
Check if specific coordinates fall inside geofences
Support for custom metadata and tags
Create Operation - Create one or more geofences with the following parameters:
Parameter | Type | Default | Description |
| string | - | Custom identifier (auto-generated if not provided) |
| string | - | Human-readable name |
| array | [] | Tags for search and filtering |
| object | - | Additional custom metadata |
| string | - | Geometry type: |
| object | - | Area definition (polygon coordinates, circle center/radius, or bbox) |
Read Operation - Retrieve one or more geofences with the following parameters:
Parameter | Type | Default | Description |
| array | - | Array of geofence IDs to retrieve |
| object | - | Bounding box filter (north, south, east, west) |
| object | - | Search geofences near a point (reference_point, distance, limit) |
Update Operation - Modify properties of an existing geofence with the following parameters:
Parameter | Type | Default | Description |
| string | - | ID of geofence to update |
| string | - | Human-readable name to update the geofence |
| array | [] | Updated keywords/tags for geofence area |
Delete Operation - Remove one or more geofences with the following parameters:
Parameter | Type | Default | Description |
| array | - | Array of geofence IDs to delete |
Check Point Operation - Determine if coordinates fall within geofences with the following parameters:
Parameter | Type | Default | Description |
| array | - | Array of geofence IDs to check against |
| array | - | Array of locations to test; each entry uses |
Asset Monitoring & Tracking
"Create a circular geofence with 500m radius around our warehouse at 123 Main Street, Chicago."
"Is the delivery vehicle at coordinates 40.7589, -73.9851 inside of Main Street zone geofence?"
Restricted Area Management
"Create a rectangular 'construction-zone-1' geofence covering downtown Seattle bounded by these coordinates: north 47.6205, south 47.5990, east -122.3250, west -122.3450."
"Update the 'construction-zone-1' geofence to include 'temporary' and 'high-priority' keywords."
Service Area & Delivery Zones
"Create three circular delivery zone geofences: 'berlin-warehouse-1' at coordinates 13.3777, 52.5163 with 2km radius, 'berlin-warehouse-2' at 13.4050, 52.5200 with 1.5km radius, and 'berlin-warehouse-3' at 13.3888, 52.5170 with 2.5km radius."
"Show me all geofences within 2km of Brandenburg Gate at coordinates 13.3777, 52.5163."
"Retrieve all geofences with IDs: 'zone-premium-01', 'zone-premium-02', and 'zone-premium-03' that are tagged with 'premium-service'."
Location-Based Alerts
"Delete the temporary event geofences with IDs: 'summer-festival-2025-main', 'summer-festival-2025-parking', and 'summer-festival-2025-stage' now that the event is over."
"List all geofences within the bounding box covering Manhattan: north 40.8820, south 40.7006, east -73.9070, west -74.0479."
"Find all geofences near Times Square within 1000 meters and show their names and keywords."
The Renderer Tool generates static map images of calculated routes, isochrones, round trips, and custom map views using the Magic Lane rendering service. It delivers immediate visual context by overlaying geographic data on a map and returning the result as an embedded image.
Key Features:
Renders routes, isochrones, and round trips as PNG, JPEG, or WebP images
Automatically calculates the optimal viewport to frame all relevant data
Generates static map views centered on a location or bounded by custom coordinates
Delivers images directly to the MCP client as base64-encoded data; for routing, isochrone, and round_trip a JSON text block with the underlying route details accompanies the image, so no separate calculation call is needed
Parameter | Type | Default | Description |
| string | - | Visualization type: |
| string |
| Output image format: |
| object | - | Parameters matching the selected |
Route representation
"I'm at 10 Downing Street, London - please show a driving route to St Paul's Cathedral."
Round Trip representation
"Visualize a 5.5km jogging route starting from the Rijksmuseum in Amsterdam."
Isochrone representation
"Please display a map of Paris with a 15-minute walking isochrone."
Static Map representation
"Display a wide view of Miami, including beach and the Art Deco Historic District."
See Visual Examples for rendered output of these prompts.
The Interactive Map Tool renders MagicLane vector tiles in a fully interactive map directly inside the conversation using MapLibre GL JS and MCP Apps. Unlike the static renderer, users can pan, zoom, and explore the map widget without leaving the chat client.
Key Features:
Streams live vector tiles from MagicLane's global map service
Automatically fits the viewport to the displayed data: location, route, isochrone, round trip, search results, geofence areas, or a custom coordinate path
Draws one or many overlays on the same map (routes, isochrones, geofences, paths) - each shape in its own color
Supports pan and zoom interactions within MCP Apps-compatible clients
Parameter | Type | Default | Description |
| number |
| Map zoom level (0 = world view, 16 = street level). Ignored for |
| array | - | Overlays to draw (at least one entry). Each entry is an object |
Each overlayParameters entry has:
Field | Type | Description |
| string | Display mode: |
| object | Accepts the same parameters as the corresponding calculation tool, and must match this entry's |
Location View
"Show me an interactive map centered on the Eiffel Tower"
"Display an interactive map of downtown Tokyo."
Route Visualization
"Show an interactive map of the driving route from Amsterdam to Brussels."
"Display a bike route from Central Park to Brooklyn Bridge on an interactive map, including a stop to pharmacy."
Isochrone Overlay
"Show on an interactive map everywhere I can reach by car in 30 minutes from Berlin Central Station."
"Display a walking isochrone of 20 minutes from Trafalgar Square on an interactive map."
Round Trip
"Show a 10 km jogging loop from Vondelpark on an interactive map."
Search Results
"Show all coffee shops near the Louvre on an interactive map."
"Display restaurants within 1 km of Notre-Dame on an interactive map."
Custom Path
"Draw this GPS track on an interactive map: [[2.35, 48.85], [2.34, 48.86], [2.33, 48.87]]."
"Plot a line on an interactive map, label it 'Delivery run', using [[11.8793, 46.4372], [11.8694, 46.4329], [11.8597, 46.4339], [11.8504, 46.4341], [11.8406, 46.4187], [11.8378, 46.4149], [11.8437, 46.4103]] coordinates."
Browse runnable HTML demos for each
display_typein Visual Examples.
# Check if Node.js version is 22+
node --version
# Verify API key is set
echo $MAGICLANE_API_KEY
# Check for build errors
npm run buildEnsure your API key is valid and active in the Magic Lane Dashboard
Verify the environment variable is correctly set: MAGICLANE_API_KEY=your_key
Check for extra spaces or quotes in the API key
Verify your MCP client configuration matches the server path
Ensure the server is running before connecting the client
Check firewall settings if using remote connections
Magic Lane API has rate limits; check your dashboard for current usage
Implement request caching for frequently accessed routes
Consider upgrading your API plan if limits are exceeded
Unauthorized access (401): Invalid API key. Check your configuration.
No results found (404): The location could not be found. Try a different query.
Too many requests (429): Rate limit exceeded. Check your usage dashboard.
Bad request (400): Invalid parameters. Check your input format.
Magic Lane is committed to protecting your privacy and handling your data responsibly. For complete privacy information, see our full privacy policy: https://www.magiclane.com/web/terms-and-conditions#privacy
Query data: Location search terms, route origins/destinations, and coordinates submitted through the MCP server are transmitted to Magic Lane's API for processing. They are not stored or logged by Magic Lane after the response is delivered.
API key: Your API key is transmitted with every request solely for authentication and rate limiting. It is never shared with third parties.
No user profiling: Magic Lane does not build user profiles, track usage patterns across sessions, or correlate individual requests.
All requests are processed in real-time to generate the requested geospatial response (route, search result, isochrone, etc.).
Processed data is immediately discarded after the response is delivered.
Map rendering is performed dynamically; generated images are not retained after transmission.
Magic Lane does not persistently store the content of routing requests, location queries, search parameters, or reverse geocode inputs.
No session data or request history is retained on Magic Lane servers.
Magic Lane uses OpenStreetMap data and other publicly available geographic datasets
No personal or proprietary location data is shared with third parties
Traffic and routing data is aggregated and anonymized at the source
For detailed information, review our Terms of Service and Privacy Policy.
Documentation: developer.magiclane.com/docs
API Dashboard: developer.magiclane.com/api/dashboard
GitHub Issues: github.com/magiclane/magiclane-mcp-server/issues
Developer Portal Support: Contact support through the developer portal
Manage geofences and perform spatial queries for asset monitoring and location-based services.
Supports operations:
check_point: Test if locations are inside geofence(s) (uses CheckPointsInGeofencesSchema)
create: Define new geofence(s) with polygon, circle, or rectangle geometries (uses CreateGeofenceParametersSchema)
read: Retrieve geofences by IDs or within a bounding box (uses GetGeofencesParametersSchema)
update: Modify existing geofence properties (uses UpdateGeofenceParametersSchema)
delete: Remove geofence(s) by ID(s) (uses DeleteGeofenceParametersSchema)
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Geofence operation to perform. Exactly one of: "create": define new geofence(s); use CreateGeofenceParametersSchema. "read": fetch existing geofences by ID or area; use GetGeofencesParametersSchema. "update": modify metadata of an existing geofence; use UpdateGeofenceParametersSchema. "delete": remove geofence(s) by ID; use DeleteGeofenceParametersSchema. "check_point": test whether one or more points lie inside the given geofence(s); use CheckPointsInGeofencesSchema. | |
| parameters | No | Operation-specific parameters. MUST match `operation`: "create": CreateGeofenceParametersSchema; "read": GetGeofencesParametersSchema; "update": UpdateGeofenceParametersSchema; "delete": DeleteGeofenceParametersSchema; "check_point": CheckPointsInGeofencesSchema. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true) and not idempotent. The description adds operational details like 'delete' but does not elaborate on behavioral nuances (e.g., what happens on failure, rate limits, or side effects). It aligns with annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two introductory sentences followed by a clear bullet list of operations. It front-loads the core purpose and uses efficient, scannable formatting. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple operations, no output schema), the description is adequate but not exhaustive. It explains what the tool does and lists operations, but does not describe the return format or success/failure behavior. The rich input schema partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The description adds high-level operation names but no deeper semantic meaning beyond what the schema already 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?
The description clearly states the tool's purpose: managing geofences and performing spatial queries. It lists five specific operations (check_point, create, read, update, delete), each with a direct verb and resource. This distinguishes it from sibling tools like interactive_map or route_planner, which serve different functions.
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 usage through the listed operations, but it does not explicitly say when to use this tool versus alternatives. No comparison to siblings or exclusion criteria are provided. The agent must infer from the tool's name and operation list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Display an interactive map using MagicLane vector tiles and MapLibre GL JS directly in the conversation. Supports multiple display types: location view, route visualization with stops, isochrone reachability areas, round trip routes, and search result markers. The map supports pan, zoom, and click interactions.
| Name | Required | Description | Default |
|---|---|---|---|
| display_type | Yes | What to show on the interactive map. Exactly one of: "location": single point with optional label (default; use LocationDisplayParametersSchema). "routing": calculated route with origin/destination/stops (use RoutingParametersSchema). "isochrone": reachability polygon from a departure point (use IsochroneParametersSchema). "round_trip": circular loop from a departure point (use RoundTripParametersSchema). "search_results": POI/address search results as markers (use SearchParametersSchema). | |
| zoom | No | Initial map zoom level in [0, 16]. 0 = whole world, 8 = country, 12 = city (default), 14 = neighborhood, 16 = street. IGNORED when display_type is "routing", "isochrone", or "round_trip" - those auto-fit to data bounds. | |
| parameters | Yes | Parameters for the chosen `display_type`. Shape MUST match `display_type`: "location": LocationDisplayParametersSchema; "routing": RoutingParametersSchema; "isochrone": IsochroneParametersSchema; "round_trip": RoundTripParametersSchema; "search_results": SearchParametersSchema. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It only mentions interactivity (pan, zoom, click) but does not disclose read-only nature, data requirements, or any side effects. This is insufficient for an agent to understand system impact.
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 extremely concise with only two sentences that front-load the main purpose and capabilities. Every word adds value, making it efficient for agent comprehension.
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 high complexity (multiple display types, nested parameters) and no output schema, the description is insufficient. It does not explain return format, rendering behavior, or how results are presented to the user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already provides detailed parameter descriptions. The tool description adds minimal extra meaning beyond listing display types. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool displays an interactive map using specific technologies (MagicLane, MapLibre GL JS) and lists supported display types. However, it does not differentiate from sibling tool static_map_render, which also renders maps, causing potential ambiguity.
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 like route_planner, isochrone_calculator, or static_map_render. The description lacks when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate isochrone polygons (areas reachable within a certain time or distance) from a given starting point. Accepts either coordinates or a place/address name. If an address is provided, this tool will internally convert it to coordinates. Useful for finding reachable areas for driving, walking, or cycling.
| Name | Required | Description | Default |
|---|---|---|---|
| transport | No | Transport mode used to compute reachability. Exactly one of: "car" (default), "lorry"/"truck", "pedestrian", "bike", "public". | car |
| type | No | Cost model and units for the values in `ranges`. Exactly one of: "fastest" — `ranges` interpreted as SECONDS of travel time (default; valid for all transport modes). "shortest" — `ranges` interpreted as METERS of travel distance (valid for all transport modes). "economic" — energy-minimizing cost model; VALID ONLY for e-bikes (requires transport="bike" AND `vehicle.profile` set to a pedelec/spedelec sub-profile such as "city_pedelec"). Range units same as "fastest". Do NOT use for cars, trucks, regular bikes, or pedestrians. "scenic" — prefers scenic roads; valid for car, truck/lorry, and pedestrian. NOT valid for transport="bike". Range units same as "fastest". | fastest |
| departure | Yes | Origin point from which reachability is computed. Provide "coordinates" (longitude, latitude) when known, or "location" to resolve from a place/address. | |
| ranges | Yes | One or more range thresholds; each produces a separate isochrone polygon. UNITS depend on `type`: SECONDS when type="fastest"/"economic"/"scenic", METERS when type="shortest". Example: [600, 1800, 3600] with type="fastest": 10 min, 30 min, 60 min reachable areas. All values must be positive. | |
| avoid | No | Road features to exclude. Array of zero or more of: "highway", "toll", "ferry", "unpaved", "turnaround", "traffic", "roadblocks". Empty array (default) means avoid nothing. | |
| locale | No | ISO 639-2 / ISO 639-3 language code for any place names in the response. Default "en". | en |
| vehicle | No | Vehicle profile used to apply road restrictions and energy modelling to the reachability calculation. REQUIRED for transport="truck"/"lorry" (dimensions/weight to avoid restricted roads). REQUIRED for electric vehicles (set `vehicle.fuel="electric"` and `vehicle.ev` for range-aware isochrones). REQUIRED for bike with type="economic" — set `vehicle.profile` to a pedelec/spedelec eBike variant. OPTIONAL for car/regular-bike/pedestrian — defaults apply when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true (read-only) and openWorldHint=true (external data). The description adds value by noting that addresses are internally converted to coordinates, which is a behavioral detail not in annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. It front-loads the core purpose, then explains input flexibility, and ends with a use-case statement. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, nested objects, no output schema), the description is minimal. It does not explain output format (polygons) beyond the first sentence, nor provide usage tips for specific parameters like ranges or transport. However, the comprehensive schema descriptions partially compensate.
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% (all parameters have descriptions in the schema). The description mentions that the tool accepts coordinates or addresses, but this is already detailed in the schema. Thus, the description adds minimal 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 explicitly states that the tool generates isochrone polygons (areas reachable within a time or distance) from a starting point. It clearly distinguishes from siblings like route_planner (which provides point-to-point routes) by focusing on reachable areas.
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 usefulness for driving, walking, or cycling, implying the tool is for reachability analysis. However, it does not explicitly state when to use this tool versus alternatives (e.g., route_planner for routes, geofence_manager for boundaries) or when not to use it. No exclusions or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for locations, places, and points of interest by name or address to retrieve their geographic coordinates. Supports geocoding of place names, POIs, businesses, landmarks, and addresses with optional category filtering. Returns coordinates, formatted addresses, and metadata for matching locations.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Primary search query. REQUIRED. For target="pois": describe the POI (e.g. "gas station", "Italian restaurant", "Eiffel Tower"). For target="addresses": full or partial street address (e.g. "10 Downing Street"). For target="cities": city name (e.g. "Berlin"). | |
| target | Yes | Result type to return. One of: "pois" (Points of Interest: businesses, landmarks, services), "addresses" (street addresses and house numbers), "cities" (city, town, or settlement names). CRITICAL: when target="pois", you MUST also provide at least one entry in poi_categories. | |
| poi_categories | No | POI category filters. REQUIRED when target="pois"; ignored otherwise. Provide one or more values from this exact set: "gas_stations", "parking", "food&drink", "accommodation", "medical_services", "shopping" (shops, supermarkets, malls), "car_services", "public_transport", "education", "entertainment", "public_services", "geographic_area", "business", "sightseeing", "religious_places", "roadside", "sports", "uncategorized", "hydrants", "emergency_services_support", "civil_emergency_infrastructure". Pick the narrowest category that matches the user intent. | |
| reference_location | Yes | Geographic context that biases and ranks the search. REQUIRED. Provide coordinates (preferred, most accurate) and/or location_text (city/region/country). Results closer or more relevant to this anchor rank higher. | |
| locale | No | ISO 639-2 / ISO 639-3 language code for returned place names and address fields (e.g. "en", "de", "fr", "ja"). Default "en". | en |
| limit | No | Maximum number of results to return, ranked by relevance (best match first). Positive integer. Default 5. Use a smaller value (1-3) when you only need the top match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations (readOnlyHint, openWorldHint) by detailing the types of queries supported (place names, POIs, etc.), optional category filtering, and the nature of results (coordinates, addresses, metadata). It does not contradict annotations and provides useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the core action and then provide additional detail. Every sentence is meaningful, no redundancy, and the description is appropriately sized for 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?
Given the tool's moderate complexity (6 parameters, nested objects) and the absence of an output schema, the description adequately covers the main inputs and outputs. It mentions geocoding for various entity types and category filtering, but it does not explicitly mention the required parameters (text, target, reference_location) or the dependency between target and poi_categories, though these are detailed in the schema.
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 documents all parameters thoroughly. The description adds minimal extra meaning beyond stating 'supports geocoding of place names, POIs... with optional category filtering,' which slightly reinforces the text parameter's purpose but does not significantly enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for locations by name/address to retrieve coordinates, listing supported types (places, POIs, businesses, landmarks, addresses). It specifies an output of coordinates, formatted addresses, and metadata, which distinguishes it from sibling tools like reverse_geocode, but does not explicitly differentiate from other search tools like interactive_map.
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 forward geocoding and POI search but provides no explicit guidance on when to prefer this tool over alternatives like reverse_geocode or geofence_manager. No when-not-to-use or alternative references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert geographic coordinates to detailed address information (reverse geocoding). Supports single-point lookup, area-based search within a radius, and address lookup along a path or route. Requires at least one of: coordinates, insideArea, or along parameters.
| Name | Required | Description | Default |
|---|---|---|---|
| coordinates | No | Single point to reverse-geocode into an address. MOST COMMON mode. Provide EXACTLY one of `coordinates`, `insideArea`, or `along`. | |
| insideArea | No | Return addresses found INSIDE the given shape (bbox, circle, or polygon). Use for area-coverage queries (e.g. "list all addresses in this neighborhood"). Provide EXACTLY one of `coordinates`, `insideArea`, or `along`. | |
| along | No | Return addresses found ALONG a path within a given radius. Use for corridor queries (e.g. "addresses along this route"). Provide EXACTLY one of `coordinates`, `insideArea`, or `along`. | |
| limit | No | Maximum number of address results to return, ranked by relevance. Positive integer. Default 5. | |
| locale | No | ISO 639-2 / ISO 639-3 language code for returned address fields (e.g. "en", "de", "fr"). Default "en". | en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, indicating safety. The description adds the three modes and parameter requirement but does not disclose any additional behavioral traits like output size, rate limits, or potential errors. Given the annotations, the description provides some context but not 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?
The description is only two sentences, front-loaded with the core purpose, and contains no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, nested objects) and the detailed schema, the description covers the essential modes and requirements. It lacks some nuance (e.g., output description) but is sufficient for an agent with schema context. Could mention return type briefly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so each parameter is well-documented. The tool description adds high-level mode guidance but does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool converts geographic coordinates to address information, specifying three distinct modes (single-point, area, along path). This distinguishes it from sibling tools like location_search (forward geocoding) without needing explicit 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?
The description explicitly states the required parameter condition (at least one of coordinates, insideArea, along), guiding the agent on input requirements. However, it does not contrast with similar sibling tools (e.g., when to prefer reverse_geocode over location_search), missing an opportunity for clearer differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a circular round-trip route that starts and ends at the same location. Accepts a starting point as coordinates or place name, with a range parameter for time-based (seconds) or distance-based (meters) loop extent. Returns route geometry, distance, and duration for the circular route.
| Name | Required | Description | Default |
|---|---|---|---|
| transport | No | Transport mode for the round trip. Exactly one of: "car", "lorry"/"truck", "pedestrian", "bike" (default for leisure loops), "public". | car |
| type | No | Optimization objective and units for `range`. Exactly one of: "fastest" — `range` interpreted as SECONDS of travel time (default; valid for all transport modes). "shortest" — `range` interpreted as METERS of travel distance (valid for all transport modes). "economic" — energy-minimizing cost model; VALID ONLY for e-bikes (requires transport="bike" AND `vehicle.profile` set to a pedelec/spedelec sub-profile such as "city_pedelec"). Range units same as "fastest". Do NOT use for cars, trucks, regular bikes, or pedestrians. "scenic" — prefers scenic roads; valid for car, truck/lorry, and pedestrian. NOT valid for transport="bike". Range units same as "fastest". | fastest |
| departure | Yes | Start AND end point of the loop (round trips begin and end at the same location). Provide `coordinates` (longitude, latitude) when known, or `location` to resolve from a place/address. | |
| avoid | No | Road features to exclude. Array of zero or more of: "highway", "toll", "ferry", "unpaved", "turnaround", "traffic", "roadblocks". Empty array (default) means avoid nothing. | |
| number_of_routes | No | Number of distinct loop variants to return. Range: 1-3 for car/truck/bike/pedestrian; 1-11 for transport="public". Default 1. Use >1 to offer the user a few different loops of similar length. | |
| terrain | No | When true, include an elevation/terrain profile alongside the route geometry. Default false. Enable for hiking/cycling routes where elevation matters. | |
| range | Yes | Target size of the loop. Must be positive. UNITS depend on `type`: SECONDS when type="fastest"/"economic"/"scenic", METERS when type="shortest". Example: range=3600 with type="fastest" for 1-hour loop. | |
| random_seed | No | Integer seed for the route-generation randomizer. Use the same seed to reproduce a loop; change it to get a different loop with the same parameters. | |
| locale | No | ISO 639-2 / ISO 639-3 language code for place names in the response. Default "en". | en |
| departure_time | No | Departure time as a Unix epoch timestamp in SECONDS (not milliseconds). Pass 0 (default) to use the server-side current time. Used for traffic-aware and time-dependent routing. | |
| profile | No | Detailed sub-profile for bike/pedestrian modes. For transport="bike": "city" (default), "road", "cross", "mountain". For e-bikes append "_pedelec" (≤25 km/h) or "_spedelec" (≤45 km/h). For transport="pedestrian": "walk" (default) or "hike". Ignored for car/truck/public. Shortcut for `vehicle.profile`; if both are set, `vehicle.profile` takes precedence. | city |
| vehicle | No | Vehicle profile used to apply road restrictions and energy modelling to the loop. REQUIRED for transport="truck"/"lorry" (dimensions/weight to avoid restricted roads). REQUIRED for electric vehicles (set `vehicle.fuel="electric"` and `vehicle.ev` for range-aware loops). REQUIRED for bike with type="economic" — set `vehicle.profile` to a pedelec/spedelec eBike variant. OPTIONAL for car/regular-bike/pedestrian — defaults apply when omitted. When `vehicle.profile` is set it overrides the top-level `profile` field. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and openWorldHint=true, so the description need not repeat. It adds behavior: accepts coordinates or place name, range parameter, returns geometry/distance/duration. No contradictions; 'Generate' aligns with read-only computation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no wasted words. Efficiently summarizes key aspects 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 complex parameters and nested objects, the description provides a sufficient high-level summary. It mentions return values (geometry, distance, duration) despite no output schema. Could be slightly more detailed but schema covers individual parameters.
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 3. The description adds high-level context (starting point, range units) but does not provide deep semantics beyond the schema's already thorough descriptions. Appropriate for the coverage level.
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 a circular round-trip route starting and ending at same location, with specific verb 'Generate' and resource 'route'. It distinguishes from siblings like route_planner (point-to-point) and isochrone_calculator (area) by emphasizing the loop nature.
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 generating round trips but does not explicitly state when to use or not use this tool versus alternatives like route_planner for point-to-point. No exclusion or context for when other tools are better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate optimized routes between two or more locations for car, bicycle, or pedestrian transport modes. Supports multi-stop routing with automatic waypoint resolution from place names or coordinates. Returns turn-by-turn instructions, distance, duration, and route geometry.
| Name | Required | Description | Default |
|---|---|---|---|
| transport | No | Transport mode used to compute the route. Exactly one of: "car" (passenger car, default; supports type="fastest"|"shortest"|"scenic"), "lorry" or "truck" (heavy goods vehicle — set the `vehicle` field with dimensions/weight; supports type="fastest"|"shortest"|"scenic"), "pedestrian" (walking; supports type="fastest"|"shortest"|"scenic"), "bike" (bicycle — use `fitness_factor` and `vehicle.profile`; supports type="fastest"|"shortest"; type="economic" REQUIRES an eBike `vehicle.profile` (pedelec/spedelec variant); type="scenic" is NOT supported), "public" (public transport: bus/train/tram; supports type="fastest"|"shortest"). | car |
| type | No | Route optimization objective. Exactly one of: "fastest" (minimize travel time, default; valid for all transport modes). "shortest" (minimize distance; valid for all transport modes). "economic" (minimize energy use; VALID ONLY for e-bikes — requires transport="bike" AND `vehicle.profile` set to one of the eBike sub-profiles: "road_pedelec", "cross_pedelec", "city_pedelec", "mountain_pedelec" (or the "_spedelec" 45 km/h variants). Do NOT use for cars, trucks, regular bikes, or pedestrians). "scenic" (prefer scenic roads at the cost of travel time; valid for car, truck/lorry, and pedestrian. NOT valid for transport="bike" — bicycle routing has no scenic cost model. Use "fastest" for bikes and tune `fitness_factor`/`vehicle.profile` instead). | fastest |
| origin | Yes | Route start point. Provide `coordinates` (longitude, latitude) when known - preferred for accuracy. Otherwise provide `location` to resolve the start from a place name or address. | |
| destination | Yes | Route end point. Provide `coordinates` (longitude, latitude) when known - preferred for accuracy. Otherwise provide `location` to resolve the end from a place name or address. | |
| avoid | No | Road features to exclude from the route. Array of zero or more of: "highway" (motorways), "toll" (toll roads), "ferry", "unpaved" (dirt/gravel), "turnaround" (U-turns), "traffic" (heavy-traffic segments), "roadblocks" (closures). Empty array (default) means avoid nothing. Adding entries may significantly increase travel time or fail to find a route. | |
| details | No | Response verbosity. Exactly one of: "full": geometry + turn-by-turn instructions (default; use when guiding the user). "path": geometry only, no instructions (use for map rendering). "timedistance": only total time and distance (smallest response; use for ETAs). | full |
| number_of_routes | No | Number of route alternatives to return, including the recommended primary route. Range: 1-3 for car/truck/bike/pedestrian; 1-11 for transport="public". Default 1. Use >1 only when the user explicitly wants alternatives. | |
| fitness_factor | No | Effort tolerance for bike and pedestrian routing, in [0.0, 1.0]. 0.0 = avoid steep climbs and long routes (low fitness); 1.0 = accept steep/hard terrain (high fitness). Default 0.5. Ignored for car/truck/public. | |
| intermediate_waypoints | No | Ordered list of stops between origin and destination, excluding origin and destination themselves. Order in the array defines visit order for fixed stops. Each entry has a `type` discriminator - see RoutingStopParametersSchema for the per-type rules ("coordinates", "address", "reference_poi", or "along_route_poi"). Default empty array (no intermediate stops). | |
| emergency | No | Enable emergency-vehicle routing. When true, the engine relaxes certain traffic restrictions (e.g. one-way streets, restricted zones) that apply to emergency services. Default false. Set to true ONLY for ambulance/fire/police use cases. | |
| locale | No | ISO 639-2 / ISO 639-3 language code for turn-by-turn instruction text (e.g. "en", "de", "fr", "es"). Default "en". Does not affect routing, only instruction language. | en |
| vehicle | No | Vehicle profile used for restrictions and energy modelling. REQUIRED for transport="truck"/"lorry" (dimensions/weight to avoid restricted roads). REQUIRED for electric vehicles (set `vehicle.fuel="electric"` and `vehicle.ev` for charging-aware routing). OPTIONAL for car/bike/pedestrian - defaults apply if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond annotations, such as returning turn-by-turn instructions and supporting multi-stop routing. It is consistent with readOnlyHint and openWorldHint, providing useful context without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words: first introduces core function, second adds key features. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits public and lorry/truck transport modes listed in the schema, and does not explain return format in absence of output schema. While it covers basic use cases, gaps reduce completeness for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds little parameter meaning beyond summarizing key capabilities (e.g., automatic waypoint resolution). Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates optimized routes between two or more locations for specific transport modes, and lists key outputs (turn-by-turn instructions, distance, duration, route geometry). It distinguishes from sibling tools like location_search and static_map_render by focusing on routing.
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 vs. alternatives like round_trip or isochrone_calculator. Does not mention when not to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render visual map images of routes, isochrones, round-trips, and static locations. Supports route rendering with automatic calculation, pre-calculated path overlays, area views, and location-centered maps. Returns a PNG image of the rendered map.
| Name | Required | Description | Default |
|---|---|---|---|
| render_type | Yes | What to render on the map. Exactly one of: "routing": a calculated route path between waypoints (use RoutingParametersSchema). "isochrone": reachability polygon(s) from an origin within time/distance limits (use IsochroneParametersSchema). "round_trip": a circular loop starting and ending at the same point (use RoundTripParametersSchema). "map_location": a static basemap centered on an area or fit to a bounding box (use SimpleMapParametersSchema). | |
| output_format | Yes | Output image format as a full MIME type. Exactly one of: "image/png" (default; lossless, supports transparency, best for diagrams/markers), "image/jpeg" (lossy; smallest file size; NO transparency), "image/webp" (modern; good compression; supports transparency). | |
| parameters | Yes | Parameters for the selected `render_type`. The shape MUST match `render_type`: "routing": RoutingParametersSchema; "isochrone": IsochroneParametersSchema; "round_trip": RoundTripParametersSchema; "map_location": SimpleMapParametersSchema. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description carries a reduced burden. It adds the behavioral detail that the tool returns a PNG image, which is beyond the annotations. No contradictions; the description is consistent with the read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, and every sentence earns its place. No redundant or extraneous 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?
While the schema is rich, the description does not explicitly mention the output_format parameter or the need to match parameters with render_type. However, with full schema coverage, the description adequately covers the high-level mapping capabilities. It lacks mention of the output format details beyond PNG.
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 the input schema providing extensive explanations for each parameter. The tool description itself does not add new parameter meaning beyond summarizing the render types. Baseline 3 is appropriate as the schema already handles parameter semantics.
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 renders visual map images of routes, isochrones, round-trips, and static locations, and returns a PNG image. This verb+resource combination immediately distinguishes it from sibling tools like interactive_map (interactive) or isochrone_calculator (data 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 guidance is provided on when to use this tool versus alternatives. The description does not mention any exclusions, prerequisites, or comparisons to sibling tools such as route_planner or round_trip, which might be more appropriate for pure calculation without rendering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tools generally target different aspects, but geofence_manager's interactive_map overlaps with static_map_render, and isochrone_calculator's results can be rendered by static_map_render. route_planner and round_trip both produce routes, though round_trip is a specific type. These overlaps create moderate ambiguity.
Tool names follow no consistent pattern: geofence_manager (noun_noun), isochrone_calculator (noun_noun), location_search (noun_noun), reverse_geocode (verb_noun), round_trip (adj_noun), route_planner (noun_noun), static_map_render (adj_noun_noun). Mixed conventions with no discernible verb_noun or noun_verb pattern.
8 tools is reasonable for a location services MCP server. Each tool covers a distinct domain area (geocoding, routing, geofences, etc.), and the count is not excessive or insufficient.
Covers core location operations: geocoding, reverse geocoding, routing (multi-stop, round-trip), isochrones, geofence management, and map rendering. However, lacks batch operations, elevation data, or traffic-aware routing, and the bundling of interactive map within geofence_manager is a design quirk that creates a minor gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Maps built for agents: routing incl. truck/ADR, geocoding, matrices, isochrones — 34 tools.
Geospatial intelligence with Mapbox APIs like geocoding, POI search, directions, isochrones, etc.
Geolocate Me turns your phone into location context for any AI assistant. Install the iOS or Android app, connect once with OAuth, and your GPS is queryable in natural language. Ask where you are, where you parked, where you were yesterday at 3pm, or how long you were at the office — the assistant calls the tool and answers with a real street address. https://geolocateme.app
Provides AI assistants with direct access to Mapbox developer APIs and documentation.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/magiclane/magiclane-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server