analyze_missing_critical_data

Instructions

Implementation Reference

• server/tools/analyze_missing.py:5-106 (handler)

  The core handler function that implements the 'analyze_missing_critical_data' tool logic. It checks for missing/pending troponin, vital signs (blood pressure, heart rate, oxygen saturation), ECG interpretation, STEMI-related contraindications/red flags, heart failure markers (BNP, echo), and Chagas serology based on case data from a synthetic case.

  def analyze_missing_critical_data(case_id: str) -> MissingCriticalDataOutput:
      case = get_synthetic_case(case_id)
      missing: list[MissingCriticalDataItem] = []
  
      lab_keys = {key.lower(): value for key, value in case.labs.items()}
      troponin = lab_keys.get("troponin")
      if troponin is None:
          missing.append(
              MissingCriticalDataItem(
                  field="troponin",
                  status="missing",
                  why_critical="Troponin is needed to support ACS rule-in/rule-out and serial trend assessment.",
                  suggested_action="Obtain baseline and repeat troponin per local ED protocol.",
              )
          )
      elif "pending" in troponin.lower():
          missing.append(
              MissingCriticalDataItem(
                  field="troponin",
                  status="pending",
                  why_critical="A pending troponin does not yet complete ACS risk stratification.",
                  suggested_action="Track result availability and repeat if symptoms or timing require serial testing.",
              )
          )
  
      vital_keys = {key.lower() for key in case.vitals}
      required_vitals = {
          "blood pressure": "Hemodynamic status changes immediate triage priority.",
          "heart rate": "Tachycardia or bradycardia can signal instability or arrhythmia.",
          "oxygen saturation": "Hypoxemia changes escalation and differential diagnosis.",
      }
      for field, why in required_vitals.items():
          if field not in vital_keys:
              missing.append(
                  MissingCriticalDataItem(
                      field=field,
                      status="missing",
                      why_critical=why,
                      suggested_action=f"Document {field} before risk disposition.",
                  )
              )
  
      if not case.ecg:
          missing.append(
              MissingCriticalDataItem(
                  field="ECG interpretation",
                  status="missing",
                  why_critical="ECG interpretation is central to STEMI/NSTEMI and arrhythmia triage.",
                  suggested_action="Document clinician-reviewed ECG interpretation.",
              )
          )
  
      text = f"{case.presenting_problem} {case.ecg}".lower()
      if "st-elevation" in text or "stemi" in text:
          missing.append(
              MissingCriticalDataItem(
                  field="reperfusion/antithrombotic contraindications",
                  status="missing",
                  why_critical="High-risk ACS pathways require contraindication review before therapy decisions.",
                  suggested_action="Document bleeding risk, allergy history, anticoagulant use, and reperfusion contraindications.",
              )
          )
          missing.append(
              MissingCriticalDataItem(
                  field="red flags review",
                  status="incomplete",
                  why_critical="Ongoing pain, syncope, shock, or malignant arrhythmia would change escalation urgency.",
                  suggested_action="Document structured red flags review and escalation status.",
              )
          )
  
      if "heart failure" in text or "dyspnea" in text or "cardiomyopathy" in text:
          missing.extend(
              [
                  MissingCriticalDataItem(
                      field="BNP/NT-proBNP",
                      status="missing",
                      why_critical="Natriuretic peptide data helps support or refute acute heart failure.",
                      suggested_action="Order BNP or NT-proBNP if available.",
                  ),
                  MissingCriticalDataItem(
                      field="echocardiography",
                      status="missing",
                      why_critical="Echo helps characterize ventricular function, valvular disease, and cardiomyopathy pattern.",
                      suggested_action="Request focused or formal echocardiography based on local availability.",
                  ),
              ]
          )
  
      if "chagas" in text:
          missing.extend(
              [
                  MissingCriticalDataItem(
                      field="Chagas serology",
                      status="missing",
                      why_critical="Synthetic Latam endemic-origin context raises Chagas cardiomyopathy as a differential.",
                      suggested_action="Document epidemiologic risk and order confirmatory serology if clinically appropriate.",
                  ),
              ]
          )
  
      return MissingCriticalDataOutput(case_id=case.case_id, missing=missing)

• server/main.py:160-163 (registration)

  The tool is registered with FastMCP via server.tool()(analyze_missing_critical_data) inside the register_tools function. Also listed in REGISTERED_TOOL_NAMES on line 27.

  def register_tools(server: FastMCP) -> None:
      server.tool()(list_synthetic_cases)
      server.tool()(get_fhir_case_bundle)
      server.tool()(analyze_missing_critical_data)

• server/models.py:27-37 (schema)

  Pydantic models MissingCriticalDataItem (field, status, why_critical, suggested_action) and MissingCriticalDataOutput (case_id, missing list, disclaimer) define the input/output schema for the tool.

  class MissingCriticalDataItem(BaseModel):
      field: str
      status: Literal["missing", "pending", "incomplete"]
      why_critical: str
      suggested_action: str
  
  
  class MissingCriticalDataOutput(BaseModel):
      case_id: str
      missing: list[MissingCriticalDataItem]
      disclaimer: str = DISCLAIMER

• server/main.py:132-135 (helper)

  The MCP-facing wrapper function in server/main.py that delegates to the actual implementation in server/tools/analyze_missing.py. Provides the tool's description for the MCP registry.

  def analyze_missing_critical_data(case_id: str) -> MissingCriticalDataOutput:
      """Flag missing or pending critical cardiovascular triage data for a synthetic case. Use before risk disposition. NOT for clinical use."""
  
      return analyze_missing_tool(case_id)

• server/tools/handoff_note.py:1-24 (helper)

  The handoff note tool directly imports and calls analyze_missing_critical_data on line 10, integrating missing data findings into the generated SBAR note.

  from backend.fhir_bundle import get_synthetic_case
  from server.models import HandoffNote, HandoffNoteOutput, Language
  from server.tools.analyze_missing import analyze_missing_critical_data
  from server.tools.summarize_risk import summarize_cardiovascular_risk_signals
  
  
  def generate_structured_handoff_note(case_id: str, language: Language = "en") -> HandoffNoteOutput:
      case = get_synthetic_case(case_id)
      risk = summarize_cardiovascular_risk_signals(case.case_id)
      missing = analyze_missing_critical_data(case.case_id)
      recommendations = _recommendations(case.case_id)
  
      note = HandoffNote(
          situation=f"Synthetic {case.case_id}: {case.presenting_problem}.",
          background=(
              f"{case.age}-year-old {case.sex}; vitals: {_format_dict(case.vitals)}; "
              f"labs: {_format_dict(case.labs) if case.labs else 'none documented'}; ECG: {case.ecg}."
          ),
          assessment=_assessment(case.case_id, risk),
          recommendation=recommendations,
          safety=_safety(language),
      )
      text = _render_sbar(note, missing_fields=[item.field for item in missing.missing], language=language)
      return HandoffNoteOutput(case_id=case.case_id, language=language, note=note, text=text)