explain_variant_impact

Instructions

Implementation Reference

• scripts/alphagenome_bridge.py:678-709 (handler)

  Core handler function that generates human-readable explanation of variant impact by processing predictions from predict_variant_effect and constructing explanatory text based on impact level, RNA fold change, and splicing delta.

  def explain_variant_impact(client, params: Dict[str, Any]) -> Dict[str, Any]:
      """Provide human-readable explanation of variant impact."""
      result = predict_variant_effect(client, params)
  
      # Generate explanation
      predictions = result['predictions']
      impact = result['interpretation']['impact_level']
  
      explanation = []
  
      if impact == 'high':
          explanation.append("This variant has HIGH regulatory impact.")
      elif impact == 'moderate':
          explanation.append("This variant has MODERATE regulatory impact.")
      else:
          explanation.append("This variant has LOW regulatory impact.")
  
      rna_fc = predictions.get('rna_seq', {}).get('fold_change', 0)
      if abs(rna_fc) > 0.01:
          direction = "increases" if rna_fc > 0 else "decreases"
          explanation.append(f"It {direction} gene expression by {abs(rna_fc):.3f} fold.")
  
      splice_delta = predictions.get('splice', {}).get('delta', 0)
      if splice_delta > 0.1:
          explanation.append(f"It significantly affects splicing (delta: {splice_delta:.3f}).")
  
      return {
          'variant': result['variant'],
          'summary': ' '.join(explanation),
          'impact_level': impact,
          'clinical_significance': result['interpretation']['clinical_significance']
      }

• src/tools.ts:684-704 (schema)

  Tool definition including name, description, and input schema (JSON Schema) for validating variant parameters: chromosome, position, ref, alt (tissue_type optional).

  export const EXPLAIN_VARIANT_IMPACT_TOOL: Tool = {
    name: 'explain_variant_impact',
    description: `Provide human-readable explanation of variant impact.
  
  Translates technical predictions into plain language.
  
  Perfect for: patient reports, non-technical summaries.
  
  Example: "Explain the impact of chr9:12345678A>C in simple terms"`,
    inputSchema: {
      type: 'object',
      properties: {
        chromosome: { type: 'string', pattern: '^chr([1-9]|1[0-9]|2[0-2]|X|Y)$' },
        position: { type: 'number', minimum: 1 },
        ref: { type: 'string', pattern: '^[ATGCatgc]+$' },
        alt: { type: 'string', pattern: '^[ATGCatgc]+$' },
        tissue_type: { type: 'string' },
      },
      required: ['chromosome', 'position', 'ref', 'alt'],
    },
  };

• src/tools.ts:709-730 (registration)

  Registration of the explain_variant_impact tool as part of the complete ALL_TOOLS array exported for MCP server tool provision.

  export const ALL_TOOLS: Tool[] = [
    PREDICT_VARIANT_TOOL,
    BATCH_SCORE_TOOL,
    ASSESS_PATHOGENICITY_TOOL,
    PREDICT_TISSUE_SPECIFIC_TOOL,
    COMPARE_VARIANTS_TOOL,
    PREDICT_SPLICE_IMPACT_TOOL,
    PREDICT_EXPRESSION_IMPACT_TOOL,
    ANALYZE_GWAS_LOCUS_TOOL,
    COMPARE_ALLELES_TOOL,
    BATCH_TISSUE_COMPARISON_TOOL,
    PREDICT_TF_BINDING_IMPACT_TOOL,
    PREDICT_CHROMATIN_IMPACT_TOOL,
    COMPARE_PROTECTIVE_RISK_TOOL,
    BATCH_PATHOGENICITY_FILTER_TOOL,
    COMPARE_VARIANTS_SAME_GENE_TOOL,
    PREDICT_ALLELE_SPECIFIC_EFFECTS_TOOL,
    ANNOTATE_REGULATORY_CONTEXT_TOOL,
    BATCH_MODALITY_SCREEN_TOOL,
    GENERATE_VARIANT_REPORT_TOOL,
    EXPLAIN_VARIANT_IMPACT_TOOL,
  ];

• src/index.ts:273-279 (handler)

  MCP server tool call dispatcher that validates input using variantPredictionSchema and invokes the AlphaGenome client method.

  case 'explain_variant_impact': {
    const params = validateInput(variantPredictionSchema, args) as VariantPredictionParams;
    const result = await getClient().explainVariantImpact(params);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/alphagenome-client.ts:460-466 (helper)

  Client wrapper method that bridges the tool call to the Python bridge script by invoking callPythonBridge with action 'explain_variant_impact'.

  async explainVariantImpact(params: VariantPredictionParams): Promise<any> {
    try {
      return await this.callPythonBridge('explain_variant_impact', params);
    } catch (error) {
      if (error instanceof ApiError) throw error;
      throw new ApiError(`Variant impact explanation failed: ${error}`, 500);
    }