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. A mutation seen in hundreds of independent tumors (e.g., BRAF V600E) 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 Fallback Strategy When a primary tool returns no results, fall back rather than reporting "no data found": CIViC empty search PubMed for "[gene] [variant] clinical evidence" OpenTargets no drugs try ChEMBL drug search by target cBioPortal specific study empty try pan cancer study (msk impact 2017 or similar) Reactome no pathways use UniProt function annotation for pathway context

tooluniverse-cancer-variant-interpretation