Skip to content
NEMT MCP Service

resolve_address

Status: Verified | Module: address

Validate and geocode a street address (house number + street + city) through a 4-source cascade with type-aware ranking. Google Maps and HERE Maps are queried in parallel for the geocoding fallback so the slower provider does not delay the response. REQUIRED before set_booking_details — call for BOTH pickup and dropoff.

For facility/place lookups (clinic names, partial addresses), use find_place instead — it carries Google Places Text Search + Details enrichment that this tool does not.

If best_match is null or all_blocked is true, the address could not be verified — ask the member to SPELL the street name (speech-to-text often garbles road names on phone calls) and retry. No session required.

Annotations

Section titled “Annotations”
Hint Value
readOnlyHint true
openWorldHint true

Input

Section titled “Input”
Field Type Required Description
session_id string yes Active session
address string yes Free-text address to resolve
type string no pickup or dropoff hint for ranking

Cascade Order

Section titled “Cascade Order”
  1. Saved addresses – member’s home and frequent addresses (confidence: 0.95)
  2. Trip history – addresses from previous trips (confidence: 0.85)
  3. Facilities DB – medical facilities via Spanner FORCE_INDEX (confidence: 0.80)
  4. Google Maps – geocoding fallback (confidence: 0.70)

Output

Section titled “Output”
Field Type Description
candidates Candidate[] Up to 5 ranked results
best_match Candidate Highest confidence match
query string Original search text

Candidate Fields

Section titled “Candidate Fields”
Field Type Description
street string Street address
city string City
state string State (2-letter)
zip_code string ZIP code
latitude float Latitude
longitude float Longitude
facility_name string Facility name (if source=facility)
phone string Facility phone (pass to set_booking_details)
source string saved_address, trip_history, facility, google_maps
confidence float 0.0 to 1.0

Example Request

Section titled “Example Request”
{
  "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": {
    "name": "resolve_address",
    "arguments": { "session_id": "a1b2c3d4-...", "address": "Springfield Medical", "type": "dropoff" }
  }
}

Example Response

Section titled “Example Response”
{
  "status": "success",
  "data": {
    "candidates": [
      {
        "street": "456 Health Ave", "city": "Springfield", "state": "IL", "zip_code": "62701",
        "latitude": 39.7817, "longitude": -89.6501,
        "facility_name": "Springfield Medical Center", "facility_id": "fac-uuid-001",
        "source": "facility", "confidence": 0.92
      }
    ],
    "best_match": { "..." },
    "query": "Springfield Medical"
  }
}

Error Codes

Section titled “Error Codes”
  • INVALID_ADDRESS – Address cannot be resolved
  • ADDRESS_AMBIGUOUS – Multiple matches, present candidates to member
Section titled “Related”