refine mcp

docs.json

@@ -40,7 +40,11 @@
       {
         "group": "MCP",
         "pages": [
-          "mcp/overview"
+          "mcp/overview",
+          "mcp/geocode",
+          "mcp/route",
+          "mcp/table",
+          "mcp/optimize"
         ]
       },
       {

mcp/geocode.mdx

@@ -0,0 +1,115 @@
+---
+title: "Geocode Tool"
+description: "Convert a place name or address into coordinates — structured fields, filters, and best-match results."
+icon: "search"
+---
+
+## Overview
+
+Search for a place or address and convert it into coordinates.
+
+Use this tool 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 in `longitude,latitude` format.
+
+## Structured input
+
+The search is structured. Parse the user's location into the 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:
+
+```json
+{
+  "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.
+
+## Limit and filters
+
+`limit` is optional and defaults to `1`.
+
+The maximum value is `10`.
+
+Use a larger `limit` when the location is ambiguous or the user asks for alternatives.
+
+`filters` can optionally restrict the search.
+
+For example:
+
+```json
+{
+  "name": "Marina Bay Sands",
+  "country": "Singapore",
+  "limit": 5,
+  "filters": ["countrycode:sg"]
+}
+```
+
+## Output
+
+```json
+{
+  "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.
+
+If 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`](/mcp/route), [`table`](/mcp/table), or [`optimize`](/mcp/optimize).
+
+When using geocode as part of a routing workflow, verify that the selected result matches the user's intended place before passing its coordinates to the next tool.
+
+If no result matches, the tool returns an error so the assistant can refine the search.
+
+## Example
+
+Prompt for an MCP-capable agent, e.g. Claude or Codex
+
+```shell
+What are the latitude and longitude for 75 Jln Kelabu Asap, Singapore 278268?
+
+# The coordinates for 75 Jalan Kelabu Asap, Singapore 278268 are:
+#
+# - Latitude: 1.310368
+# - Longitude: 103.797116
+#
+# (In longitude,latitude format: 103.797116,1.310368)
+```

mcp/optimize.mdx

@@ -0,0 +1,215 @@
+---
+title: "Optimize Tool"
+description: "Assign jobs to vehicles and determine the order in which each vehicle visits its stops."
+icon: "truck"
+---
+
+## Overview
+
+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 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`](/mcp/route).
+
+Do not use it only to compare distances or travel times between locations. Use [`table`](/mcp/table).
+
+## Input
+
+```json
+{
+  "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"
+    }
+  ]
+}
+```
+
+Every vehicle must have a unique `id`.
+
+Every job must have a unique `id` and a `location`.
+
+Locations must use:
+
+```text
+longitude,latitude
+```
+
+Each vehicle must have at least a `start` or an `end`.
+
+For a round trip, set both `start` and `end` to the same location:
+
+```json
+{
+  "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.
+
+## Vehicle profiles
+
+Each vehicle can use its own routing profile.
+
+Use:
+
+```json
+"profile": "motorcycle"
+```
+
+when the user explicitly asks for a motorcycle or motorbike route.
+
+Otherwise, omit `profile` to use the default driving profile.
+
+For example:
+
+```json
+{
+  "id": 1,
+  "profile": "motorcycle",
+  "start": "103.7923,1.3246",
+  "end": "103.7923,1.3246"
+}
+```
+
+## Output
+
+A simplified result looks like:
+
+```json
+{
+  "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": []
+}
+```
+
+Use `routes[].steps` to determine:
+
+* which vehicle serves each job
+* the order in which jobs are visited
+* when each job is reached
+
+A `job` step contains the job ID, arrival time, travel duration, and travel distance for reaching that job.
+
+Always check `unassigned`.
+
+**Do not assume that every job will be assigned.**
+
+If the user provides place names or addresses instead of coordinates, call [`geocode`](/mcp/geocode) first for every location and use the selected coordinates in the optimization request.
+
+## Example
+
+Prompt for an MCP-capable agent, e.g. Claude or Codex
+
+```shell
+I have two vans available to pick up packages from six customers.
+
+Vans:
+- V1 starts at 249 Sixth Ave, Singapore 275771
+- V2 starts at 8 Harlyn Rd, Singapore 299445
+
+Customers:
+- C1: 75 Jln Kelabu Asap, Singapore 278268
+- C2: 20 Mount Sinai Rd, Singapore 276854
+- C3: 10 Bin Tong Park, Singapore 269792
+- C4: 9 Cluny Park, Singapore 259619
+- C5: 28 Nassim Rd, Singapore 258403
+- C6: 30 Chancery Ln, Singapore 309549
+
+How should these six pickup tasks be assigned and ordered between the two vans?
+
+# Solved — all 6 jobs assigned, none left unassigned. Optimal assignment:
+#
+# Van V1 — starts at 249 Sixth Ave (total ~19.4 min)
+# ┌──────┬──────────┬────────────────────┬────────────┐
+# │ Stop │ Customer │      Address       │ Arrives at │
+# ├──────┼──────────┼────────────────────┼────────────┤
+# │ 1    │ C2       │ 20 Mount Sinai Rd  │ ~6 min     │
+# ├──────┼──────────┼────────────────────┼────────────┤
+# │ 2    │ C1       │ 75 Jln Kelabu Asap │ ~13 min    │
+# ├──────┼──────────┼────────────────────┼────────────┤
+# │ 3    │ C3       │ 10 Bin Tong Park   │ ~17 min    │
+# └──────┴──────────┴────────────────────┴────────────┘
+#
+#  Van V2 — starts at 8 Harlyn Rd (total ~29.0 min)
+# ┌──────┬──────────┬────────────────┬────────────┐
+# │ Stop │ Customer │    Address     │ Arrives at │
+# ├──────┼──────────┼────────────────┼────────────┤
+# │ 1    │ C6       │ 30 Chancery Ln │ ~5 min     │
+# ├──────┼──────────┼────────────────┼────────────┤
+# │ 2    │ C5       │ 28 Nassim Rd   │ ~14 min    │
+# ├──────┼──────────┼────────────────┼────────────┤
+# │ 3    │ C4       │ 9 Cluny Park   │ ~23 min    │
+# └──────┴──────────┴────────────────┴────────────┘
+#
+# Each van returns to its own depot afterward. The solver minimizes total fleet driving time (~48.5 min combined),
+# which is why V1 picks up the western cluster and V2 covers the eastern side
+```