io.github.littleblakew/msds-chain

Check pairwise compatibility between a list of chemicals. Returns compatibility status (compatible / caution / incompatible) for each pair, along with specific hazard reasons and storage recommendations. Use this before an experiment to verify it is safe to use the listed chemicals together in the same lab setting. Args: chemicals: List of chemical names or CAS numbers, e.g. ["acetone", "methanol", "ethanol"] or ["67-64-1", "67-56-1"]

Get hazard and risk warnings for one or more chemicals. Returns GHS hazard classification, signal words (Danger/Warning), H-codes, flash point, toxicity, and recommended PPE. DRILL-DOWN tool: use this only when the user explicitly wants the raw structured hazard fields. For a broad "what are the hazards / is X dangerous / what PPE" question, prefer `ask_chemical_safety` — it returns one sourced answer instead of forcing you to chain several tools. Args: chemicals: List of chemical names or CAS numbers, e.g. ["acetone", "67-56-1"]

Check multi-region regulatory status for chemicals. Answers TWO separate questions per region — do not collapse them (CI-493): 1. `status` — is it on a RESTRICTION list (SVHC / REACH Annex XVII / CLP Annex VI / Prop 65 / China Catalogue of Hazardous Chemicals / JP CSCL / SG EPMA)? `restricted` on at least one restriction list, or a CMR hazard code `detected` only indirect evidence (occupational exposure limit, or an SDS Section 15 mention). 🔴 NOT a clearance and NOT a violation. `not_restricted` we DID check that region's restriction lists and it is not on them. `details` names which lists were checked. Lists we do not hold were not checked, so this is not a clearance either. `unverified` no check was performed — we hold no restriction list for that region (KR, TW, CA, AU), or the source could not be read. 🔴 Never report this as "not regulated". 2. `inventory` — is it on that region's EXISTING-SUBSTANCE inventory (TSCA / IECSC / KECL / DSL / AIIC / REACH registered)? Here the polarity is REVERSED: `on_inventory: true` registered there — about registration, not restriction `on_inventory: false` 🔴 the direction that needs attention: a substance absent from the inventory typically needs new-substance notification before import `on_inventory: null` we hold no inventory for that region Use this when preparing export documentation, compliance audits, or when working with chemicals that may be restricted in certain jurisdictions. 🔴 No result from this tool is ever, on its own, an import/export clearance. In particular an exposure limit (OSHA PEL) answers "how much exposure is allowed", not "is this substance permitted" — report it as evidence, never as compliance. Args: chemicals: List of chemical names or CAS numbers regions: Optional list of region codes to check, e.g. ["EU", "US", "CN"] Defaults to EU + US if not specified. Valid codes: EU, US, CN, JP, KR, CA, AU, TW

PREFERRED first tool for any general chemical-safety question — hazards, PPE, first aid, spill/exposure response, storage, disposal, "is X safe", "what do I need to handle Y", GHS interpretation, MSDS lookup. Returns ONE answer grounded in a specific supplier SDS, with the source (supplier + revision date) cited and any general knowledge clearly separated from what the SDS actually says. Use this FIRST for broad questions instead of chaining search_chemical_database + get_chemical_risk_warnings + get_ppe_recommendation — those are slower, produce a fragmented answer, and lose the single sourced citation. Reach for the granular tools only when the user explicitly wants just that one structured field. When presenting the answer, cite the returned source and do not add hazard, medical, or regulatory claims that are not in the tool output. A question may name more chemicals than one turn checks. When the result carries a non-empty `unchecked` list, you MUST say so before any conclusion and MUST NOT state or imply whether data exists for those — this turn did not look them up. Tell the user to ask about them separately. Args: question: Any chemical safety question, e.g. "What are the main hazards and PPE for TMAH?" "How should I store acetone and methanol in the same cabinet?" "A worker got hydrofluoric acid on their skin — first aid?"

Get PPE (Personal Protective Equipment) recommendations for chemicals. Returns specific glove types, eye protection, respiratory protection, and body protection requirements based on MSDS Section 8 data and GHS hazard codes. DRILL-DOWN tool: use this only when the user explicitly wants a standalone PPE list. A broad "what are the hazards and what PPE" question is answered in one sourced call by `ask_chemical_safety` — prefer that over chaining tools. Args: chemicals: List of chemical names or CAS numbers, e.g. ["acetone", "hydrochloric acid"] or ["67-64-1"]

Get storage and isolation guidance for chemicals. Returns storage class (flammable/oxidizer/corrosive/toxic/general), recommended cabinet type and color code, temperature requirements, incompatible materials for isolation, and specific storage instructions derived from SDS Section 7. Args: chemicals: List of chemical names or CAS numbers, e.g. ["acetone", "sulfuric acid"] or ["67-64-1"]

Get emergency response guidance for a chemical incident. Returns immediate actions, SDS-specific instructions from Section 4/5/6, and H-code-based guidance for three scenario types. Args: chemical: Chemical name or CAS number, e.g. "hydrochloric acid" scenario: Type of emergency — "spill" (leak/release), "fire", or "exposure" (skin/eye/inhalation first aid). Defaults to "spill". 🔴 Person first: material that reached a person is "exposure" even when the user says "spilled" — only "exposure" returns the substance-specific antidote protocol (CI-579).

Get occupational exposure limits (OEL/TLV/PEL/MAC) for chemicals. Returns TWA, STEL, and Ceiling values from multiple standards: - OSHA PEL (US) - ACGIH TLV (International) - EU SCOEL IOELV - Japan 産衛研 - China GBZ Args: chemicals: List of chemical names or CAS numbers region: Optional filter — "US", "EU", "JP", "CN", or "INT"

Get UN transport classification for chemicals (dangerous goods shipping). Returns UN number, proper shipping name, hazard class, packing group, and transport mode details (ADR road, IATA air, IMDG sea). Args: chemicals: List of chemical names or CAS numbers

Run a full MSDS safety audit for a list of chemicals and return a session id. Creates a persistent audit session on MSDS Chain, runs pairwise compatibility and risk analysis across all chemicals, and returns a session_id that can later be passed to `get_audit_report` to fetch the signed PDF report URL. Use this when the user wants an archivable, signed record of a safety review (e.g. for SOPs, compliance audits, or to share with a PI / safety officer), rather than a one-off Q&A. Args: experiment_name: Short human-readable label for the audit, e.g. "Grignard prep — 2026-04-16" or "Solvent screening #3". chemicals: List of chemical names or CAS numbers to include in the audit, e.g. ["acetone", "methanol", "67-64-1"]. Returns: Session id + compatibility summary (compatible/caution/incompatible pair counts + top warnings). An API key must be configured (MSDS_API_KEY) so the session is bound to your account and the report is retrievable.

Get a short-lived signed URL to download an archivable PDF safety report. Two ways to call it: - **No arguments** — builds the report from the chemicals this user has analysed over the last 7 days (compatibility / risk / regulatory / protocol checks). Use this whenever the user asks for "a report", "something for the file", "a document for my PI / safety officer" and you do not already hold a session id. You do NOT need to ask them to list the chemicals again. - **With a session_id** — the classic path, for a session you just created with `create_audit_session`. The PDF contains the chemicals, compatibility matrix, risk warnings and session metadata, and is signed, so it can be filed as a compliance record. Args: session_id: Optional. The session id returned by `create_audit_session`, e.g. "DEMO-A1B2C3D4". Omit to report on recent analyses. Returns: A signed URL valid for ~5 minutes. The session must be owned by the API key's user (MSDS_API_KEY).

Search the MSDS Chain database for a specific chemical. Returns structured information: CAS number, chemical name, NFPA ratings (flammability, health, reactivity), GHS classification, and whether full MSDS data is available. Use this to verify a chemical is in the database before running compatibility or risk checks, or to get the canonical CAS number for a chemical name. Args: query: Chemical name, synonym, or CAS number, e.g. "methanol", "wood alcohol", "67-56-1"

Look up GHS hazard data for a chemical NOT in the MSDS Chain database, via PubChem. Use this ONLY as a fallback when search_chemical_database returns no result. The data is PubChem's AGGREGATED GHS classification, clearly labelled source="pubchem" — it is NOT a signed supplier SDS. Present it to the user as PubChem-sourced and unverified; prefer uploading a real SDS (upload_msds_pdf) when accuracy matters. Args: chemical_name: Chemical name, e.g. "acetonitrile" cas_number: CAS number, e.g. "75-05-8" (used first if provided)

Retrieve a specific SDS (Safety Data Sheet) section for a chemical. The 16 standard GHS-SDS sections are: 1. Identification 2. Hazard(s) identification 3. Composition / ingredients 4. First-aid measures 5. Fire-fighting measures 6. Accidental release measures 7. Handling and storage 8. Exposure controls / PPE 9. Physical and chemical properties 10. Stability and reactivity 11. Toxicological information 12. Ecological information 13. Disposal considerations 14. Transport information 15. Regulatory information 16. Other information Use this when you need detailed data from a specific section rather than a general safety overview. Args: chemical: Chemical name or CAS number section: SDS section number (1-16)

Suggest safer alternatives for a chemical, considering its intended use. Returns 2-4 alternative chemicals with: name, CAS number, why it's safer (lower toxicity, higher flash point, non-CMR, etc.), any trade-offs (cost, availability, performance), and relevant regulatory context (e.g., REACH SVHC substitution requirement). Use this when a chemical is flagged as high-risk, restricted, or when the user is exploring greener chemistry options. Args: chemical: Chemical name or CAS number to find alternatives for use_case: Optional context about how the chemical is being used, e.g. "degreasing solvent", "extraction solvent for organic synthesis", "cleaning agent for labware"

Extract and validate chemical names from a protocol or experiment description. Parses free-text or code (e.g., Opentrons Python protocol, lab notebook entry, SOP paragraph) to identify all mentioned chemicals, then checks each against the MSDS Chain database. Returns a structured list with: chemical name as mentioned, canonical name, CAS number (if found), and whether full safety data is available. Use this as the FIRST step before calling batch_safety_check or check_chemical_compatibility — it saves the user from manually listing chemicals. A protocol routinely names more chemicals than one turn checks. The result carries an `unchecked` list of the ones this turn did NOT look up. When it is non-empty you MUST report those chemicals as "not checked" before any conclusion, and you MUST NOT say or imply that we lack data or a record for them — nothing was looked up. Tell the user to re-send them separately or in smaller batches. Args: protocol_text: Any text containing chemical names — can be a Python script, a natural language protocol description, or a reagent list. Maximum ~4000 characters.

Determine the safe order for mixing/adding two chemicals. Returns the recommended addition sequence, the dangerous sequence to avoid, reasoning (exothermic potential, gas evolution, splashing risk), and any required precautions (cooling, dilution rate, inert atmosphere). Classic examples: "acid into water, never water into acid"; "add oxidizer to substrate slowly, not the reverse". Use this when reviewing liquid transfer steps in an Opentrons protocol or any manual procedure involving sequential addition of reagents. Args: chemical_a: First chemical name or CAS number chemical_b: Second chemical name or CAS number context: Optional context about the procedure, e.g. "diluting for titration" or "quenching a reaction"

Get waste classification and disposal guidance for chemicals. Returns waste category (halogenated/non-halogenated/acidic/alkaline/ heavy metal/oxidizing/reactive), disposal method, container requirements, and incompatible waste streams that must NOT be mixed. Based on SDS Section 13 (Disposal Considerations) data. Use this after an experiment to determine proper waste segregation and disposal procedures for the chemicals used. Args: chemicals: List of chemical names or CAS numbers, e.g. ["dichloromethane", "acetone", "sulfuric acid"]

Compare a chemical's two most recent SDS versions and report whether its hazard data changed (and whether the change is relevant to safety verdicts). Identifies H-code additions/removals between the latest two on-record SDS revisions, and flags whether the change could affect a prior compatibility or risk conclusion. Use when a user asks if a chemical's safety data has been updated, or to check whether a past safety conclusion might be affected by an SDS revision. Args: chemical: Chemical name or CAS number, e.g. "hydrogen peroxide" or "7722-84-1". supplier: Optional SDS supplier/manufacturer to disambiguate (e.g. "Sigma-Aldrich"). region: Optional region code to narrow the lookup (e.g. "US", "EU", "JP", "CN"). version_old / version_new: DEPRECATED and ignored — an arbitrary version pair cannot be compared. Supplying them adds an explicit note to the reply saying the request was not honoured; they never change what is compared.

Upload an MSDS/SDS PDF file to MSDS Chain and get AI-parsed safety data. Parses the PDF with an LLM to extract: chemical name, CAS number, GHS hazard classification, NFPA ratings, flash point, LD50, H-codes, PPE requirements, storage conditions, incompatibilities, and safety rules. If no session_id is provided, a new audit session is automatically created and its ID is returned so you can call `get_audit_report` later. Requires MSDS_API_KEY — the parsed data is stored under your account. Args: pdf_source: One of, tried in this order: 1. A publicly reachable HTTPS URL of the PDF (fetched server-side). 2. **Inline file bytes, base64-encoded** — use this when you already have the PDF's bytes in this conversation (e.g. the user just uploaded a PDF to you and you can read/attach it), which is the common case for remote clients like ChatGPT or claude.ai where the file lives in YOUR sandbox with no public URL. Pass either a data URI (`data:application/pdf;base64,<...>`) or a bare base64 string of the raw PDF bytes. Max 10 MB decoded. 3. A local file path (e.g. "/tmp/acetone_sds.pdf") — works ONLY for a self-hosted stdio server running on the same machine as the file. Do NOT pass a path from the user's machine or a client-side sandbox to the hosted server; it will not exist there. If you cannot get a URL or the raw bytes, send the user to the web uploader instead. Rule of thumb: if you (the model) can see/hold the PDF's bytes right now, base64-encode them and pass that — don't go looking for a local path that only exists on the user's machine, not the server's. session_id: Existing session ID to attach this upload to. If omitted, a new session is created automatically. experiment_name: Label for the auto-created session (ignored if session_id is provided). Defaults to "MCP Upload". filename: Optional display filename, used when pdf_source is inline base64 content (which has no filename of its own). Defaults to "upload.pdf" if omitted. Returns: Parsed chemical info (name, CAS, risk level, key fields) and session_id. If parsing partially failed, missing fields are listed so you can follow up with `ask_chemical_safety` for the gaps.

Run a comprehensive safety check on a list of chemicals in one call. Returns a combined report with: - Pairwise compatibility matrix (compatible/caution/incompatible) - Key risk warnings per chemical, with the source SDS for each It does NOT return PPE or storage grouping — for those call `get_ppe_recommendation` / `get_storage_guidance`. (This list previously advertised both; the description is what you read when choosing a tool, so naming an output that never arrives invites answering from nothing.) Good first call when reviewing an experiment protocol or Opentrons deck layout: it covers the pairwise interactions in one round-trip. Args: chemicals: List of chemical names or CAS numbers (2-20 items), e.g. ["acetone", "sulfuric acid", "sodium hydroxide", "methanol"]

Check which international regulatory lists a chemical appears on. Searches 23 lists — 8 jurisdictions plus 3 international conventions: - US: EPA TSCA Inventory, OSHA PEL, California Prop 65 - EU: SVHC Candidate List, REACH Annex XVII, REACH Annex XIV, REACH registered substances, CLP Annex VI, Seveso III, Water Framework Directive priority substances - APAC: China Catalogue of Hazardous Chemicals, China IECSC, Japan CSCL, Korea KECL, Australia AIIC, Singapore EPMA - Americas: Canada DSL - Conventions: Rotterdam PIC, Stockholm POPs, Montreal Protocol - Dual-use / export control: CWC Schedules 1/2/3, Australia Group precursors It also reports presence in the EPA CompTox Dashboard, which is an identifier resource rather than a regulatory list. Coverage limits, so the answer is not over-read: - There is NO Taiwan and NO IARC coverage. Do not infer either from this tool. - The lists are a curated snapshot, not a live regulatory feed. A chemical missing from a list means "not found in our copy of that list", never "not regulated". Returns a summary of all matching lists, helping you understand a chemical's global regulatory footprint at a glance. Args: chemical: Chemical name or CAS number

Return a signed download URL for the original SDS/MSDS PDF of a chemical. The URL is valid for approximately 5 minutes and can be opened in a browser or downloaded with `curl -O`. The response also includes the document's source (supplier, region, revision date) so the provenance is clear. If only parsed text is available (no original PDF on file), the tool says so and suggests using `get_sds_section` to query specific sections instead. If the chemical is not in the database at all, the tool suggests uploading an SDS PDF via `upload_msds_pdf`. Args: chemical: Chemical name or CAS number, e.g. "acetone" or "67-64-1"