tooluniverse-product-safety-surveillance

# 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` | | Device | Unique Device Identifier (UDI) lookup | `OpenFDADevice_search_udi` | -- | | Device | US regulatory class (1/2/3) | `OpenFDADevice_get_classification` | -- | | Device | Premarket Approval (PMA, Class 3 devices) | `OpenFDADevice_search_pma` | -- | | 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. **Note**: `OpenFDADevice_search_recalls`/`_search_adverse_events`/`_search_510k` return the same underlying openFDA data as `OpenFDA_search_device_recalls`/`_device_adverse_events`/`_device_510k` above (two independently-added wrappers over the same endpoints) — either works, no need to call both. Use whichever is already in your loaded toolset; the `OpenFDADevice_*` family additionally has the three UDI/classification/PMA tools with no equivalent in the other family. --- ## 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`.