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 phaseREPORT_TEMPLATE.md - Full report template with completeness checklistSCORING_TABLES.md - Evidence grading, treatment prioritization, use casesTOOLS_REFERENCE.md - Detailed tool parameter referenceQUICK_START.md - Example usage and quick referenceEXAMPLES.md - Complete example reports