mims-harvard/tooluniverse-precision-oncology

Precision Oncology Treatment Advisor

Provide actionable treatment recommendations for cancer patients based on their molecular profile using CIViC, ClinVar, OpenTargets, ClinicalTrials.gov, and structure-based analysis.

Domain Reasoning

Treatment selection follows a strict evidence hierarchy: FDA-approved for this specific mutation in this cancer type ranks highest, followed by approval for this mutation in any cancer (tumor-agnostic), then active clinical trials, and finally off-label use. Skipping this hierarchy to recommend off-label therapies when an approved option exists is a clinical error. Always check current NCCN guidelines and recent literature, as approvals change rapidly — a drug that was investigational last year may now be first-line.

When looking up treatment for a specific mutation, search CIViC and OncoKB FIRST, not PubMed. These databases have curated evidence levels. PubMed is for when curated databases don't have the answer.

Treatment Selection Reasoning

Biomarker-to-drug logic — When a biomarker is identified, the first-line targeted therapy follows established mappings. Always verify current approval status via OncoKB/CIViC, but use this as a starting framework:

• NSCLC: EGFR exon 19 del / L858R → osimertinib (1L); ALK fusion → alectinib/lorlatinib; ROS1 fusion → crizotinib/entrectinib; KRAS G12C → sotorasib/adagrasib; MET exon 14 skip → capmatinib/tepotinib; RET fusion → selpercatinib; BRAF V600E → dabrafenib+trametinib; NTRK fusion → larotrectinib/entrectinib (tumor-agnostic)
• Breast: HER2+ → trastuzumab+pertuzumab (1L), T-DXd (2L); HR+/HER2- → CDK4/6i (palbociclib/ribociclib) + AI; BRCA1/2 mut → olaparib/talazoparib; PIK3CA mut → alpelisib+fulvestrant
• Colorectal: BRAF V600E → encorafenib+cetuximab; MSI-H/dMMR → pembrolizumab (tumor-agnostic); KRAS/NRAS wild-type → cetuximab/panitumumab (anti-EGFR)
• Melanoma: BRAF V600E/K → dabrafenib+trametinib or encorafenib+binimetinib; wild-type → immunotherapy (nivolumab+ipilimumab)
• Tumor-agnostic: MSI-H/dMMR → pembrolizumab; NTRK fusion → larotrectinib; TMB-H (>=10 mut/Mb) → pembrolizumab; RET fusion → selpercatinib

Resistance mechanism reasoning — When a patient progresses on targeted therapy, distinguish primary resistance (never responded — check if the mutation was truly the driver, or if co-mutations like TP53/RB1 abrogate response) from acquired resistance (responded then progressed — on-target mutations or bypass activation). Common patterns:

• EGFR TKIs: 1st/2nd-gen resistance → T790M (50-60%); osimertinib resistance → C797S (10-25%), MET amp (15-20%), HER2 amp, histologic transformation (SCLC ~5%)
• ALK TKIs: crizotinib resistance → ALK secondary mutations (L1196M, G1269A); alectinib resistance → G1202R (solvent front); lorlatinib resistance → compound mutations
• BRAF inhibitors: MAPK reactivation (MEK mutations, BRAF amplification, NRAS mutations), PI3K/AKT bypass
• Anti-HER2: HER2 truncation (p95HER2), PIK3CA activation, HER3 upregulation
• Immunotherapy (anti-PD1): B2M loss (MHC-I loss), JAK1/2 loss-of-function (IFN-gamma signaling escape), WNT/beta-catenin activation (T-cell exclusion) For resistance workup: query civic_search_evidence_items with the drug name + "resistance", then PubMed_search_articles for recent mechanisms.

LOOK UP DON'T GUESS

• FDA approval status for a mutation-drug pair: query OncoKB_annotate_variant and civic_search_variants; never assume approval status from memory.
• Active clinical trials: search search_clinical_trials with the specific condition and mutation; do not cite trials from memory.
• Resistance mechanisms for specific drugs: query civic_search_evidence_items and PubMed_search_articles; do not assume resistance pathways.
• Variant frequency in TCGA: retrieve from GDC_get_mutation_frequency or cBioPortal_get_mutations; do not estimate prevalence.

---

KEY PRINCIPLES:

1. Report-first - Create report file FIRST, update progressively
2. Evidence-graded - Every recommendation has evidence level
3. Actionable output - Prioritized treatment options, not data dumps
4. Clinical focus - Answer "what should we do?" not "what exists?"
5. English-first queries - Always use English terms in tool calls (mutations, drug names, cancer types), even if the user writes in another language. Only try original-language terms as a fallback. Respond in the user's language

---

When to Use

• "Patient has [cancer] with [mutation] - what treatments?"
• "What are options for EGFR-mutant lung cancer?"
• "Patient failed [drug], what's next?"
• "Clinical trials for KRAS G12C?"
• "Why isn't [drug] working anymore?"

---

Phase 0: Tool Verification

| Tool | WRONG | CORRECT | |------|-------|---------| | civic_get_variant | variant_name | variant_id (numeric, e.g., 4170) | | civic_get_evidence_item | variant_id | id (numeric) | | OpenTargets_* | ensemblID | ensemblId (camelCase) | | search_clinical_trials | disease | condition |

---

Workflow Overview

Input: Cancer type + Molecular profile (mutations, fusions, amplifications)

Phase 1: Profile Validation -> Resolve gene IDs (Ensembl, UniProt, ChEMBL)
Phase 2: Variant Interpretation -> CIViC, ClinVar, COSMIC, GDC/TCGA, DepMap, OncoKB, cBioPortal, HPA
Phase 2.5: Tumor Expression -> CELLxGENE cell-type expression, ChIPAtlas regulatory context
Phase 3: Treatment Options -> OpenTargets + DailyMed (approved), ChEMBL (off-label)
Phase 3.5: Pathway & Network -> KEGG/Reactome pathways, IntAct interactions
Phase 4: Resistance Analysis -> CIViC + PubMed + NvidiaNIM structure analysis
Phase 5: Clinical Trials -> ClinicalTrials.gov search + eligibility
Phase 5.5: Literature -> PubMed, BioRxiv/MedRxiv preprints, OpenAlex citations
Phase 6: Report Synthesis -> Executive summary + prioritized recommendations

---

Key Tools by Phase

Phase 1: Profile Validation

• MyGene_query_genes - Resolve gene to Ensembl ID
• UniProt_search - Get UniProt accession
• ChEMBL_search_targets - Get ChEMBL target ID

Phase 2: Variant Interpretation

• civic_search_variants / civic_get_variant - CIViC evidence
• COSMIC_get_mutations_by_gene / COSMIC_search_mutations - Somatic mutations
• GDC_get_mutation_frequency / GDC_get_ssm_by_gene - TCGA patient data
• GDC_get_gene_expression / GDC_get_cnv_data - Expression and CNV
• GDC_get_survival - Kaplan-Meier survival data by project and optional gene mutation filter
• GDC_get_clinical_data - TCGA clinical metadata (stage, vital status, treatment, demographics)
• Progenetix_cnv_search - Copy number variation biosamples by genomic region and cancer type (NCIt code)
• DepMap_get_gene_dependencies / PharmacoDB_get_experiments - Target essentiality
• OncoKB_annotate_variant / OncoKB_get_gene_info - Actionability
• cBioPortal_get_mutations / cBioPortal_get_cancer_studies - Cross-study data
• HPA_search_genes_by_query / HPA_get_comparative_expression_by_gene_and_cellline - Expression

Phase 2.5: Tumor Expression

• CELLxGENE_get_expression_data / CELLxGENE_get_cell_metadata - Cell-type expression

Phase 3: Treatment Options

• OpenTargets_get_associated_drugs_by_target_ensemblID - Approved drugs (param: ensemblId, camelCase)
• DGIdb_get_drug_gene_interactions - Drug-gene interactions (param: genes as array, e.g., ["EGFR"]). Comprehensive; covers inhibitors, antibodies, and investigational agents.
• DailyMed_search_spls - FDA label details
• ChEMBL_get_drug_mechanisms - Drug mechanism

Phase 3.5: Pathway & Network

• kegg_find_genes / kegg_get_gene_info - KEGG pathways
• reactome_disease_target_score - Reactome disease relevance
• intact_get_interaction_network - Protein interactions

Phase 4: Resistance Analysis

• civic_search_evidence_items - Search by known resistance mutations individually (e.g., molecular_profile="EGFR C797S", molecular_profile="MET Amplification"). The significance field in results indicates Resistance/Sensitivity — filter on it after retrieval.
• PubMed_search_articles - Resistance literature (e.g., "osimertinib resistance C797S combination therapy")
• alphafold_get_prediction / get_diffdock_info - Structure-based analysis (AlphaFold for structure, DiffDock for docking)

Phase 5: Clinical Trials

• search_clinical_trials - Find trials (param: condition, NOT disease)
• get_clinical_trial_eligibility_criteria - Eligibility details

Phase 5.5: Safety & Pharmacogenomics (MANDATORY — do NOT skip)

You MUST call FAERS for the leading approved drug before finalizing the report. A clinical brief without real-world adverse-event data is incomplete.

• FAERS_search_adverse_event_reports — REQUIRED: call with medicinalproduct="<drug_name>" for at least the top 1-2 approved drugs. Report top 10 serious AEs + death count.
• FDA_get_warnings_and_cautions_by_drug_name — REQUIRED: boxed warnings + key precautions.
• FAERS_count_death_related_by_drug - Mortality signal for a drug
• CPIC_list_guidelines - Check for relevant PGx guidelines (e.g., DPYD for fluoropyrimidines in chemo regimens, UGT1A1 for irinotecan). No CPIC guidelines exist for EGFR TKIs.
• fda_pharmacogenomic_biomarkers - FDA-labeled PGx biomarkers for the drug

OncoKB demo mode: Without ONCOKB_API_TOKEN env var, OncoKB only covers BRAF, TP53, ROS1. For other genes (EGFR, KRAS, ALK, etc.), set the API key or use CIViC as the primary evidence source.

Phase 6: Literature

• PubMed_search_articles - Published evidence (use limit, mindate, maxdate for date filtering)
• BioRxiv_list_recent_preprints / MedRxiv_get_preprint - Preprints (flag as NOT peer-reviewed)
• openalex_search_works - Citation analysis

---

Cross-Skill References

For CYP interaction with cancer drugs, run: python3 skills/tooluniverse-drug-drug-interaction/scripts/pharmacology_ref.py --type cyp_substrate --drug drugname

---

References

• TOOLS_REFERENCE.md - Complete tool documentation with parameters and examples
• API_USAGE_PATTERNS.md - Detailed code examples for each phase
• TREATMENT_ALGORITHMS.md - Evidence grading, treatment prioritization, cancer type mappings, DepMap interpretation
• REPORT_TEMPLATE.md - Report template with output tables
• EXAMPLES.md - Worked examples (EGFR NSCLC, T790M resistance, KRAS G12C, no actionable mutations)
• CHECKLIST.md - Quality and completeness checklist