Skip to content
NEMT MCP Service

update_member_address

Status: Implemented | Module: member

Save an address/place on the verified member’s profile. The server geocodes the address (falling back to raw text if geocoding is unavailable). Two safety rails apply on every write: address dedup and home exclusivity.

ALWAYS call get_member_addresses first so you can re-use an existing address by place_id instead of relying on dedup as a backstop.

DEDUP

Section titled “DEDUP”

Before writing, the tool looks up the member’s existing places and matches by:

  1. Normalized address string (case + whitespace + punctuation folded), OR
  2. ~50 m lat/lon proximity when both rows have coordinates.

A match returns the existing place_id with action=already_exists (or action=updated when the home flag or label needed promotion). Duplicates are NOT created.

HOME EXCLUSIVITY

Section titled “HOME EXCLUSIVITY”

When is_home=true is passed, the tool first demotes every other place flagged is_home to is_home=false, then sets the new row’s flag. The member always has at most one home address. The demote-then-set sequence is atomic from the agent’s perspective — a partial failure surfaces in the audit row.

(Unlike email/phone, there is no INTENT contract here — Place rows do not carry a “primary” concept. Dedup + home-exclusivity cover the same ground.)

Annotations

Section titled “Annotations”
Hint Value
readOnlyHint false
destructiveHint false
idempotentHint false

Input

Section titled “Input”
Field Type Required Description
session_id string yes Active session ID from verify_member
address string yes Full street address (e.g. 123 Main St, Springfield, IL 62701)
name string no Optional label (e.g. Home, Work, Dialysis Center)
is_home bool no Whether this is the member’s home address. Defaults to false. Setting true demotes every other home row.

Output

Section titled “Output”
Field Type Description
status string success or error
place_id string Saved-place UUID (existing row id when dedup matched)
address string Display-friendly address (formatted or geocoded)
name string Label (echoed from input)
is_home bool Whether the saved row is flagged home
action string created, updated, or already_exists
message string Human summary
guidance Guidance Suggests set_booking_details or update_member_phone next

v2.0 audit change: MemberName is no longer echoed (caller has it from session — AUDIT-3 / P2-5).

Workflow Tip

Section titled “Workflow Tip”

Call resolve_address FIRST when the input is a facility name or partial address — that gives you a confirmed structured address before persisting.

Side Effects

Section titled “Side Effects”
  • Calls the configured geocoder (graceful degradation on failure — raw text is used for the street value).
  • Writes (or updates / acknowledges) a saved place via the nemt-objects Place facade.
  • Emits a HIPAA audit entry mcp.update_member_address — metadata carries place_id, is_home, and action only. The address text and coordinates are NEVER logged.
  • Error logs redact the raw address value.
Section titled “Related”
  • Source: internal/app/member/usecases/update_member_address.go, internal/app/member/register.go
  • Read companion: get_member_addresses (use place_id from this list to avoid duplicate writes)
  • Prerequisite: verify_member, optionally resolve_address