Skip to content
NEMT MCP Service

find_place

Status: Implemented | Module: address

Search for healthcare facilities, clinics, hospitals, pharmacies, and other places by name or description (e.g. dialysis on Hopkins Road, DaVita in Richmond, the clinic near my house). Backed by Google Places Text Search with a location bias (member org home coordinates when a session is provided, Virginia-center fallback otherwise), an optional healthcare-focused category filter, and Google Places Details enrichment on the top results.

Does NOT require a session — pass session_id for per-org caching and bias.

v2.0 Enrichment

Section titled “v2.0 Enrichment”

For the top 3 results, the use case follows up with a Google Places Details call to enrich each candidate with:

  • formatted_phone_number — local-format phone
  • international_phone_number — E.164 phone
  • business_status — OPERATIONAL, CLOSED_TEMPORARILY, CLOSED_PERMANENTLY
  • opening_hours — weekday text + currently-open flag

A soft HoursAdvisory is attached to candidates whose opening hours suggest the place is closed at the appointment time, so the agent can warn the member without making a hard rejection.

The enrichment payload is cached for 24 hours per place_id to keep the Google quota cost bounded.

Annotations

Section titled “Annotations”
Hint Value
readOnlyHint true
openWorldHint true

Input

Section titled “Input”
Field Type Required Description
session_id string no Session ID from verify_member. When provided, biases results and enables per-org cache.
query string yes Facility/place name or description. Include city/state for better results.
category string no Optional filter. One of: medical, pharmacy, diagnostic. Unknown values rejected with a validation error.

Category keyword mapping

Section titled “Category keyword mapping”
  • medical → medical clinic
  • pharmacy → pharmacy
  • diagnostic → diagnostic lab imaging

The keyword is appended to the query before calling Google Places, biasing relevance.

Output

Section titled “Output”
Field Type Description
places Candidate[] Matched places (capped at 5, de-duplicated by coordinate rounded to 4 decimals)
place_count int Number of results returned
query string Original query (without appended category keyword)
category string Echoed category filter (if any)
street_hint_warning string Non-fatal warning when the query mentioned a street/road name but no result contains it

Candidate Fields

Section titled “Candidate Fields”

Same shape as resolve_address candidates: street, city, state, zip_code, latitude, longitude, facility_name, facility_id, phone, source, confidence.

Enriched Fields (top 3 results, v2.0)

Section titled “Enriched Fields (top 3 results, v2.0)”
Field Type Description
formatted_phone_number string Local-format phone
international_phone_number string E.164 phone
business_status string OPERATIONAL, CLOSED_TEMPORARILY, or CLOSED_PERMANENTLY
opening_hours object {weekday_text[], open_now} from Google Places Details
hours_advisory string Soft warning when the place appears closed at the relevant time (non-fatal)

STT Mismatch Warning

Section titled “STT Mismatch Warning”

On voice calls, speech-to-text frequently garbles street/road names (Hioaks Road → Hyx Road, Jahnke → Yanky). When the query contains a road-suffix word (Road, Street, Avenue, etc.) and none of the returned results contain that street name, the response includes a street_hint_warning telling the AI agent to ask the member to SPELL the street name rather than cycling through wrong results.

Caching

Section titled “Caching”
  • Results cached per org_id + effective_query + location_bias for 1 hour.
  • Cache read/write failures are non-fatal (logged and treated as a miss).
  • Cache key is a SHA-256 hash truncated to 16 hex chars.

Location Bias

Section titled “Location Bias”
  • When session_id is supplied and valid: the session’s org_id is resolved and used for cache attribution.
  • Default bias coordinates: 37.4316, -78.6569 (Virginia center). Session-based home coordinates are deferred until the session model stores them.

Side Effects

Section titled “Side Effects”
  • Touches session TTL when session_id is provided (non-fatal).
  • No audit write — this tool is a lookup and no PHI is persisted.
Section titled “Related”
  • Source: internal/app/address/usecases/find_place.go, internal/app/address/adapters/mcp/handlers/find_place.go
  • Companion: resolve_address (cascade-based exact address resolution)
  • Next: set_booking_details with the confirmed address + lat/lon