clinical-knowledge

name	clinical-knowledge
description	Teaches agents clinical reference ranges, condition codes, quality measure definitions, drug classifications, and regulatory context so they can flag abnormal values and identify care gaps.
metadata	{"openclaw":{"requires":{"bins":["python3"]}}}

Clinical Reference Knowledge

Regulatory Context

The 21st Century Cures Act (2016) and ONC's Interoperability Final Rule (2020) require US healthcare organizations to expose patient data through standardized FHIR APIs. As of 2024, ~70% of US hospitals support FHIR R4 (source: ONC). CMS ties quality measure reporting to reimbursement through programs like MIPS (Merit-based Incentive Payment System) and the Hospital Value-Based Purchasing Program. Failure to report -- or poor performance -- results in payment adjustments of up to 9%.

HIPAA (Health Insurance Portability and Accountability Act) prohibits transmitting Protected Health Information (PHI) to external services without a BAA (Business Associate Agreement). This is the primary reason clinical AI must run locally: cloud LLM APIs are not BAA-covered by default, and even those that offer BAAs (e.g., Azure OpenAI) face institutional resistance from hospital compliance teams.

Common Lab Reference Ranges

These are general adult reference ranges. Values vary by lab, assay, and patient characteristics. Always defer to the performing laboratory's reference range when available via FHIR referenceRange.

Lab	Normal Range	Concerning	Unit	Notes
HbA1c	< 5.7% (non-diabetic), < 7.0% (diabetic target)	> 9.0% = poor control	%	ADA 2024 guidelines; target may be relaxed to < 8.0% for elderly/frail
Fasting Glucose	70-100	100-125 = prediabetes, >= 126 = diabetic	mg/dL	Must be fasting; random glucose >= 200 also diagnostic
Creatinine	0.7-1.3 (male), 0.6-1.1 (female)	> 1.5 = impaired renal	mg/dL	Affected by muscle mass; less reliable in elderly
eGFR	> 90 (normal), 60-89 (mild decrease)	30-59 = moderate CKD, 15-29 = severe, < 15 = kidney failure	mL/min/1.73m2	CKD-EPI 2021 equation (race-neutral)
BUN	7-20	> 20 with rising creatinine = renal concern	mg/dL	Elevated by dehydration, high protein diet
Total Cholesterol	< 200	200-239 = borderline, >= 240 = high	mg/dL
LDL	< 100 (general), < 70 (high-risk ASCVD)	> 160 = high	mg/dL	ACC/AHA 2018
HDL	> 40 (male), > 50 (female)	< 40 = cardiovascular risk factor	mg/dL
Triglycerides	< 150	150-499 = elevated, >= 500 = severe (pancreatitis risk)	mg/dL
Systolic BP	< 120 (normal), 120-129 (elevated)	130-139 = Stage 1 HTN, >= 140 = Stage 2 HTN	mmHg	ACC/AHA 2017; CMS165 uses 140/90 threshold
Diastolic BP	< 80	80-89 = Stage 1 HTN, >= 90 = Stage 2 HTN	mmHg
BNP	< 100	100-400 = possible HF, > 400 = likely HF	pg/mL	Age-adjusted: higher cutoffs in elderly; obesity lowers BNP
NT-proBNP	< 300 (rule-out)	Age-stratified: >450 (<50y), >900 (50-75y), >1800 (>75y)	pg/mL	More stable than BNP; renal clearance affects levels
Potassium	3.5-5.0	< 3.5 = hypokalemia, > 5.5 = hyperkalemia (cardiac risk)	mEq/L	Critical for patients on ACEi/ARB/spironolactone
Sodium	136-145	< 130 = moderate hyponatremia	mEq/L	Common in HF patients
ALT	7-56	> 3x ULN = significant hepatotoxicity	U/L	Monitor with statin therapy
Hemoglobin	13.5-17.5 (male), 12.0-16.0 (female)	< 12 (male) or < 11 (female) = anemia	g/dL	Common in CKD (erythropoietin deficiency)

When reporting lab values:

• Always flag values outside the normal range with the severity (mild / moderate / severe)
• Note the date of the observation -- a result from 2 years ago has different clinical significance than one from yesterday
• If the FHIR Observation includes a referenceRange, use that instead of the table above

Condition Codes

SNOMED CT Codes (Primary)

Code	Condition	ICD-10 Equivalent	Prevalence (US adults)
44054006	Type 2 Diabetes Mellitus	E11.x	~11% (37M)
46635009	Type 1 Diabetes Mellitus	E10.x	~0.5% (1.6M)
38341003	Essential Hypertension	I10	~47% (116M)
84114007	Heart Failure	I50.x	~2.4% (6.7M)
40055000	Chronic Kidney Disease	N18.x	~15% (37M)
53741008	Coronary Artery Disease	I25.x	~7% (20M)
13645005	COPD	J44.x	~6% (16M)
195967001	Asthma	J45.x	~8% (25M)
49436004	Atrial Fibrillation	I48.x	~2% (6M)
73211009	Diabetes (unspecified)	E11.9	Used in older records

ICD-10-CM to SNOMED Crosswalk

When FHIR Condition resources use ICD-10 coding (system http://hl7.org/fhir/sid/icd-10-cm), map as follows:

• E11.* → Type 2 Diabetes (SNOMED 44054006)
• E10.* → Type 1 Diabetes (SNOMED 46635009)
• I10 → Essential Hypertension (SNOMED 38341003)
• I50.* → Heart Failure (SNOMED 84114007)
• N18.* → Chronic Kidney Disease (SNOMED 40055000)

Note: A Condition resource may have both SNOMED and ICD-10 codes in the coding array. Always check all entries, not just coding[0].

CMS Quality Measures

CMS122v12 -- Diabetes: Hemoglobin A1c (HbA1c) Poor Control (> 9%)

Component	Definition
Denominator	Patients 18-75 with diabetes (Type 1 or Type 2) and at least 2 encounters during the measurement period
Numerator	Patients with most recent HbA1c > 9.0%, OR no HbA1c recorded during the measurement period
Exclusions	Hospice care, palliative care, advanced illness with frailty (2+ encounters for advanced illness AND frailty diagnosis), dementia medications (donepezil, rivastigmine, memantine, galantamine)
Performance rate	Lower is better (inverse measure)
Payment impact	Part of MIPS quality reporting; affects Medicare reimbursement

CMS165v12 -- Controlling High Blood Pressure

Component	Definition
Denominator	Patients 18-85 with essential hypertension diagnosed before or during the measurement period
Numerator	Patients with most recent BP < 140/90 mmHg
Exclusions	Hospice, palliative care, ESRD, kidney transplant, advanced illness with frailty, pregnancy
Performance rate	Higher is better
Note	BP must be measured during an outpatient encounter; home BP readings are not counted in the standard measure

CMS135v12 -- Heart Failure: ACEi/ARB/ARNI Therapy for LVEF < 40%

Component	Definition
Denominator	Patients 18+ with heart failure AND documented LVEF < 40% (HFrEF)
Numerator	Patients prescribed ACE inhibitor, ARB, or ARNI (sacubitril/valsartan)
Exclusions	Hospice, allergy/intolerance to all three classes, bilateral renal artery stenosis, pregnancy, hyperkalemia > 5.5
Note	LVEF data often in DiagnosticReport or CarePlan, not always queryable via Condition alone

CMS134v12 -- Diabetes: Medical Attention for Nephropathy

Component	Definition
Denominator	Patients 18-75 with diabetes
Numerator	Patients with nephropathy screening (urine albumin test) OR evidence of nephropathy treatment (ACEi/ARB) OR nephropathy diagnosis
Exclusions	Hospice, palliative care, advanced illness with frailty

Drug Classifications

When checking medication coverage, recognize these drug class groupings. Matching should be case-insensitive partial string matching on the medication name from FHIR medicationCodeableConcept.text or .coding[].display.

Diabetes Medications

Class	Drugs	Notes
Biguanide	metformin	First-line therapy
Sulfonylureas	glipizide, glyburide, glimepiride	Hypoglycemia risk
Insulin	insulin lispro, insulin glargine, insulin aspart, insulin detemir, insulin degludec, NPH insulin	Match any string containing "insulin"
GLP-1 Receptor Agonists	liraglutide (Victoza), semaglutide (Ozempic/Wegovy/Rybelsus), dulaglutide (Trulicity), exenatide (Byetta/Bydureon), tirzepatide (Mounjaro)	Weight loss benefit; cardiovascular benefit
SGLT2 Inhibitors	empagliflozin (Jardiance), dapagliflozin (Farxiga), canagliflozin (Invokana), ertugliflozin (Steglatro)	Cardiovascular + renal benefit; monitor for DKA
DPP-4 Inhibitors	sitagliptin (Januvia), saxagliptin, linagliptin, alogliptin	Weight-neutral
Thiazolidinediones	pioglitazone, rosiglitazone	HF risk; edema

Antihypertensives

Class	Drugs	Notes
ACE Inhibitors	lisinopril, enalapril, ramipril, benazepril, fosinopril, quinapril	Cough side effect; monitor K+ and creatinine
ARBs	losartan, valsartan, irbesartan, olmesartan, telmisartan, candesartan, azilsartan	Alternative if ACEi cough
ARNIs	sacubitril/valsartan (Entresto)	HFrEF guideline-directed; do NOT combine with ACEi
CCBs	amlodipine, nifedipine, diltiazem, verapamil	Diltiazem/verapamil contraindicated in HFrEF
Beta-Blockers	metoprolol (tartrate or succinate), atenolol, carvedilol, bisoprolol, propranolol, nebivolol	Only carvedilol, metoprolol succinate, bisoprolol for HF
Thiazide Diuretics	hydrochlorothiazide (HCTZ), chlorthalidone, indapamide	First-line for HTN
Loop Diuretics	furosemide, bumetanide, torsemide	Volume management in HF, not primary HTN therapy
Aldosterone Antagonists	spironolactone, eplerenone	HF benefit; monitor K+

Statins (HMG-CoA Reductase Inhibitors)

Intensity	Drugs
High	atorvastatin 40-80mg, rosuvastatin 20-40mg
Moderate	atorvastatin 10-20mg, rosuvastatin 5-10mg, simvastatin 20-40mg, pravastatin 40-80mg
Low	simvastatin 10mg, pravastatin 10-20mg, lovastatin 20mg

Heart Failure Medications (Guideline-Directed Medical Therapy)

The four pillars of HFrEF therapy (ACC/AHA 2022):

1. ACEi/ARB/ARNI -- sacubitril/valsartan preferred over ACEi/ARB
2. Beta-Blocker -- carvedilol, metoprolol succinate, or bisoprolol only
3. Aldosterone Antagonist -- spironolactone or eplerenone (if eGFR > 30, K+ < 5.0)
4. SGLT2 Inhibitor -- dapagliflozin or empagliflozin (regardless of diabetes status)

Matching Strategy

medication_name = fhir_med_text.lower()

is_on_insulin = "insulin" in medication_name
is_on_glp1 = any(drug in medication_name for drug in
    ["liraglutide", "semaglutide", "dulaglutide", "exenatide", "tirzepatide",
     "victoza", "ozempic", "trulicity", "byetta", "mounjaro", "rybelsus"])
is_on_sglt2 = any(drug in medication_name for drug in
    ["empagliflozin", "dapagliflozin", "canagliflozin", "ertugliflozin",
     "jardiance", "farxiga", "invokana", "steglatro"])
is_on_acei = any(drug in medication_name for drug in
    ["lisinopril", "enalapril", "ramipril", "benazepril", "fosinopril", "quinapril"])
is_on_arb = any(drug in medication_name for drug in
    ["losartan", "valsartan", "irbesartan", "olmesartan", "telmisartan",
     "candesartan", "azilsartan"])
is_on_betablocker = any(drug in medication_name for drug in
    ["metoprolol", "atenolol", "carvedilol", "bisoprolol", "propranolol", "nebivolol"])
is_on_statin = any(drug in medication_name for drug in
    ["atorvastatin", "rosuvastatin", "simvastatin", "pravastatin", "lovastatin"])

Clinical Comorbidity Patterns

Common co-occurring conditions to watch for during analysis:

• Cardiorenal-metabolic overlap: Diabetes + Hypertension + CKD occur together in ~30% of diabetic patients
• Heart failure + CKD: eGFR < 30 limits medication options (spironolactone, SGLT2i dose adjustment)
• Diabetes + CAD: Statin therapy should be high-intensity; GLP-1/SGLT2i have cardiovascular benefit
• Atrial fibrillation + Heart failure: Common pairing; rate control with beta-blocker preferred

Guardrails

• These reference ranges are general guidelines based on published clinical guidelines (ADA, ACC/AHA, KDIGO), not diagnostic criteria
• Never state that a patient "has" a condition based on a lab value alone
• Always include the disclaimer: "This is for informational and research purposes, not clinical decision-making"
• When flagging care gaps, use language like "may warrant review" not "requires treatment"
• Acknowledge that CMS measure logic here is simplified -- production implementations use the full eCQM (electronic Clinical Quality Measure) specifications from CMS
• Lab reference ranges should defer to the performing laboratory's range when available