Clinical interpretation of somatic cancer mutations for precision oncology. Transforms a gene + variant + cancer-type input into an actionable report: clinical evidence tier (CIViC, OncoKB), therapeutic options (FDA-approved + investigational), resistance mechanisms, prognosis, and matching clinical

Cancer Variant Interpretation for Precision Oncology Comprehensive clinical interpretation of somatic mutations in cancer. Transforms a gene + variant input into an actionable precision oncology report covering clinical evidence, therapeutic options, resistance mechanisms, clinical trials, and prognostic implications. KEY PRINCIPLES : 1. Report first approach Create report file FIRST, then populate progressively 2. Evidence graded Every recommendation has an evidence tier (T1 T4) 3. Actionable output Prioritized treatment options, not data dumps 4. Clinical focus Answer "what should we treat with?" not "what databases exist?" 5. Resistance aware Always check for known resistance mechanisms 6. Cancer type specific Tailor all recommendations to the patient's cancer type when provided 7. Source referenced Every statement must cite the tool/database source 8. English first queries Always use English terms in tool calls (gene names, drug names, cancer types), even if the user writes in another language. Respond in the user's language LOOK UP, DON'T GUESS When uncertain about any scientific fact, SEARCH databases first (PubMed, UniProt, ChEMBL, ClinVar, etc.) rather than reasoning from memory. A database verified answer is always more reliable than a guess. COMPUTE, DON'T DESCRIBE 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. When to Use Apply when user asks: "What treatments exist for EGFR L858R in lung cancer?" "Patient has BRAF V600E melanoma what are the options?" "Is KRAS G12C targetable?" "Patient progressed on osimertinib what's next?" "What clinical trials are available for PIK3CA E545K?" "Interpret this somatic mutation: TP53 R273H" Input Parsing Required : Gene symbol + variant notation (e.g., "EGFR L858R", "BRAF p.V600E", "EML4 ALK fusion", "HER2 amplification") Optional : Cancer type (improves specificity) Parse the gene symbol and variant separately. For fusions, use the kinase partner as the primary gene. For amplifications/deletions, use the gene name directly. Normalize common aliases: HER2 ERBB2, PD L1 CD274, VEGF VEGFA. Phase 0: Tool Parameter Verification (CRITICAL) BEFORE calling ANY tool for the first time , verify its parameters. Tool WRONG Parameter CORRECT Parameter OpenTargets get associated drugs by target ensemblID ensemblID ensemblId (camelCase) OpenTargets get drug chembId by generic name genericName drugName OpenTargets target disease evidence ensemblID ensemblId + efoId MyGene query genes q query search clinical trials disease , biomarker condition , query term (required) civic get variants by gene gene symbol gene id (CIViC numeric ID) drugbank any 3 params ALL 4 required: query , case sensitive , exact match , limit ChEMBL get drug mechanisms chembl id drug chembl id exact ensembl lookup gene no species species='homo sapiens' is REQUIRED Workflow Overview For detailed code snippets and API call patterns for each phase, see ANALYSIS DETAILS.md . Clinical Reasoning Strategies Driver vs Passenger Reasoning Not every mutation in a tumor is driving the cancer. Before querying databases, form a hypothesis: Is this gene a known oncogene or tumor suppressor? Genes like EGFR, BRAF, KRAS, TP53, PIK3CA are well established cancer drivers. A mutation in one of these warrants deep investigation. A mutation in a gene with no known cancer role is likely a passenger. Is this specific mutation recurrent across tumors (hotspot)? Use cBioPortal to check prevalence across specific studies, or GenomeNexus get cancer hotspots for a direct is hotspot boolean plus tumor counts from the Chang et al. hotspot database (e.g., BRAF V600E: is hotspot: true , 897 tumors as a single residue hotspot, 545 as a 3D cluster hotspot). A mutation seen in hundreds of independent tumors is almost certainly a driver. A unique, never before seen missense in the same gene is less certain. What is the predicted functional impact? Truncating mutations (nonsense, frameshift) in tumor suppressors are likely loss of function drivers. Missense mutations in oncogenes at known hotspot residues are likely gain of function drivers. For unique (non hotspot) missense in driver genes, look at mechanism, not just pathogenicity. AlphaMissense gives a score; the ESMC 6B SAE composite ESM explain variant mechanism(sequence=wt protein seq, position=..., ref aa=..., alt aa=..., top k features=5) answers how the substitution disrupts function — catalytic / ligand binding / PTM / structural stability loss. A unique missense that disrupts the same SAE feature category as a known driver hotspot in the same gene is more likely a driver than a missense that disrupts unrelated features. Requires ESM API KEY ; missense only. Conclusion pattern : A recurrent mutation in a known driver gene is likely actionable. A unique mutation in a gene not associated with cancer is likely a passenger. State your assessment and the reasoning behind it. Actionability Reasoning Actionable means a therapy exists that targets this alteration. Think in tiers based on evidence strength: Tier 1 : FDA approved drug for this mutation in this cancer type. The standard of care — recommend confidently. Example reasoning: "CIViC returns Level A evidence, FDA label confirms indication." Tier 2 : FDA approved for this mutation in a different cancer type, or strong clinical trial evidence (phase 2 3) in this cancer type. Reasonable to consider, especially under tumor agnostic approvals or with molecular tumor board discussion. Tier 3 : Preclinical evidence only — cell line data, animal models, or case reports. May justify clinical trial enrollment but not off label use. Tier 4 : Biological rationale but no direct evidence — the mutation is in a druggable pathway, or a structurally similar mutation responds to therapy. Hypothesis generating only. When synthesizing, state the tier and explain WHY you assigned it based on the evidence you found, not just which database returned a hit. Resistance Reasoning If the patient has already been treated, ask: could this mutation be a resistance mechanism? On target resistance : Mutations in the drug target gene itself that restore signaling despite drug binding. These typically emerge at the drug binding site (e.g., EGFR T790M after erlotinib, EGFR C797S after osimertinib, ABL T315I after imatinib). Bypass pathway activation : Mutations in parallel signaling pathways that render the target irrelevant (e.g., MET amplification bypassing EGFR inhibition, BRAF activation bypassing MEK inhibition). Phenotypic transformation : Lineage changes (e.g., small cell transformation in EGFR mutant lung cancer) that eliminate dependence on the original driver. Timing matters : If the mutation was detected AFTER treatment, it is more likely a resistance mechanism than if it was present at diagnosis. When to Use Which Tool Form your clinical hypothesis FIRST based on gene function and mutation type, THEN use tools to validate: CIViC ( civic search genes , civic get variants by gene ): Your primary source for clinical evidence. Returns curated evidence items with evidence levels, clinical significance, and associated therapies. Start here for any variant with potential clinical relevance. cBioPortal ( cBioPortal get mutations ): Use to assess mutation prevalence — is this a hotspot? How common is it across cancer types? This informs your driver vs passenger assessment. OpenTargets ( OpenTargets get associated drugs by target ensemblID ): Use for actionability — what drugs target this gene? Cross reference with CIViC evidence to assign tiers. PubMed ( PubMed search articles ): Use when CIViC lacks entries for your variant, or to find resistance mechanism reports and recent clinical trial results. ClinicalTrials.gov ( search clinical trials ): Use after establishing the variant is potentially actionable, to find enrollment opportunities. Tool Reference (Verified Parameters) Gene Resolution Tool Key Parameters Response Key Fields MyGene query genes query , species hits[].ensembl.gene , .entrezgene , .symbol UniProt search query , organism , limit results[].accession OpenTargets get target id description by name targetName data.search.hits[].id ensembl lookup gene gene id , species (REQUIRED) data.id , .version Clinical Evidence Tool Key Parameters Response Key Fields civic search genes query , limit data.genes.nodes[].id , .entrezId civic get variants by gene gene id (CIViC numeric) data.gene.variants.nodes[] civic get variant variant id data.variant Drug Information Tool Key Parameters Response Key Fields OpenTargets get associated drugs by target ensemblID ensemblId , size data.target.drugAndClinicalCandidates.rows[] FDA get indications by drug name drug name , limit results[].indications and usage drugbank get drug basic info by drug name or id query , case sensitive , exact match , limit (ALL required) results[] Mutation Prevalence Tool Key Parameters Response Key Fields cBioPortal get mutations study id , gene list data[].proteinChange cBioPortal get cancer studies limit [].studyId , .cancerTypeId Clinical Trials & Literature Tool Key Parameters Response Key Fields search clinical trials query term (required), condition studies[] PubMed search articles query , limit , include abstract Returns list of dicts (NOT wrapped) Reactome map uniprot to pathways id (UniProt accession) Pathway mappings GTEx get median gene expression gencode id , operation="median" Expression by tissue Variant Annotation & Cancer Hotspots (Genome Nexus) Complements CIViC/cBioPortal with structured, computed consequence prediction (VEP/SIFT/PolyPhen/AlphaMissense) plus a dedicated cancer hotspot lookup — use it to establish in silico pathogenicity and hotspot status before or alongside the curated clinical evidence search, not instead of it. Requires GRCh37/hg19 coordinates (convert first if you only have GRCh38, e.g. via NCBI Variation Services in tooluniverse variant analysis ). Tool Key Parameters Response Key Fields GenomeNexus annotate variant hgvsg (GRCh37, e.g. "7:g.140453136A T" ) most severe consequence , transcript consequences[].{hgvsp, sift prediction, polyphen prediction, alphaMissense} , hotspots.annotation , colocated variants[].dbSnpId GenomeNexus annotate mutation chromosome , start , end , reference allele , variant allele (GRCh37) Same shape as annotate variant — use when you have separate coordinate fields instead of an HGVS string GenomeNexus annotate dbsnp rsid (e.g. "rs121913529" ) Same shape; resolves the rsID to coordinates first GenomeNexus get cancer hotspots hgvsg (GRCh37) is hotspot (bool), hotspots[].{residue, tumorCount, type} — type is "single residue" or "3d" (structural cluster) GenomeNexus get canonical transcript gene symbol transcriptId , proteinId , proteinLength , refseqMrnaId , pfamDomains[] Cancer Driver Gene Classification (IntOGen) Genome Nexus's is hotspot (above) answers "is this exact variant recurrent?" IntOGen answers a different, gene level question: "is this whole gene a statistic

tooluniverse-cancer-variant-interpretation