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

:

Report-first approach

- Create report file FIRST, then populate progressively

Evidence-graded

- Every recommendation has an evidence tier (T1-T4)

Actionable output

- Prioritized treatment options, not data dumps

Clinical focus

- Answer "what should we treat with?" not "what databases exist?"

Resistance-aware

- Always check for known resistance mechanisms

Cancer-type specific

- Tailor all recommendations to the patient's cancer type when provided

Source-referenced

- Every statement must cite the tool/database source

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

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

Optional

Cancer type (improves specificity) Accepted Input Formats Format Example How to Parse Gene + amino acid change EGFR L858R gene=EGFR, variant=L858R Gene + HGVS protein BRAF p.V600E gene=BRAF, variant=V600E Gene + exon notation EGFR exon 19 deletion gene=EGFR, variant=exon 19 deletion Gene + fusion EML4-ALK fusion gene=ALK, variant=EML4-ALK Gene + amplification HER2 amplification gene=ERBB2, variant=amplification Gene Symbol Normalization 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 Input: Gene symbol + Variant notation + Optional cancer type Phase 1: Gene Disambiguation & ID Resolution - Resolve gene to Ensembl ID, UniProt accession, Entrez ID - Get gene function, pathways, protein domains - Identify cancer type EFO ID (if cancer type provided) Phase 2: Clinical Variant Evidence (CIViC) - Find gene in CIViC (via Entrez ID matching) - Get all variants for the gene, match specific variant - Retrieve evidence items (predictive, prognostic, diagnostic) Phase 3: Mutation Prevalence (cBioPortal) - Frequency across cancer studies - Co-occurring mutations, cancer type distribution Phase 4: Therapeutic Associations (OpenTargets + ChEMBL + FDA + DrugBank) - FDA-approved targeted therapies - Clinical trial drugs (phase 2-3), drug mechanisms - Combination therapies Phase 5: Resistance Mechanisms - Known resistance variants (CIViC, literature) - Bypass pathway analysis (Reactome) Phase 6: Clinical Trials - Active trials recruiting for this mutation - Trial phase, status, eligibility Phase 7: Prognostic Impact & Pathway Context - Survival associations (literature) - Pathway context (Reactome), Expression data (GTEx) Phase 8: Report Synthesis - Executive summary, clinical actionability score - Treatment recommendations (prioritized), completeness checklist For detailed code snippets and API call patterns for each phase, see ANALYSIS_DETAILS.md . Evidence Grading Summary Tier Criteria Examples T1 FDA-approved therapy, Level A CIViC evidence, phase 3 trial Osimertinib for EGFR T790M T2 Phase 2/3 clinical data, Level B CIViC evidence Combination trial data T3 Preclinical data, Level D CIViC, case reports Novel mechanisms, in vitro T4 Computational prediction, pathway inference Docking, pathway analysis Clinical Actionability Scoring Score Criteria HIGH FDA-approved targeted therapy for this exact mutation + cancer type MODERATE Approved therapy for different cancer type with same mutation, OR phase 2-3 trial data LOW Only preclinical evidence or pathway-based rationale UNKNOWN Insufficient data to assess actionability For full scoring tables and treatment prioritization, see SCORING_TABLES.md . 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.knownDrugs.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 For full tool parameter reference, see TOOLS_REFERENCE.md . Fallback Chains Primary Tool Fallback Use When CIViC variant lookup PubMed literature search Gene not found in CIViC OpenTargets drugs ChEMBL drug search No OpenTargets drug hits FDA indications DrugBank drug info Drug not in FDA database cBioPortal TCGA study cBioPortal pan-cancer Specific cancer study not available GTEx expression Ensembl gene lookup GTEx returns empty Reactome pathways UniProt function Pathway mapping fails Quantified Minimums Section Requirement Gene IDs At least Ensembl + UniProt resolved Clinical evidence CIViC queried + PubMed literature search Mutation prevalence At least 1 cBioPortal study Therapeutic options All approved drugs listed + FDA label for top drugs Resistance Literature search + known patterns documented Clinical trials At least 1 search query executed Prognostic impact PubMed literature search performed Pathway context Reactome pathway mapping attempted See Also ANALYSIS_DETAILS.md - Detailed code snippets and API call patterns for each phase REPORT_TEMPLATE.md - Full report template with completeness checklist SCORING_TABLES.md - Evidence grading, treatment prioritization, use cases TOOLS_REFERENCE.md - Detailed tool parameter reference QUICK_START.md - Example usage and quick reference EXAMPLES.md - Complete example reports