Click on "Deploy 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., "@JustRouting MCP How long is the drive from Marina Bay Sands to Changi Airport?"
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.
Routing, geocoding, distance matrices, and vehicle routing for AI assistants — focused on Southeast Asia.
JustRouting MCP lets MCP-compatible AI assistants such as Claude and Cursor use JustRouting for road routing, geocoding, distance and travel-time comparison, and multi-vehicle route optimization.
Designed for Southeast Asia.
curl -fsSL https://raw.githubusercontent.com/justrouting/mcp/main/install.sh | shThe installer downloads the latest prebuilt binary for your platform and installs justrouting-mcp.
No Go installation is required.
go install github.com/justrouting/mcp/cmd/justrouting-mcp@latestMake sure justrouting-mcp is available in your PATH.
Get an API key from JustRouting, then set:
export JUSTROUTING_API_KEY="your-api-key"Add the following MCP server configuration:
{
"mcpServers": {
"justrouting": {
"command": "justrouting-mcp",
"env": {
"JUSTROUTING_API_KEY": "your-api-key"
}
}
}
}The server communicates with MCP clients through stdio.
Related MCP server: ThinAir Geo
Tool | Purpose |
| Place or address → coordinates |
| Calculate one route |
| Compare travel times or distances between multiple locations |
| Assign jobs to vehicles and order their stops |
The tools are intentionally separated by task:
route = calculate table = compare optimize = decide
geocodeSearch for a place or address and convert it into coordinates.
Use it when the user provides:
a place name
a landmark
a business
a street address
another location description
Do not use it when the user already provides coordinates.
{
"name": "Marina Bay Sands",
"housenumber": "10",
"street": "Bayfront Avenue",
"postcode": "018956",
"city": "Singapore",
"country": "Singapore"
}The available fields are:
name — place, landmark, or business name
housenumber — house or building number
street — street name
postcode — postal or ZIP code
city — city or locality
country — country
limit — maximum number of results, up to 10
filters — optional search filters
Only provide fields that can be determined from the user's request. Do not invent missing address components.
Country and city can be useful for disambiguating common or abbreviated place names.
{
"results": [
{
"longitude": 103.859,
"latitude": 1.2834,
"coordinates": "103.859,1.2834",
"formatted": "Marina Bay Sands, 10 Bayfront Avenue, 018956, Singapore",
"place_id": "51667b3e...",
"country_code": "sg",
"result_type": "building"
}
]
}Results are ordered by relevance.
By default, the best matching result is returned. When multiple results are requested, choose the result that best matches the user's intended location.
The coordinates value is in longitude,latitude format and can be passed directly to route, table, or optimize.
If geocoding is used as part of a routing workflow, verify that the selected result matches the intended place before using its coordinates.
routeCalculate a driving route between two locations.
Use it when the user needs to:
calculate driving distance
estimate travel time
get a route between two locations
get route geometry
understand which roads a route uses
avoid specific road types
{
"origin": "103.8198,1.3521",
"destination": "103.9915,1.3644"
}Coordinates must use:
longitude,latitudeFor example:
103.8198,1.3521Optional motorcycle routing:
{
"origin": "103.8198,1.3521",
"destination": "103.9915,1.3644",
"profile": "motorcycle"
}Use profile: "motorcycle" when the user explicitly asks for a motorcycle or motorbike route.
Otherwise, omit profile to use the default driving profile.
Use exclude when the user explicitly asks to avoid a type of road.
Supported values:
toll
motorway
ferry
Example:
{
"origin": "103.8198,1.3521",
"destination": "103.9915,1.3644",
"exclude": ["toll"]
}Road avoidance is a preference, not a guarantee. The routing engine avoids the specified road type when a reasonable alternative exists.
{
"distance_meters": 18500,
"duration_seconds": 1500,
"profile": "driving",
"origin": {
"input": "103.8198,1.3521",
"snapped": [103.8197, 1.3520],
"name": "Example Road",
"distance": 4.2
},
"destination": {
"input": "103.9915,1.3644",
"snapped": [103.9915, 1.3644],
"name": "Airport Boulevard",
"distance": 8.1
},
"geometry": "ka|`@_ceeEnAqB...",
"summary": {
"roads": ["East Coast Parkway"],
"tolls": false,
"ferry": false
}
}distance_meters is the route distance in meters.
duration_seconds is the estimated travel duration in seconds.
geometry is a simplified encoded polyline that can be used to render the route on a map.
summary.roads lists the main roads used by the route.
summary.tolls indicates whether the route uses toll roads.
summary.ferry indicates whether the route includes a ferry crossing.
If the user provides place names or addresses instead of coordinates, call geocode first.
tableCalculate a distance and/or travel-time matrix between multiple locations.
Use it when the user needs to:
find the nearest driver, vehicle, store, or facility
compare several destinations
compare multiple origin-destination pairs
build a distance or travel-time matrix
Do not use it for a single route between two locations. Use route instead.
{
"coordinates": [
"103.8391,1.2771",
"103.8590,1.2834",
"103.7986,1.2885"
],
"annotations": ["distance"]
}Each coordinate has a stable zero-based index based on its position in the coordinates list.
Matrix rows correspond to sources.
Matrix columns correspond to destinations.
A matrix value at:
[row][column]represents the route from that source to that destination.
For example:
durations[0][2]is the travel time from source index 0 to destination index 2.
The sources and destinations returned by the tool contain the original coordinate indices so the matrix can be mapped back to the user's locations.
For a question such as:
Which driver is closest to this customer?
Put the customer first:
coordinates[0] = customer
coordinates[1] = driver A
coordinates[2] = driver B
coordinates[3] = driver CThen use the customer as the source and the drivers as destinations.
Read the corresponding matrix row and choose the smallest non-null distance or duration.
source and destinations can restrict the matrix to specific coordinate indices.
For example:
{
"coordinates": [
"103.8391,1.2771",
"103.8590,1.2834",
"103.7986,1.2885"
],
"sources": [0],
"destinations": [1, 2]
}This calculates routes from coordinate 0 to coordinates 1 and 2.
Use:
"annotations": ["duration"]for travel times.
Use:
"annotations": ["distance"]for distances.
Use:
"annotations": ["duration", "distance"]for both.
If omitted, both are returned.
{
"code": "Ok",
"durations": [
[0, 1860, null],
[1850, 0, 2100],
[null, 2110, 0]
],
"distances": [
[0, 14200, null],
[14100, 0, 18400],
[null, 18200, 0]
],
"sources": [
{
"index": 0,
"name": "Duxton Road",
"location": [103.8391, 1.2771],
"distance": 12.3
}
],
"destinations": [
{
"index": 1,
"name": "Bayfront Avenue",
"location": [103.8590, 1.2834],
"distance": 8.4
}
]
}durations are in seconds.
distances are in meters.
A matrix value of null means that the origin-destination pair is unreachable. Never interpret null as zero.
optimizeAssign jobs to vehicles and determine the order in which each vehicle should visit its assigned jobs.
Use it when the user needs to:
assign multiple deliveries or pickups to vehicles
plan routes for a fleet
determine the order of multiple stops
optimize a multi-vehicle routing solution
Do not use it for a single route. Use route.
Do not use it only to compare distances between locations. Use table.
{
"vehicles": [
{
"id": 1,
"start": "103.7923,1.3246",
"end": "103.7923,1.3246"
},
{
"id": 2,
"start": "103.8232,1.3241",
"end": "103.8232,1.3241"
}
],
"jobs": [
{
"id": 1,
"location": "103.7975,1.3104"
},
{
"id": 2,
"location": "103.7843,1.3149"
},
{
"id": 3,
"location": "103.7976,1.3198"
}
]
}Each vehicle must have at least a start or an end.
For a round trip, set both to the same location:
{
"id": 1,
"start": "103.7923,1.3246",
"end": "103.7923,1.3246"
}If start or end is omitted, the vehicle may start or end anywhere.
Each vehicle and job must have a unique id.
Locations must use:
longitude,latitudeEach vehicle can use its own routing profile.
For example:
{
"id": 1,
"profile": "motorcycle",
"start": "103.7923,1.3246",
"end": "103.7923,1.3246"
}Use "motorcycle" when the user explicitly asks for a motorcycle or motorbike route.
Otherwise, omit profile to use the default driving profile.
A simplified result looks like:
{
"summary": {
"cost": 2733,
"routes": 2,
"unassigned": 0,
"duration": 2733
},
"routes": [
{
"vehicle": 1,
"cost": 1144,
"duration": 1144,
"steps": [
{
"type": "start",
"location": [103.7923, 1.3246],
"arrival": 0
},
{
"type": "job",
"job": 2,
"location": [103.7843, 1.3149],
"arrival": 269,
"duration": 269
},
{
"type": "job",
"job": 1,
"location": [103.7975, 1.3104],
"arrival": 673,
"duration": 673
},
{
"type": "end",
"location": [103.7923, 1.3246],
"arrival": 1144,
"duration": 1144
}
]
}
],
"unassigned": []
}Read each route's steps in order to determine:
which vehicle serves each job
the order in which jobs are visited
when each job is reached
Always check unassigned.
Do not assume that every job can be assigned to a vehicle.
If the user provides place names or addresses instead of coordinates, call geocode first for every location and use the selected coordinates in the optimization request.
JustRouting MCP is designed so that AI assistants can combine the tools into larger workflows.
For:
How long does it take to drive from Marina Bay Sands to Changi Airport?
The workflow is:
geocode → geocode → routeGeocode the origin.
Geocode the destination.
Pass the resulting coordinates to route.
If the user already provides coordinates, skip geocoding.
For:
Which driver is closest to the customer?
The workflow is:
geocode × N → tableGeocode the customer.
Geocode each driver.
Keep the locations in a fixed order.
Use the customer as the source.
Use the drivers as destinations.
Compare the returned distances or durations.
For:
I have two vans and six customers. Assign the customers to the vans and determine the stop order.
The workflow is:
geocode × N → optimizeGeocode each vehicle's start/end location.
Geocode every job location.
Create one vehicle entry per vehicle.
Create one job entry per customer.
Call optimize.
Read routes[].steps to determine each vehicle's itinerary.
Check unassigned for jobs that could not be served.
All routing tools use:
longitude,latitudeFor example:
103.8198,1.3521This is:
longitude = 103.8198
latitude = 1.3521Do not reverse the order.
Add JustRouting MCP to your Claude MCP configuration:
{
"mcpServers": {
"justrouting": {
"command": "justrouting-mcp",
"env": {
"JUSTROUTING_API_KEY": "your-api-key"
}
}
}
}Once connected, Claude can use the JustRouting tools directly.
Add JustRouting MCP to your Cursor MCP configuration:
{
"mcpServers": {
"justrouting": {
"command": "justrouting-mcp",
"env": {
"JUSTROUTING_API_KEY": "your-api-key"
}
}
}
}Once connected, Cursor can use the JustRouting tools directly.
For prebuilt binaries:
A JustRouting API key
For installation from source:
Go 1.25+
The MCP server currently uses stdio transport.
Clone the repository:
git clone https://github.com/justrouting/mcp.git
cd mcpInstall dependencies:
go mod downloadRun tests:
go test ./...Build:
go build -o justrouting-mcp ./cmd/justrouting-mcpRun:
JUSTROUTING_API_KEY="YOUR-API-KEY" ./justrouting-mcp┌─────────────────────────────┐
│ MCP Client │
│ Claude / Cursor / AI │
└──────────────┬──────────────┘
│
│ MCP / stdio
▼
┌─────────────────────────────┐
│ justrouting-mcp │
│ │
│ geocode route │
│ table optimize │
└──────────────┬──────────────┘
│
│ Official Go Client
▼
┌─────────────────────────────┐
│ api.justrouting.tech │
└─────────────────────────────┘The MCP server is intentionally thin.
It exposes JustRouting capabilities through MCP and uses the official JustRouting Go client for API communication.
Prebuilt binaries are published through GitHub Releases.
To create a release:
git tag v0.1.0
git push origin v0.1.0GitHub Actions builds the binaries and publishes the release.
The one-line installer always installs the latest release.
The core routing capabilities are already available:
Route calculation
Geocoding
Distance and travel-time matrix
Vehicle routing optimization
Future improvements may include:
Alternative routes
Waypoints
Streamable HTTP transport
Remote MCP deployment
Search for a place or address and convert it into coordinates using JustRouting.
Use this tool when the user provides a place name, landmark, business, street address, or other location description instead of coordinates.
Do not use this tool when the user already provides coordinates in longitude,latitude format.
Parse the user's location into the structured fields that can be determined:
"name": place, landmark, or business name
"housenumber": house or building number
"street": street name
"postcode": postal or ZIP code
"city": city or locality
"country": country
Only provide fields that are known from the user's request. Do not invent or guess missing address components.
For example, "Marina Bay Sands, 10 Bayfront Avenue, Singapore 018956" can be represented as:
name: "Marina Bay Sands"
housenumber: "10"
street: "Bayfront Avenue"
postcode: "018956"
city: "Singapore"
country: "Singapore"
When the user's context provides a country or city, include it to disambiguate common, abbreviated, or misspelled place names.
Results are ordered by relevance. Each result contains longitude, latitude, and a "coordinates" string in longitude,latitude format that can be passed directly to the route, table, or optimize tools.
By default, only the best matching result is returned. If the location is ambiguous or the user asks for alternatives, request multiple results using "limit" and use the result that best matches the user's intended location.
When using geocode as part of a route, table, or optimize workflow, verify that the selected result matches the user's intended place before passing its coordinates to the next tool.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | city or locality, for example "Singapore" | |
| name | No | name of the place, for example "Marina Bay Sands" or "marina bay" | |
| limit | No | maximum number of results to return; defaults to 1 (best match only), must not exceed 10 | |
| street | No | street name, for example "Bayfront Avenue" | |
| country | No | country, for example "Singapore" | |
| filters | No | optional filters to restrict results, for example "countrycode:sg" | |
| postcode | No | postal code, for example "018956" | |
| housenumber | No | house or building number, for example "10" |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it discloses relevance ordering, a default of one result, the max limit of 10, the output coordinate string format, and a verification step before passing coordinates downstream. It omits auth/permission requirements and error behavior, but the operational traits that matter for calling it are covered.
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?
Front-loaded with purpose, then usage, then field parsing and an example. It is somewhat long and the field bullet list partially restates schema documentation, but each section adds routing or parsing value rather than 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?
An output schema exists, so return values need not be fully explained, and the description still summarizes them (longitude, latitude, coordinates string). For an 8-parameter, zero-required geocoding tool, the guidance on parsing, disambiguation, and limits is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3. The description goes beyond it by showing how to decompose free-form user input into name/housenumber/street/postcode/city/country, warning not to invent missing components, and explaining when to include city/country for disambiguation and when to use limit.
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?
States a specific verb (search/convert) and resource (place or address into coordinates), and the mechanism (JustRouting). It is clearly distinguishable from the coordinate-consuming siblings route, table, and optimize.
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?
Gives explicit use conditions (user provides a place name, landmark, business, street address) and an explicit exclusion (do not use when the user already provides longitude,latitude). It also states the correct next step when part of a route/table/optimize workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Solve a vehicle routing problem using JustRouting: assign jobs to vehicles and determine the order in which each vehicle should visit its assigned jobs.
Use this tool when the user needs to:
assign multiple deliveries, pickups, or visits to one or more vehicles
determine the order in which each vehicle should visit its assigned jobs
plan routes for a fleet of vehicles
optimize the overall routing solution
Do not use this tool for:
calculating a single route between two locations; use the route tool
comparing travel times or distances between multiple locations; use the table tool
The input consists of:
"vehicles": the available vehicles, each with a unique "id" and optional start, end, and routing profile
"jobs": the locations that need to be served, each with a unique "id"
Locations:
All locations must use longitude,latitude format.
For example: "103.8198,1.3521"
A vehicle may have only a start, only an end, or both.
For a round trip, set both the vehicle's start and end to the same location.
If start or end is omitted, the vehicle may start or end anywhere.
Each vehicle must have at least a start or an end location.
If the user provides place names or addresses instead of coordinates, do not guess their coordinates. Call the geocode tool first for every location, then pass each place's best geocoded coordinates to this tool.
Vehicle profiles:
Each vehicle can use its own routing profile.
Set profile to "motorcycle" when the user explicitly asks for a motorcycle or motorbike route.
Otherwise, omit profile to use the default driving profile.
The result contains:
"routes": one itinerary for each vehicle used. Read each route's "steps" in order to determine which jobs are assigned to that vehicle and the order in which they are visited.
"unassigned": jobs that could not be served by any vehicle.
"summary": aggregate cost, duration, waiting time, and distance across the solution.
A "job" step contains the job id, arrival time, travel duration, and travel distance for reaching that job. Use these fields when explaining the planned schedule to the user.
Do not assume that every job will be assigned. Always check "unassigned" and mention any jobs that could not be served.
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | Yes | the tasks to assign; at least 1 job required | |
| vehicles | Yes | the available fleet; at least 1 vehicle required; each vehicle needs a start or an end |
| Name | Required | Description |
|---|---|---|
| routes | Yes | one itinerary per vehicle that was used |
| summary | Yes | aggregate cost and time across all routes |
| unassigned | Yes | jobs that no vehicle could serve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden and does well: it states the default driving profile vs. motorcycle, the coordinate-only input requirement with a mandatory geocode pre-step, and the meaning of the result sections including the warning to always check 'unassigned'. It stops short of disclosing operational traits such as latency, cost, request limits, or error behavior for a solver of this kind.
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?
Purpose and the when/when-not routing are front-loaded, and the bulleted sections are scannable. It is on the long side and repeats input rules already carried by the schema, which is the only thing keeping it from a 5.
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 moderately complex solver with a full input schema and an output schema, the description covers everything an agent needs: input shape, coordinate format, profile defaults, geocoding prerequisite, and how to interpret the response including unassigned jobs. No material gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents id, location, start, end, and profile. The description's location and vehicle rules (round trip via identical start/end, omitting to allow anywhere, each vehicle needing a start or end) largely restate the schema rather than adding new semantics, so it sits at the baseline 3.
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 opens with a specific verb+resource: 'Solve a vehicle routing problem ... assign jobs to vehicles and determine the order in which each vehicle should visit its assigned jobs.' It is unmistakably distinct from the route and table siblings, which it names explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit 'Use this tool when' list (multi-vehicle assignment, ordering, fleet planning) and an explicit 'Do not use this tool for' list that routes the agent to the route and table tools for single-route and comparison tasks. When/when-not/alternatives are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate a driving route between two locations using JustRouting.
Use this tool when the user needs to:
calculate driving distance or travel time between two locations
get a route between two locations
get the route geometry or road information
avoid specific road types such as toll roads, motorways, or ferries
Do not use this tool for:
comparing travel times or distances between many origin-destination pairs; use the table tool
assigning multiple jobs to vehicles or determining the order of multiple stops; use the optimize tool
Input locations:
origin and destination must be coordinates in longitude,latitude format.
If the user provides a place name or address, do not guess its coordinates.
Call the geocode tool first, then use the coordinates from its best result as the input to this tool.
If the user already provides coordinates, call this tool directly without using geocode.
Routing profile:
The default profile is driving.
Set profile to "motorcycle" when the user explicitly asks for a motorcycle or motorbike route.
Otherwise, omit profile.
Road avoidance:
Use exclude when the user explicitly asks to avoid a type of road.
Supported values are "toll", "motorway", and "ferry".
For example, use ["toll"] when the user asks for a route that avoids toll roads.
Avoidance is a preference, not a guarantee: the engine will avoid the specified road type when a reasonable alternative exists.
Coordinates must be in longitude,latitude order. For example: 103.8198,1.3521.
| Name | Required | Description | Default |
|---|---|---|---|
| origin | Yes | origin coordinates in longitude,latitude format | |
| exclude | No | road classes to avoid, for example ["toll"] when the user asks to avoid toll roads | |
| profile | No | routing profile: set to "motorcycle" when the user's request mentions a motorcycle or motorbike; otherwise omit it for the default driving profile | |
| destination | Yes | destination coordinates in longitude,latitude format |
| Name | Required | Description |
|---|---|---|
| origin | Yes | the origin as the routing engine used it: the requested coordinate plus where it snapped to the road network |
| exclude | No | the road classes the route avoids; omitted when none were requested |
| profile | Yes | routing profile used: "driving" or "motorcycle" |
| summary | Yes | high-level description of the route |
| geometry | No | the route's shape as an encoded polyline (simplified overview); omitted when the engine returned none |
| destination | Yes | the destination as the routing engine used it: the requested coordinate plus where it snapped to the road network |
| distance_meters | Yes | route length in meters |
| duration_seconds | Yes | estimated travel time in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and largely does so: it discloses the default driving profile, when to switch to motorcycle, and that road avoidance is a preference rather than a guarantee. It also states the geocode prerequisite and the mandatory coordinate order/format. It does not mention rate limits or error behavior, leaving a small gap.
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?
Purpose is front-loaded and the bulleted when/when-not structure is easy to scan. It is slightly long and repeats the longitude,latitude ordering rule twice (in 'Input locations' and again at the end), which is minor waste rather than padding.
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?
An output schema exists, so return values need no explanation, and the description covers everything else an agent needs: prerequisites (geocode), input format, profile selection logic, and exclusion semantics. Nothing required to invoke it correctly is missing.
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 baseline is 3, but the description adds genuine meaning beyond the schema: why to omit profile rather than set 'driving', that exclude is a soft preference with fallback behavior, and a concrete coordinate example (103.8198,1.3521) to lock in ordering. That is more than restating field definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence gives a specific verb and resource ('Calculate a driving route between two locations') and names the backing service. Subsequent bullets distinguish this tool from geocode (coordinate lookup), table (many pairs), and optimize (job assignment), so an agent can select it without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit 'use this tool when' conditions and an equally explicit 'do not use this tool for' list that names the alternative sibling tool (table for many O-D pairs, optimize for stop ordering). The geocode-vs-direct-call decision rule based on whether the user supplied coordinates is spelled out completely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate a travel-time and/or distance matrix between multiple locations using JustRouting.
Use this tool when the user needs to compare travel times or distances between multiple origins and destinations, such as:
finding the nearest driver, vehicle, store, or facility
comparing which destination is closest to an origin
comparing multiple origin-destination pairs
building a distance or travel-time matrix for several locations
Do not use this tool for:
a single route between two locations; use the route tool
assigning jobs to vehicles or determining the order of multiple stops; use the optimize tool
Coordinates:
Each coordinate must be in longitude,latitude format.
For example: ["103.8198,1.3521", "103.9915,1.3644"]
Each coordinate has a stable zero-based index based on its position in the coordinates list.
Matrix rows correspond to sources and columns correspond to destinations.
A matrix value at [row][column] represents the route from that source to that destination.
The sources and destinations in the result include their original coordinate indices, so use these indices to map matrix rows and columns back to the user's locations.
If the user provides place names or addresses instead of coordinates, do not guess their coordinates. Call the geocode tool first for every place, then pass each place's best geocoded coordinates to this tool. Keep the same order as the user's locations so the matrix can be mapped back correctly.
For example, if the user asks which driver is closest to a customer:
put the customer in the coordinates list
put the drivers after it
use the customer as the source and the drivers as destinations
read the corresponding row of the matrix and choose the smallest non-null distance or duration
Unreachable origin-destination pairs are returned as null. Never interpret null as zero or as a valid route.
Optional "sources" and "destinations" select subsets of the coordinates by zero-based index. Omit them to calculate the full matrix.
Optional "annotations" controls which matrices are returned:
"duration" for travel times in seconds
"distance" for distances in meters
["duration", "distance"] for both
omit it to return both
Optional "profile" selects the routing profile:
Set profile to "motorcycle" when the user explicitly asks for a motorcycle or motorbike route.
Otherwise, omit profile to use the default driving profile.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | routing profile: set to "motorcycle" when the user's request mentions a motorcycle or motorbike; otherwise omit it for the default driving profile | |
| sources | No | optional subset of coordinates to use as matrix rows (sources), by index into the coordinates list; empty or omitted means all of them | |
| annotations | No | which matrices to compute: "duration", "distance", or both; omit to get both | |
| coordinates | Yes | list of coordinates in longitude,latitude format, for example ["103.8198,1.3521", "103.9915,1.3644"]; at least 2 required; the position of each coordinate in this list is its index in the returned matrices | |
| destinations | No | optional subset of coordinates to use as matrix columns (destinations), by index into the coordinates list; empty or omitted means all of them |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| message | No | |
| sources | Yes | |
| distances | No | |
| durations | No | |
| destinations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers well: it discloses that unreachable pairs are returned as null and must not be read as zero, states the output units (seconds, meters), and explains row=source / column=destination semantics plus index mapping. It stops short of covering error behavior, rate limits, or coordinate validity limits.
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?
Front-loads purpose and use/don't-use guidance before drilling into coordinates and optional parameters, and every section is relevant. It is somewhat long with repeated coordinate-format and ordering guidance that the schema already contains, keeping it just under top marks.
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 five parameters, a required coordinates list, a nested-free schema, and an output schema that handles return structure, the description covers everything an agent needs: purpose, alternatives, coordinate format, index mapping, subset selection, units, and null handling.
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 baseline is 3, but the description adds genuine meaning: how sources/destinations select subsets by zero-based index, what each annotations value returns, when to set profile to motorcycle, and how to map returned indices back to the user's locations. This goes beyond the schema text.
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?
States a specific verb and resource (calculate a travel-time/distance matrix between multiple locations) and explicitly distinguishes itself from the route and optimize siblings. An agent can identify this as the many-to-many matrix tool without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists when to use it (nearest driver/facility, comparing destinations, multiple O-D pairs) and when not to (single route -> route tool; job assignment/stop ordering -> optimize tool), plus a prerequisite workflow for geocoding named places. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0geocodeoptimizeroutetableScored across 4 tools
Each tool targets a clearly distinct operation: geocode (place→coordinates), route (single two-point route), table (N×M matrix), and optimize (vehicle routing problem). Descriptions go further with explicit 'Do not use this tool for...' clauses that redirect to the correct sibling tool, leaving essentially no room for misselection.
All four names are single lowercase words in a uniform style, which is readable and predictable. The only minor inconsistency is that two are verbs (geocode, optimize) and two are nouns (route, table), but this is conventional for routing APIs and doesn't impede selection.
Four tools is well-scoped for a routing service, covering geocoding, point-to-point routing, matrix computation, and fleet optimization. Each tool earns its place with no redundant or trivial entries.
The surface covers the full core workflow (geocode → route/table/optimize) with clear cross-tool chaining and profile/exclusion options. Only advanced features like isochrones or map-matching are absent, which are minor gaps for most use cases.
Routing, geocoding, places, matrix and map tools for location-aware AI workflows.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Hosted MCP for live place search, geocoding & turn-by-turn routes. No Maps API key to manage.
HERE MCP — premium geocoding, places, and TRAFFIC-AWARE routing from HERE
