tooluniverse-product-safety-surveillance - Claude MCP Skill

# Product Safety Surveillance (multi-product, openFDA)

Retrieve and interpret post-market safety records across **every FDA-regulated
product class except drug-AE signal mining**: medical devices, food / dietary
supplements / cosmetics, veterinary drugs, and drug supply (shortages), plus
cross-product enforcement/recall reports.

**KEY PRINCIPLES**
1. **Decide the product class first.** Device? Food/supplement/cosmetic? Vet drug? Drug shortage? Recall? The class picks the tool.
2. **Build a valid Lucene query.** openFDA uses field-scoped `field:value` terms; combine with a space-separated `AND`. Phrases and special characters need care (see Query Grammar).
3. **Retrieve, then interpret.** These are spontaneous/voluntary reports. Report the records and their fields; never assert causation or rates.
4. **Cite every record** with the tool name, the openFDA endpoint, the query used, and the `total` hit count from `meta.results.total`.
5. **Stay in scope.** If the request is drug-AE signal detection (PRR/ROR/IC), STOP and point to `tooluniverse-pharmacovigilance` / `tooluniverse-adverse-event-detection`.

---

## When to Use vs When NOT to Use

**USE for:**
- Device adverse events (MAUDE): "adverse events / malfunctions / deaths for [device]"
- Device recalls & enforcement: "device recalls for [firm]", "Class I device recalls"
- Device clearance context: "510(k) clearances for [device type]"
- Food / dietary-supplement / cosmetic adverse events (CAERS): "supplement reactions", "cosmetic adverse events for [brand]"
- Food recalls/enforcement: "food recall for listeria / undeclared allergen"
- Veterinary drug adverse events: "adverse events for [drug] in dogs"
- Drug shortages: "is [drug] in shortage", "injectables on current shortage"
- Drug recalls/enforcement: "drug recalls for contamination"

**DO NOT USE for** (point elsewhere):
- Drug adverse-event SIGNAL detection / disproportionality (PRR, ROR, IC) → `tooluniverse-pharmacovigilance` or `tooluniverse-adverse-event-detection`
- Drug-AE association strength scoring, demographic risk stratification of drug AEs → same two skills
- Drug efficacy, mechanism, pharmacogenomics → other tooluniverse-* skills

This skill **retrieves and interprets multi-product safety records**. It does not compute drug-AE signal statistics.

---

## Tool Map (which tool for which question)

| Product class | Question | Tool | openFDA endpoint |
|---|---|---|---|
| Device | Adverse events / malfunctions / deaths (MAUDE) | `OpenFDA_search_device_adverse_events` | `/device/event.json` |
| Device | Recalls | `OpenFDA_search_device_recalls` | `/device/recall.json` |
| Device | Enforcement / recall reports | `OpenFDA_search_device_enforcement` | `/device/enforcement.json` |
| Device | 510(k) clearances (context) | `OpenFDA_search_device_510k` | `/device/510k.json` |
| Food/supplement/cosmetic | Adverse events (CAERS) | `OpenFDA_search_food_adverse_events` | `/food/event.json` |
| Food | Enforcement / recall reports | `OpenFDA_search_food_enforcement` | `/food/enforcement.json` |
| Veterinary | Animal drug adverse events | `OpenFDA_search_animalvet_adverse_events` | `/animalandveterinary/event.json` |
| Drug supply | Shortages | `OpenFDA_search_drug_shortages` | `/drug/shortages.json` |
| Drug | Enforcement / recall reports | `OpenFDA_search_drug_enforcement` | `/drug/enforcement.json` |
| Drug | Adverse events (raw FAERS records) | `OpenFDA_search_drug_events` | `/drug/event.json` |
| Drug | Labels | `OpenFDA_search_drug_labels` | `/drug/label.json` |

All tools take a Lucene `search` string plus optional `limit` and `skip`. All are keyless and verified live.

---

## openFDA Query Grammar (CRITICAL — read before querying)

- **Field-scoped term:** `field:value` (e.g. `event_type:Death`, `status:Current`).
- **Nested fields use dot paths:** `device.generic_name:pacemaker`, `products.industry_name:Cosmetics`, `animal.species:Dog`, `reaction.veddra_term_name:Vomiting`, `drug.active_ingredients.name:carprofen`.
- **Combine terms with a SPACE-separated `AND`** (verified working): `device.generic_name:pacemaker AND event_type:Death`.
  - **Do NOT use `+AND+`** — the `+`-joined boolean form errors through these tools. Use a literal space around `AND`.
- **Multi-word values:** join with `+` only for adjacency within a single field value (e.g. `device.generic_name:infusion+pump`). This is matched as tokens, not an exact phrase.
- **Avoid raw special characters** (`(`, `)`, `/`, leading `+`) inside values — they break the query. Pick a simpler token (e.g. `products.industry_name:Dietary` instead of the full `Dietary Conventional Foods/Meal Replacements`).
- **Dates** are strings: device AE/MAUDE use `YYYYMMDD` (e.g. `date_received`); recalls/enforcement use `YYYY-MM-DD` (e.g. `event_date_initiated`, `recall_initiation_date`).
- **Result envelope:** every successful call returns `{status:"success", data:{meta:{results:{total, skip, limit}}, results:[...]}}`. Read the hit count from `data.meta.results.total`.
- **Counts/aggregations:** native openFDA supports `&count=<field>`; these TU wrappers center on `search`. To rank terms, retrieve a batch (e.g. `limit:100`) and tally the field yourself in Python.

---

## Interpretation Tables (raw openFDA field → meaning)

### Medical devices — MAUDE adverse events (`/device/event.json`)
| Field | Meaning |
|---|---|
| `event_type` | `Death`, `Injury`, `Malfunction`, or `No answer provided`. Death/Injury = patient harm; Malfunction = device failure without (reported) harm. |
| `device[].generic_name` / `device[].brand_name` | Device category / trade name. |
| `device[].manufacturer_d_name` | Device manufacturer. |
| `patient[]` | Patient-level outcome data (may be sparse). |
| `mdr_text[].text` | Narrative; `text_type_code` distinguishes event description vs manufacturer narrative. |
| `report_number` | MAUDE report id. **Duplicate / follow-up reports of the same event are common** — do not count reports as distinct events. |
| `date_received` | `YYYYMMDD` FDA received date. |

### Medical devices — recalls (`/device/recall.json`)
| Field | Meaning |
|---|---|
| `product_description` | What was recalled. |
| `recalling_firm` | Firm issuing the recall. |
| `recall_status` | e.g. `Open`, `Terminated`. Terminated = FDA closed the action. |
| `product_code` | FDA device product code. |
| `k_numbers[]` | Associated 510(k) clearance numbers. |
| `root_cause_description` | FDA root-cause category (e.g. `Labeling design`). |
| `event_date_initiated` | `YYYY-MM-DD` recall start. |

### Enforcement reports (device / drug / food `/.../enforcement.json`)
| Field | Meaning |
|---|---|
| `classification` | Recall severity: `Class I` (serious/fatal hazard), `Class II` (temporary/reversible), `Class III` (unlikely to cause harm). |
| `status` | `Ongoing` / `Terminated` / `Completed`. |
| `reason_for_recall` | Why recalled. |
| `product_description` | Recalled product. |
| `recalling_firm` | Firm. |

### Food / supplement / cosmetic — CAERS adverse events (`/food/event.json`)
| Field | Meaning |
|---|---|
| `reactions[]` | MedDRA reaction terms (British spelling, e.g. `Diarrhoea`, `Nausea`). |
| `outcomes[]` | e.g. `Hospitalization`, `Life Threatening`, `Disability`, `Death`, `Other Serious or Important Medical Event`, `Visited an ER`. |
| `products[].industry_name` | Product category (`Cosmetics`, `Dietary Conventional Foods/Meal Replacements`, `Milk/Butter/Dried Milk Prod`, …). |
| `products[].role` | `SUSPECT` (implicated) vs `CONCOMITANT` (also consumed). |
| `products[].name_brand` | Brand name. |
| `consumer` | `age`, `gender` of the consumer (often sparse). |

### Veterinary — animal drug adverse events (`/animalandveterinary/event.json`)
| Field | Meaning |
|---|---|
| `animal.species` | `Dog`, `Cat`, `Horse`, … |
| `animal.gender` | Animal sex. |
| `number_of_animals_affected` | Count in the report. |
| `reaction[].veddra_term_name` | VeDDRA clinical sign (e.g. `Vomiting`, `Diarrhoea`). |
| `drug[].brand_name` / `drug[].active_ingredients[].name` | Implicated product / active. |
| `drug[].used_according_to_label` / `off_label_use` | Label vs off-label use. |

### Drug shortages (`/drug/shortages.json`)
| Field | Meaning |
|---|---|
| `status` | `Current` or `Resolved`. |
| `availability` | e.g. `Unavailable`, `Limited`. |
| `generic_name` | Drug in shortage. |
| `shortage_reason` | e.g. `Delay in shipping of the drug`, `Demand increase for the drug`. |
| `dosage_form` | e.g. `Injection`, `Tablet`. |
| `therapeutic_category[]` | Clinical category. |
| `company_name` | Manufacturer. |
| `update_type` / `initial_posting_date` / `update_date` | Posting metadata. |

---

## Workflow

1. **Classify the product** from the request (device / food-supplement-cosmetic / vet / drug shortage / recall).
2. **Pick the tool** from the Tool Map.
3. **Build the Lucene query** following Query Grammar (single field for a first pass; add ` AND ` for combinations). Keep values simple; avoid special characters.
4. **Run it** and read `data.meta.results.total` and `data.results[]`.
5. **Interpret** the fields with the table above. For severity: device `event_type:Death`; enforcement `classification:Class I`; CAERS `outcomes:Death`/`Hospitalization`; shortage `status:Current`.
6. **Summarize and cite.** Report counts, key fields, the query used, and the LIMITATIONS caveat. To rank terms, pull `limit:100` and tally in Python (no `count` aggregation in these wrappers).
7. **If out of scope** (drug-AE signal/PRR/ROR), stop and route to the pharmacovigilance skills.

---

## Worked Examples (verified live)

### Example 1 — Device deaths for a device type (MAUDE)
> "Are there any reported deaths in adverse-event reports for pacemakers?"

```
OpenFDA_search_device_adverse_events {"search":"device.generic_name:pacemaker AND event_type:Death","limit":1}
```
Real output (abbrev): `status:success`, `meta.results.total = 16619`; first record `event_type = Death`, `device.generic_name = DEFIBRILLATOR/PACEMAKER`.
Interpretation: 16,619 MAUDE reports match a pacemaker device with a `Death` event type. These are spontaneous reports — duplicates likely, and "Death" means a death was reported in temporal association, not that the device caused it.

### Example 2 — Device recalls for a firm
> "What device recalls has Medtronic Navigation issued?"

```
OpenFDA_search_device_recalls {"search":"recalling_firm:Medtronic","limit":1}
```
Real output (abbrev): `total = 1896`; first record `recall_status = Terminated`, `product_code = HAW`, `root_cause_description = Labeling design`, `k_numbers = ["K990214"]`, `event_date_initiated = 2011-01-20`, `product_description` = a tactile probe for spine surgery.
Interpretation: 1,896 recall records match firms containing "Medtronic". `recall_status: Terminated` means FDA has closed this action; the root cause was a labeling-design issue.

### Example 3 — Drug shortage lookup for an injectable
> "Is ketorolac injection in shortage right now?"

```
OpenFDA_search_drug_shortages {"search":"dosage_form:Injection AND status:Current","limit":1}
```
Real output (abbrev): `total = 799`; first record `generic_name = Ketorolac Tromethamine Injection`, `status = Current`, `shortage_reason = Delay in shipping of the drug`, `availability = Unavailable`, `company_name = Fresenius Kabi USA, LLC`.
Interpretation: 799 current shortage records are injectables; ketorolac tromethamine injection is currently in shortage (status `Current`, availability `Unavailable`) due to a shipping delay.

### Example 4 — Supplement / cosmetic CAERS reactions
> "Are there CAERS adverse-event reports implicating cosmetics?"

```
OpenFDA_search_food_adverse_events {"search":"products.industry_name:Cosmetics","limit":1}
```
Real output (abbrev): `total = 52214`; first record `products[].industry_name = Cosmetics`, `products[].role = SUSPECT`, `outcomes = ["Hospitalization","Other Serious or Important Medical Event"]`.
Interpretation: 52,214 CAERS reports name a cosmetic product as `SUSPECT`. CAERS is voluntary; a `SUSPECT` role reflects the reporter's attribution, not a verified causal link.

### Example 5 — Veterinary adverse events for a drug in a species
> "What adverse events are reported for carprofen in dogs?"

```
OpenFDA_search_animalvet_adverse_events {"search":"drug.active_ingredients.name:carprofen AND animal.species:Dog","limit":1}
```
Real output (abbrev): `total = 46469`; first record `animal.species = Dog`, `reaction[].veddra_term_name` includes `Leucocytosis NOS`, `Neutrophilia`, `Depression`, `Elevated alanine aminotransferase (ALT)`.
Interpretation: 46,469 veterinary reports match carprofen-containing products in dogs. VeDDRA terms describe reported clinical signs; counts reflect reporting, not incidence.

---

## Limitations (state these in every report)

- **Spontaneous / voluntary reports.** MAUDE (device), CAERS (food/supplement/cosmetic), FAERS (drug), and the animal/vet system are passive surveillance. Reports are **unverified** and a report is not a confirmed causal event.
- **No causation, no denominator.** Counts (`meta.results.total`) are report counts, not incidence or rates. There is no exposure denominator, so you cannot compute risk.
- **Reporting bias.** Serious events, new products, recalls, and media/regulatory attention drive reporting spikes (Weber effect). High counts may reflect usage volume or attention, not hazard.
- **Duplicate reports.** MAUDE in particular contains follow-up/duplicate reports of the same event; do not treat report counts as event counts.
- **CAERS voluntary & sparse.** Consumer/age/gender fields are often missing; `SUSPECT` role is reporter attribution.
- **This skill does not compute signal statistics** (PRR/ROR/IC). For drug-AE disproportionality use `tooluniverse-pharmacovigilance` / `tooluniverse-adverse-event-detection`.
- **Data currency:** each response carries a `meta.last_updated` date; openFDA lags real-world events.

See `references/openfda_fields.md` for the full per-endpoint field reference and additional query examples.

---

## References

- openFDA: https://open.fda.gov
- MAUDE (device adverse events): https://www.fda.gov/medical-devices/mandatory-reporting-requirements-manufacturers-importers-and-device-user-facilities
- Device recalls / 510(k): https://www.fda.gov/medical-devices
- CAERS (food/supplement/cosmetic): https://www.fda.gov/food/compliance-enforcement/cfsan-adverse-event-reporting-system-caers
- Drug shortages: https://www.fda.gov/drugs/drug-shortages
- Recall classifications: https://www.fda.gov/safety/industry-guidance-recalls