Get Demographics

Overview

get_demographics retrieves the user's demographic information from their FHIR Person record. An LLM/agent should call this tool to personalize interactions, address the user by name, or provide context-aware responses — for example, when the user asks "who am I?" or "what's my name?", when personalizing a greeting, during identity verification or contact-confirmation tasks, or any time context about the user would improve the response. The result includes name, gender, birth date, and contact information (phone, email, address), each returned with privacy labels and embedded instructions for how an LLM should (and should not) use them.

Optional Parameters

person_id (string)

• Default: None
• The identifier of the person whose demographics are to be retrieved.
• If not provided, the tool attempts to extract it from the caller's access token (from the clientFhirPersonId claim).
• If it cannot be supplied directly or resolved from the token, the tool returns an error result stating that the person ID is required and could not be extracted from the access token.

debug (boolean)

• Default: false
• Whether to include debugging information in the response, such as the FHIR request URL(s) and retrieval timing/debug metadata.

Returns

Returns a FhirDemographicsResult object with the following fields (inherited from the shared base result model, with result re-described for this tool):

• result (string, optional) — A formatted "USER CONTEXT (from FHIR Person record)" text block for LLM system-message consumption. When data is available it includes:
  • Name
  • Gender
  • Birth date (with calculated age and, when close, days until the next birthday)
  • Timezone, inferred from the address's US state
  • Phone, labeled "(sensitive)", with its use (e.g., mobile/home/work) if known
  • Email, labeled "(sensitive)", with its use if known
  • Address, labeled "(sensitive)", formatted as a single line (line1, line2 | city, state, postal | country), with its use if known
  • A "PRIVACY / BEHAVIOR RULES" section instructing the consuming LLM not to proactively reveal phone, email, or full address, and to only surface those details if the user explicitly asks or an identity-verification/contact-confirmation task requires it.
• error (string, optional) — Populated instead of result when the person ID is missing/unresolvable, the Person resource lookup fails (non-200 response), no Person resource is found for the given ID, or an unexpected error occurs during retrieval.
• urls (list of strings, optional) — Present only when debug=true; contains the FHIR request URL(s) used to fetch the Person resource.
• meta (object, optional) — Additional metadata about the retrieval process (defined on the shared base result model; not populated by this tool's retriever).
• debug (object, optional) — Present only when debug=true; includes retrieval timing (fhir_call_duration_seconds), cache status (caching is not implemented for demographics, so from_cache is always false), and, on success, a request_id.

Notes

• Best-match selection: when multiple phone numbers, emails, or addresses exist on the Person record, the tool picks one using a priority order — for phone/email: mobile > home > work > temp > old (with rank as a tiebreaker); for address: home > work > temp > old. Only the single best match per category is returned, not the full list.
• The birth date can be a partial FHIR date (YYYY, YYYY-MM, or YYYY-MM-DD); age and next-birthday calculations degrade gracefully (assuming Jan 1 / the 1st of the month) for partial dates, or are omitted if the date can't be parsed.
• Requires a valid OAuth access token; the tool raises a ToolError internally if no access token is present, though the outer registration function returns a structured error result before reaching that point when person_id cannot be resolved at all.
• Caching is explicitly not implemented for this tool — every call performs a live FHIR fetch of the Person resource.