Guide pharmacogenomics (PGx) research -- drug-gene interaction lookup, CPIC guideline retrieval, variant-drug annotation, allele function status, FDA biomarker labeling, and clinical dosing recommendations. Covers the full CPIC-to-PharmGKB-to-clinical-recommendation workflow. Use when users ask about pharmacogenomics, drug-gene interactions, CPIC guidelines, genotype-guided dosing, PGx biomarkers, CYP enzyme phenotypes, or star allele interpretation.
When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.
Systematic PGx analysis: resolve gene-drug pairs, retrieve CPIC dosing guidelines, annotate alleles and variants with PharmGKB, check FDA PGx biomarker labeling, and generate evidence-graded clinical recommendations.
Input (gene/drug/variant/phenotype)
|
v
Phase 0: Disambiguation (resolve gene symbols, drug names, rsIDs)
|
v
Phase 1: Gene-Drug Pair Identification (CPIC pairs + evidence levels)
|
v
Phase 2: Guideline & Dosing Retrieval (CPIC recommendations + PharmGKB)
|
v
Phase 3: Allele & Variant Annotation (star alleles, function, activity scores)
|
v
Phase 4: FDA Biomarker Labeling (regulatory PGx status)
|
v
Phase 5: Cross-Database Enrichment (EpiGraphDB, DGIdb, OpenTargets PGx)
|
v
Phase 6: Report (evidence-graded clinical summary)
Resolve user input to canonical identifiers before querying PGx databases.
PharmGKB_search_genes: query (string REQUIRED, e.g., "CYP2D6"). Returns {status, data: [{id, symbol, name}]}.
PharmGKB_search_drugs: query (string REQUIRED, e.g., "codeine"). Returns {status, data: [{id, name, types}]}.
PharmGKB_search_variants: query (string REQUIRED, rsID e.g., "rs1799853"). Returns {status, data: [{id, symbol, changeClassification, clinicalSignificance}]}.
CPIC_get_drug_info: name (string REQUIRED, lowercase, e.g., "codeine"). Returns drug identifiers including drugid, rxnormid, drugbankid, atcid, guidelineid, and flowchart URL.
guidelineid directly from a drug name.CPIC_get_gene_info: symbol (string REQUIRED, e.g., "CYP2D6"). Returns gene coordinates, PharmGKB/HGNC/Ensembl IDs, lookupmethod (ACTIVITY_SCORE or PHENOTYPE), and allele frequency methodology.
CPIC_search_gene_drug_pairs: gene_symbol (string), cpiclevel ("A"/"B"/"C"/"D"), limit (int, default 50). Returns {status, data: [{genesymbol, drugid, cpiclevel, guidelineid, pgxtesting, clinpgxlevel, usedforrecommendation}]}.
eq. prefix.gene or gene_symbol both resolve to genesymbol.CPIC_get_gene_drug_pairs: genesymbol (string REQUIRED). Returns ALL pairs for one gene including drug: {name}, citations, guidelineid.
CPIC_list_drugs: No params. Returns all drugs with guideline IDs. Use for browsing.
CPIC_list_pgx_genes: No params. Returns all PGx genes curated by CPIC with symbol, lookupmethod, ensemblid.
EpiGraphDB_get_gene_drug_associations: gene_name (string REQUIRED, e.g., "CYP2D6"). Returns {status, data: {gene_drug_associations: [{gene, drug, source, pharmgkb_evidence, cpic_level, pgx_on_fda_label, guideline}]}}.
Don't memorize guideline IDs. Use CPIC_list_guidelines(gene="CYP2D6") or CPIC_list_guidelines(drug="codeine") to discover them. Each result includes both the numeric id (for CPIC_get_recommendations) and the clinpgxid string (for PharmGKB_get_dosing_guidelines).
CPIC_get_recommendations (CPICGetRecommendationsTool): guideline_id (integer, OR drug/drug_name string for auto-resolution), limit (int, default 50), offset (int). Returns {status, data: {guideline_id, recommendations: [{drugrecommendation, classification, phenotypes, implications, activityscore, lookupkey, population, drug: {name}}], count}}.
CPIC_get_recommendations(drug="codeine", limit=50) — auto-resolves drug name to guideline_id via CPIC API, and filters within multi-drug guidelines (e.g., CYP2D6 opioid guideline covers codeine + tramadol) using RxNorm ID matching.classification: "Strong", "Moderate", or "Optional". phenotypes: maps gene → metabolizer phenotype. activityscore: maps gene → activity score.CPIC_get_drug_info(name="codeine") to extract guidelineid, then CPIC_get_recommendations(guideline_id=100416, limit=50).CPIC_get_drug_info: name (string REQUIRED, lowercase, e.g., "codeine"). Returns {status, data: [{drugid, guidelineid, flowchart, rxnormid, drugbankid}]}.
guidelineid directly. Still useful for extracting DrugBank/ATC IDs.PharmGKB_get_dosing_guidelines: guideline_id (string REQUIRED -- use clinpgxid from CPIC_list_guidelines, e.g., "PA166251445"). Returns {status, data: {id, name, level, literature: [{title, crossReferences}], link}}.
CPIC_list_guidelines: gene (string, optional), drug (string, optional). Returns {status, data: [{id, name, url, genes, clinpgxid}]}. Returns all ~29 guidelines; supports built-in filtering by gene/drug.
clinpgxid values for PharmGKB_get_dosing_guidelines.Note:
PharmGKB_get_clinical_annotationsrequires anannotation_id(e.g., "1447954390"). To discover annotation IDs, usePharmGKB_search_variants(query=rsID)first, then extract annotation IDs from the results.
CPIC_get_recommendations returns 0 rows. Direct users to CPIC website or PharmGKB.clinpgxid (e.g., "PA166251445"), NOT pharmgkbid (old format returns 404).CPIC_get_drug_info requires lowercase. CPIC_get_recommendations with drug= uses ilike matching (case-insensitive).{status, data: {guideline_id, recommendations: [...], count}} -- recommendations are nested under data.recommendations.CPIC_get_alleles: genesymbol (string REQUIRED), limit (int, default 50). Returns {status, data: [{name, clinicalfunctionalstatus, activityvalue, functionalstatus}]}.
clinicalfunctionalstatus (not functionalstatus which may be null). Values: "Normal function", "Decreased function", "No function", "Increased function", "Uncertain function", "Unknown function".activityvalue: numeric string (e.g., "1.0", "0.5", "0.0") or "n/a".PharmGKB_search_variants: query (string REQUIRED, rsID). Returns variant classification and clinical significance.
PharmGKB_get_clinical_annotations: annotation_id (string REQUIRED, e.g., "1447954390"). Returns {status, data: {accessionId, allelePhenotypes: [{allele, phenotype, limitedEvidence}], levelOfEvidence: {term}}}.
PharmGKB_search_variants(query=rsID) or from the PharmGKB website.levelOfEvidence.term: "1A", "1B", "2A", "2B", "3", "4" (PharmGKB evidence levels).PharmGKB_get_gene_details: gene_id (string REQUIRED, PharmGKB accession e.g., "PA128"). Returns detailed gene info including allele definition files, VIP citations.
PharmGKB_get_drug_details: drug_id (string REQUIRED, PharmGKB chemical ID e.g., "PA449088"). Returns drug metadata including SMILES, InChI, type (Drug/Prodrug).
OpenTargets_drug_pharmacogenomics_data: chemblId (string REQUIRED, e.g., "CHEMBL1201560"), size (int). Returns PGx variant data from OpenTargets including variant consequences and drug associations.
A poor metabolizer has reduced or absent enzyme activity. What that means clinically depends entirely on whether the drug is active or a prodrug:
This active-vs-prodrug distinction determines the direction of clinical concern. Get it right before interpreting any metabolizer phenotype.
Star allele reasoning: Don't memorize allele tables. The logic is always: allele function status (normal / decreased / no function) → diplotype → predicted enzyme activity → phenotype (UM/NM/IM/PM) → clinical recommendation. Use CPIC_get_alleles(genesymbol=...) to look up function status for any specific allele.
fda_pharmacogenomic_biomarkers: drug_name (string, optional), biomarker (string, optional, e.g., "CYP2D6"), limit (integer, default 10). Returns {status, count, shown, results: [{Drug, TherapeuticArea, Biomarker, LabelingSection}]}.
limit=1000 for complete results (default is 10).LabelingSection values: "Dosage and Administration", "Clinical Pharmacology", "Precautions", "Use in Specific Populations", "Boxed Warning", "Contraindications".FDA_get_pharmacogenomics_info_by_drug_name: drug_name (string REQUIRED). Returns FDA label PGx sections with brand/generic names. Good for finding PGx labeling text in actual FDA labels.
The LabelingSection field tells you how actionable the PGx information is. "Boxed Warning" or "Contraindications" means testing may be required or the drug contraindicated in certain genotypes — highest urgency. "Dosage and Administration" means genotype directly drives dose selection. "Clinical Pharmacology" is usually informational (PK/PD data), not a prescribing directive. When in doubt, retrieve the full label text with FDA_get_pharmacogenomics_info_by_drug_name.
DGIdb_get_drug_gene_interactions: genes (array of strings REQUIRED, e.g., ["CYP2D6"]), interaction_types (array, optional), interaction_sources (array, optional). Returns drug-gene interactions with sources.
interaction_types and sources parameters.DGIdb_get_gene_druggability: genes (array of strings REQUIRED). Returns {status, data: {data: {genes: {nodes: [{name, geneCategories}]}}}}.
PharmGKB_get_dosing_guidelines: (also in Phase 2) Provides DPWG (Dutch Pharmacogenetics Working Group) guidelines alongside CPIC.
OpenTargets_drug_pharmacogenomics_data: chemblId (string REQUIRED), size (int). Returns PGx variant annotations from the OpenTargets platform.
FAERS_filter_serious_events: drug_name (string REQUIRED), seriousness_type ("all"/"death"/"hospitalization"/"disability"/"life_threatening"), adverse_event (string, optional). Use to detect serious adverse event signals for PGx-relevant drugs — e.g., respiratory depression reports for codeine in the context of CYP2D6 UM status. The adverse_event parameter filters to reports containing that specific reaction term.
Optional: DisGeNET_get_vda for variant-disease associations (requires DISGENET_API_KEY).
PGx testing changes clinical decisions ONLY for drugs with narrow therapeutic indices metabolized by polymorphic enzymes where genotype reliably predicts outcome. If the drug has a wide therapeutic index or is cleared by multiple redundant pathways, PGx status rarely alters the prescribing decision even when a variant is present.
Evidence grading — reasoning approach: CPIC levels A/B represent actionable evidence; C/D are informational. PharmGKB level 1A means the annotation is already embedded in a CPIC or DPWG guideline — the highest confidence tier. Levels 3/4 are hypothesis-generating, not prescribing-grade. CPIC recommendation strength (Strong/Moderate/Optional) within a guideline reflects how certain the genotype-to-outcome link is for that specific phenotype.
The key question is not "what level is this?" but "does this level justify changing the prescription?" For Level A CPIC with Strong classification, yes. For PharmGKB level 3, no — report it but don't act on it alone.
Critical parameter behaviors to remember — these are the ones that actually cause failures:
CPIC_get_recommendations: accepts guideline_id (integer) OR drug/drug_name (string). Never pass guideline_id as a string.PharmGKB_get_dosing_guidelines: requires clinpgxid (e.g., "PA166251445"), not the numeric pharmgkbid. Get clinpgxid from CPIC_list_guidelines.PharmGKB_get_clinical_annotations: requires annotation_id. Cannot query by gene or drug. Discover IDs via PharmGKB_search_variants(query=rsID).fda_pharmacogenomic_biomarkers: default limit=10 is almost always too small. Pass limit=1000.CPIC_get_drug_info: drug name must be lowercase.DGIdb_get_drug_gene_interactions and DGIdb_get_gene_druggability: genes is an array, not a string (e.g., ["CYP2D6"]).CPIC_search_gene_drug_pairs: returns RxNorm IDs, not drug names. Use CPIC_get_gene_drug_pairs when you need drug names.CPIC guidelines give genotype → phenotype → recommendation mappings. The skill is knowing when to apply them, not memorizing the mappings themselves. Use tools to retrieve the specific recommendation for the specific phenotype. The reasoning chain is:
CPIC_get_recommendations)fda_pharmacogenomic_biomarkers)If step 1 is no, fall back to PharmGKB variant annotations for evidence-graded but non-guideline information.
PharmGKB_search_variants(query=rsID) for variant-level annotations; check EpiGraphDB for gene-drug evidencepgx_on_fda_label fielddrug: {name}) instead of CPIC_search_gene_drug_pairs (returns only RxNorm IDs)PharmGKB_search_variants(query=rsID)OpenTargets_drug_pharmacogenomics_data(chemblId=...) with ChEMBL IDDrug-first (codeine + CYP2D6 PM): CPIC_get_recommendations(drug="codeine", limit=50) → filter phenotypes.CYP2D6="Poor Metabolizer" → Strong recommendation: avoid codeine. Then CPIC_get_alleles(genesymbol="CYP2D6", limit=100) to confirm star allele function (e.g., *4/*4 → no function, AS 0.0). Then fda_pharmacogenomic_biomarkers(drug_name="codeine", limit=1000) to confirm FDA label status. Gene-first alternative: CPIC_get_gene_drug_pairs(genesymbol="CYP2D6") to list all associated drugs.
Gene-first (all CYP2C19 drugs): CPIC_search_gene_drug_pairs(gene_symbol="CYP2C19", cpiclevel="A") for Level A pairs. EpiGraphDB_get_gene_drug_associations(gene_name="CYP2C19") for CPIC + PharmGKB + FDA label overview in one call. fda_pharmacogenomic_biomarkers(biomarker="CYP2C19", limit=1000) for complete FDA coverage.
Variant-first (rs1799853): PharmGKB_search_variants(query="rs1799853") → CYP2C9 variant, drug-response significance. CPIC_get_alleles(genesymbol="CYP2C9", limit=100) → maps to *2, "Decreased function". CPIC_get_gene_drug_pairs(genesymbol="CYP2C9") → warfarin, phenytoin, NSAIDs. For each drug with a guideline: CPIC_get_recommendations(drug="phenytoin", limit=50).
When PGx analysis involves understanding which drug class a substrate belongs to, or finding all drugs in a class that share the same metabolizing enzyme: use RxClass_get_drug_classes(drug_name=...) to get all class memberships for a drug, RxClass_find_classes(query=..., class_type=...) to find class IDs from a keyword, and RxClass_get_class_members(class_id=..., rela_source=..., ttys="IN") to list all drugs in a class. Example: find all SSRIs to advise which require CYP2D6 testing as a class note.
For canonical FDA substance identification (UNII codes, cross-references to ATC/DrugBank/CAS): use FDAGSRS_search_substances(query=...) to find the UNII code, FDAGSRS_get_substance(unii=...) for the full record with all names and cross-references, and FDAGSRS_get_structure(unii=...) for SMILES/InChIKey. Useful to confirm that two drug name variants (e.g., "warfarin sodium" and "warfarin") share the same UNII before cross-referencing in CPIC or PharmGKB.