update_member_phone

Status: Implemented | Module: member

Add or replace a phone number on the verified member’s profile. CRITICAL: this tool REPLACES by default — it does not append. Same INTENT contract as update_member_email, plus TCPA-safe notification defaults.

For a number used ONLY on this trip, pass it as pickup_phone to set_booking_details instead of calling this tool.

INTENT Contract

When the member already has at least one phone AND the new normalized number does not exact-match any record AND no intent arg was passed, the tool returns INTENT_REQUIRED. STOP, ASK the member how to proceed, then re-call with one of:

Intent	Effect
replace	Overwrite an existing primary in place. Pair with replace_phone_id to target a specific row.
add_secondary	Keep existing primary, save new as is_primary=false.
add_as_primary	Demote current primary to secondary; save new as primary. Rolls back on create failure.
correct_typo	Update the single existing record’s value/note in place. ONLY valid when exactly one record exists.

TCPA / HIPAA Defaults

notification_sms and notification_calls default to OFF — you MUST ask the member explicitly and pass sms_enabled=true / calls_enabled=true to enable them. Silence from the agent means “leave existing alone on update; off by default on create” — never “on” (avoids consent violations and TCPA exposure).

sms_enabled=true is rejected when phone_type=home — landlines silently drop SMS, and the bare consent without a routing path risks a violation flag. The error tells the agent to ask the member for a mobile number.

Annotations

Hint	Value
readOnlyHint	false
destructiveHint	false
idempotentHint	false

Input

Field	Type	Required	Description
session_id	string	yes	Active session ID from verify_member
phone	string	yes	Phone number in any format (10 or 11 digits). Normalized to +1XXXXXXXXXX on save.
phone_type	string	no	mobile, home, or work. Defaults to mobile.
intent	string	conditional	Required when records exist + new value doesn’t match. replace, add_secondary, add_as_primary, or correct_typo.
replace_phone_id	string	no	When intent=replace, the specific phone_id to overwrite. Get from get_member_phone.
sms_enabled	bool	no	Explicit consent for SMS notifications. Defaults to false (TCPA-safe). Rejected for phone_type=home.
calls_enabled	bool	no	Explicit consent for automated voice calls. Defaults to false.
note	string	no	Optional label (e.g. Caretaker phone)

Validation: domain.ValidatePhone rejects anything other than 10 or 11 digits after normalization.

Output

Field	Type	Description
status	string	success or error
phone_id	string	Phone record UUID
number	string	Normalized E.164 number (e.g. +12765551234)
action	string	created, updated, replaced, added_secondary, or added_as_primary
is_primary	bool	Whether the saved row is the primary
message	string	Human summary
guidance	Guidance	Suggests set_booking_details or update_member_address next

v2.0 audit change: MemberName is no longer echoed (caller has it from session — AUDIT-3 / P2-5). is_primary reflects the actual stored flag (no longer always true).

Side Effects

• Writes via the nemt-objects Phone facade with the agent-supplied notification flags (default off).
• Emits a HIPAA audit entry mcp.update_member_phone — metadata carries action, phone_type, and intent only. The number is NEVER logged or audited.
• INTENT_REQUIRED and TCPA-rejected calls emit outcome=denied audit rows.

Error Codes

• INTENT_REQUIRED — Member has existing phones and the new value doesn’t exact-match any of them.
• MISSING_PREREQUISITE — Session missing, invalid phone format, or sms_enabled=true paired with phone_type=home.

Related

• Source: internal/app/member/usecases/update_member_phone.go, internal/app/member/register.go
• Read companion: get_member_phone (provides the phone_id you pass as replace_phone_id)
• Prerequisite: verify_member