mims-harvard/tooluniverse/tooluniverse-chemical-compound-retrieval

Chemical Compound Information Retrieval

Retrieve comprehensive chemical compound data with proper disambiguation and cross-database validation.

LOOK UP DON'T GUESS: Never assume a CID, ChEMBL ID, or molecular property value. Always retrieve from PubChem/ChEMBL.

English-first: Always use English compound names in tool calls. Respond in user's language.

Domain Reasoning: Disambiguation

"Aspirin" = one compound. "Vitamin D" = multiple forms (D2/D3/active metabolite). For generic class names (steroids, vitamins, acids), present candidates and confirm before proceeding.

Workflow

Phase 0: Clarify (only if highly ambiguous -- skip for unambiguous names or specific IDs)
Phase 1: Disambiguate → resolve PubChem CID + ChEMBL ID
Phase 2: Retrieve data (silent)
Phase 3: Report compound profile

Phase 1: Disambiguation

# By name
result = tu.tools.PubChem_get_CID_by_compound_name(compound_name=name)
# By SYSTEMATIC (IUPAC) name -> structure, deterministic parser (no DB lookup)
opsin = tu.tools.OPSIN_name_to_structure(name="2-acetoxybenzoic acid")
# Returns {parsed, smiles, inchi, inchikey}; use the SMILES/InChIKey to anchor a
# PubChem_get_CID_by_SMILES lookup. Trade/trivial names give parsed=false -> fall
# back to PubChem_get_CID_by_compound_name for those.
# By SMILES
result = tu.tools.PubChem_get_CID_by_SMILES(smiles=smiles)
# Cross-reference
chembl_result = tu.tools.ChEMBL_search_molecules(query=name, limit=5)

Verify: CID + ChEMBL ID + canonical SMILES + stereochemistry + salt forms.

Phase 2: Data Retrieval

PubChem: PubChem_get_compound_properties_by_CID, PubChemBioAssay_get_assay_summary, PubChemTox_get_acute_effects, PubChem_get_compound_2D_image_by_CID

ChEMBL: ChEMBL_get_compound_record_activities, ChEMBL_get_molecule_targets, ChEMBL_get_assay_activities

Optional: PubChem_get_associated_patents_by_CID, PubChem_search_compounds_by_similarity

Phase 3: Report

Compound Profile with: Identity (CID, ChEMBL ID, IUPAC, SMILES), Chemical Properties (MW, LogP, HBD, HBA, PSA, Lipinski), Bioactivity (targets, IC50/Ki), Drug Info (if approved), Data Sources.

Fallback Chains

Evidence Grading

Bioactivity: ChEMBL > PubChem BioAssay for curated data. IC50/Ki < 100nM = potent, 100nM-1uM = moderate, >10uM = weak. Lipinski violations reduce oral bioavailability but don't disqualify.

SMILES Verification

Always verify novel SMILES: python3 src/tooluniverse/tools/smiles_verifier.py --smiles "SMILES_STRING". Invalid SMILES produce wrong results or cryptic errors.

Identifier Resolution and Cross-Database Referencing

Beyond PubChem/ChEMBL, two more tools resolve identifiers when a name doesn't hit in PubChem or you need cross-references across other chemical databases:

• `NCICACTUS_resolve` (NCI CACTUS resolver) — converts between chemical

names (IUPAC or common), SMILES, InChI, InChIKey, CAS number, and molecular formula. Verified live: NCICACTUS_resolve(identifier="ibuprofen", representation="smiles") → CC(C)Cc1ccc(cc1)C(C)C(O)=O; also resolves a CAS number ("50-78-2") straight to an IUPAC name ("2-acetyloxybenzoic acid", i.e. aspirin) or an InChIKey to a formula. Useful as a second name-resolution path alongside OPSIN_name_to_structure and PubChem_get_CID_by_compound_name — CACTUS handles CAS numbers and trivial names OPSIN can't parse.

• `UniChem_search_compound` / `UniChem_connectivity_search` — given an

InChIKey (or a source-database compound ID), returns cross-references across UniChem's 25+ registered source databases (ChEMBL, DrugBank, PubChem, Wikipedia, ChEBI, etc. — verified live via UniChem_list_sources). connectivity_search additionally finds compounds sharing the same connectivity layer (same skeleton, different stereochemistry/salt/isotope) — use this when you want "the same molecule under any name/form" rather than an exact match. Verified live on aspirin's InChIKey (BSYNRYMUTXBXSQ-UHFFFAOYSA-N): both returned real cross-database records including a Wikipedia link.

Chained identifier workflow (real values): NCICACTUS_resolve(identifier="aspirin", representation="smiles") → CC(=O)Oc1ccccc1C(O)=O → resolve the same identifier with representation="stdinchikey" → real result "InChIKey=BSYNRYMUTXBXSQ-UHFFFAOYSA-N" (note the `InChIKey=` prefix — verified live; strip it before passing the bare key to another tool) → feed the bare BSYNRYMUTXBXSQ-UHFFFAOYSA-N into UniChem_search_compound for cross-database IDs → PubChem_get_CID_by_SMILES to re-anchor in PubChem if needed.

Cheminformatics Calculations and Structure Visualization

For calculations and rendering beyond property lookup:

• `RDKit_pharmacophore_features` — extracts pharmacophore feature centers

(HBD, HBA, aromatic, hydrophobic, etc.) from a SMILES via SMARTS matching. Verified live on aspirin (CC(=O)Oc1ccccc1C(=O)O): 1 HBD with atom index, method documented as "SMARTS-based pharmacophore features".

• `RDKit_matched_molecular_pair` — given two SMILES, finds the single-cut

MMP transformation between them (Hussain-Rea algorithm) plus their Tanimoto similarity — useful for "what single substitution turns compound A into compound B" (SAR analysis).

• `visualize_molecule_2d` — renders a 2D structure (from SMILES, InChI, or

a molecule name) to PNG/SVG/interactive HTML. Verified live: returns an embedded HTML visualization on success.

• `visualize_molecule_3d` — renders a 3D structure via RDKit + py3Dmol.

Requires `py3Dmol` installed — verified live that without it, the tool returns a clean {"status": "error", ...: "py3Dmol is not installed. Please install it with: pip install py3Dmol"} rather than crashing; check for this before assuming a visualization request has failed for another reason.

Tool Reference

PubChem: PubChem_get_CID_by_compound_name, PubChem_get_CID_by_SMILES, PubChem_get_compound_properties_by_CID, PubChem_get_compound_2D_image_by_CID, PubChemBioAssay_get_assay_summary, PubChemTox_get_acute_effects, PubChem_get_associated_patents_by_CID, PubChem_search_compounds_by_similarity, PubChem_search_compounds_by_substructure

ChEMBL: ChEMBL_search_drugs, ChEMBL_get_molecule, ChEMBL_get_activity, ChEMBL_get_target, ChEMBL_search_targets, ChEMBL_search_assays

Name parsing: OPSIN_name_to_structure (param name) — deterministic IUPAC/systematic-name → SMILES/InChI/InChIKey parser; the go-to for resolving a systematic name to structure without a DB round-trip. Trade/trivial names return parsed=false (use PubChem name lookup for those).

Identifier resolution & cross-referencing: NCICACTUS_resolve, UniChem_search_compound, UniChem_connectivity_search, UniChem_list_sources

Cheminformatics & visualization: RDKit_pharmacophore_features, RDKit_matched_molecular_pair, visualize_molecule_2d, visualize_molecule_3d