Skip to main content
Glama

Predict Variant Effect

ensembl_predict_variant
Read-onlyIdempotent

Predict the functional consequences of a sequence variant using the Ensembl Variant Effect Predictor (VEP). Accepts three input formats: HGVS notation (transcript-relative, e.g. ENST00000380152.8:c.2T>A, or genomic, e.g. 13:g.32316462T>A); region+allele (chr:start:end:strand/allele, e.g. 1:65568:65568:1/T); and a dbSNP rsID (e.g. rs334). Returns the most severe consequence term, affected transcripts and genes, impact level (HIGH/MODERATE/LOW/MODIFIER), and any colocated known variants with clinical significance. HGVS input: provide the full notation including transcript version for best results. Region+allele input: Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (a chr-prefixed name is also accepted). By default the response caps transcript consequences (max_transcript_consequences) and per-variant PubMed IDs (max_pubmed_ids_per_variant) to keep large VEP results compact — well-studied variants like rs334 otherwise carry 60+ consequences and 100+ citations. Truthful totals are always reported; set a cap to 0 (or include_all_colocated_pubmed=true) to retrieve the full set.

Input Schema

NameRequiredDescriptionDefault
speciesNoSpecies in Ensembl internal format. Default is homo_sapiens. For non-human variants, set the appropriate species (e.g. mus_musculus for mouse). Use ensembl_list_species with nameContains (a genus or common name) to find valid values.homo_sapiens
variantYesVariant in one of three formats: (1) HGVS notation — transcript-relative: ENST00000380152.8:c.2T>A; genomic: 13:g.32316462T>A; (2) Region+allele: chr:start:end:strand/allele — e.g. 1:65568:65568:1/T (strand is 1 for forward or -1 for reverse); (3) dbSNP rsID — e.g. rs334. Ensembl normalizes chromosome names; canonical vertebrate output omits the "chr" prefix, though a chr-prefixed name is also accepted.
max_pubmed_ids_per_variantNoMaximum PubMed IDs to return per colocated known variant. Well-studied variants (e.g. rs334) cite 100+ papers; the default trims each list. Set to 0 to return every PubMed ID uncapped. pubmedTotal on each colocated variant reports the true pre-cap count. Ignored when include_all_colocated_pubmed is true.
max_transcript_consequencesNoMaximum transcript consequences to return per VEP record. High-impact variants can affect 60+ transcripts; the default keeps the response focused on the top consequences. Set to 0 to return every transcript consequence uncapped. transcriptConsequencesTotal on each record always reports the true pre-cap count.
include_all_colocated_pubmedNoWhen true, return every PubMed ID for each colocated variant, overriding max_pubmed_ids_per_variant. Default false to keep responses compact.

Output Schema

NameRequiredDescriptionDefault
capNoThe max_transcript_consequences limit applied.
errorNoPresent when the call failed. Absent on success.
shownNoTotal transcript consequences returned across all records after the cap.
noticeNoGuidance when no results are returned or when caps omitted detail.
resultsNoVEP consequence records — typically one per input variant. Multiple records appear when a single notation matches multiple genomic positions.
truncatedNoTrue when transcript consequences were capped at max_transcript_consequences.
totalCountNoNumber of VEP consequence records returned.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedOutput schema / properties / results / items / properties / alleleString
      Added value: +{
      +  "description": "Reference and alternate alleles returned by VEP, separated by slashes.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / results / items / properties / colocatedVariants / items / properties / clinicalSignificance / description
      Previous value: -"Clinical significance terms from ClinVar (e.g. pathogenic, benign)."New value: +"Aggregate clinical significance terms for the colocated record; these do not classify the submitted allele."
    • addedOutput schema / properties / results / items / properties / colocatedVariants / items / properties / clinicalSignificanceByAllele
      Added value: +{
      +  "additionalProperties": {
      +    "items": {
      +      "type": "string"
      +    },
      +    "type": "array"
      +  },
      +  "description": "Clinical significance terms keyed by the allele explicitly annotated in the colocated record. Missing alleles have no reported attribution.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / results / items / properties / colocatedVariants / items / properties / clinicalSignificanceReferenceAllele
      Added value: +{
      +  "description": "Reference allele for the colocated clinical annotations, when reported.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / results / items / properties / transcriptConsequences / description
      Previous value: -"Per-transcript consequence details, capped to max_transcript_consequences. High-impact variants may affect many transcripts; focus on canonical transcripts (isCanonical from ensembl_lookup_gene) for primary effect. transcriptConsequencesTotal reports the full count."New value: +"Per-transcript consequence details, capped to max_transcript_consequences. High-impact variants may affect many transcripts; canonical and maneSelect identify annotated primary transcripts. transcriptConsequencesTotal reports the full count."
    • addedOutput schema / properties / results / items / properties / transcriptConsequences / items / properties / canonical
      Added value: +{
      +  "description": "Whether Ensembl marks this consequence transcript as canonical. Omitted when not reported.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / results / items / properties / transcriptConsequences / items / properties / maneSelect
      Added value: +{
      +  "description": "MANE Select RefSeq transcript accession, when supplied.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / results / items / properties / transcriptConsequences / items / properties / variantAllele
      Added value: +{
      +  "description": "Allele this transcript consequence describes, in the upstream genomic orientation.",
      +  "type": "string"
      +}
  2. Changed3 schema fields changed
    • changedInput schema / properties / species / description
      Previous value: -"Species in Ensembl internal format. Default is homo_sapiens. For non-human variants, set the appropriate species (e.g. mus_musculus for mouse). Use ensembl_list_species to discover valid values."New value: +"Species in Ensembl internal format. Default is homo_sapiens. For non-human variants, set the appropriate species (e.g. mus_musculus for mouse). Use ensembl_list_species with nameContains (a genus or common name) to find valid values."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_notation`: The variant notation is malformed or cannot be parsed by VEP. `not_found`: The variant location falls outside any known transcript or assembly region. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_notation`: The variant notation is malformed or cannot be parsed by VEP. `not_found`: The variant location falls outside any known transcript or assembly region. `invalid_species`: The species string was not recognized by Ensembl. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_notation",
      -  "not_found"
      -]New value: +[
      +  "invalid_notation",
      +  "not_found",
      +  "invalid_species"
      +]
  3. Changed2 schema fields changed
    • addedInput schema / properties / species / minLength
      Added value: +1
    • addedInput schema / properties / variant / minLength
      Added value: +1
  4. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "results",
      +      "totalCount"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `invalid_notation`: The variant notation is malformed or cannot be parsed by VEP. `not_found`: The variant location falls outside any known transcript or assembly region. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "invalid_notation",
      +            "not_found"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "results",
      -  "totalCount"
      -]
  5. Changed11 schema fields changed
    • addedInput schema / properties / include_all_colocated_pubmed
      Added value: +{
      +  "default": false,
      +  "description": "When true, return every PubMed ID for each colocated variant, overriding max_pubmed_ids_per_variant. Default false to keep responses compact.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / max_pubmed_ids_per_variant
      Added value: +{
      +  "default": 10,
      +  "description": "Maximum PubMed IDs to return per colocated known variant. Well-studied variants (e.g. rs334) cite 100+ papers; the default trims each list. Set to 0 to return every PubMed ID uncapped. pubmedTotal on each colocated variant reports the true pre-cap count. Ignored when include_all_colocated_pubmed is true.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / max_transcript_consequences
      Added value: +{
      +  "default": 10,
      +  "description": "Maximum transcript consequences to return per VEP record. High-impact variants can affect 60+ transcripts; the default keeps the response focused on the top consequences. Set to 0 to return every transcript consequence uncapped. transcriptConsequencesTotal on each record always reports the true pre-cap count.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The max_transcript_consequences limit applied.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no results are returned."New value: +"Guidance when no results are returned or when caps omitted detail."
    • changedOutput schema / properties / results / items / properties / colocatedVariants / items / properties / pubmed / description
      Previous value: -"PubMed IDs for literature associated with this variant."New value: +"PubMed IDs for literature associated with this variant, capped to max_pubmed_ids_per_variant. pubmedTotal reports the full count when the list was capped."
    • addedOutput schema / properties / results / items / properties / colocatedVariants / items / properties / pubmedTotal
      Added value: +{
      +  "description": "Total PubMed IDs available for this variant before the max_pubmed_ids_per_variant cap. Equals the returned pubmed length when the list was not capped.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / results / items / properties / transcriptConsequences / description
      Previous value: -"Per-transcript consequence details. High-impact variants may affect many transcripts; focus on canonical transcripts (isCanonical from ensembl_lookup_gene) for primary effect."New value: +"Per-transcript consequence details, capped to max_transcript_consequences. High-impact variants may affect many transcripts; focus on canonical transcripts (isCanonical from ensembl_lookup_gene) for primary effect. transcriptConsequencesTotal reports the full count."
    • addedOutput schema / properties / results / items / properties / transcriptConsequencesTotal
      Added value: +{
      +  "description": "Total transcript consequences available before the max_transcript_consequences cap. Equals the returned transcriptConsequences length when not capped.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Total transcript consequences returned across all records after the cap.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when transcript consequences were capped at max_transcript_consequences.",
      +  "type": "boolean"
      +}
  6. Changed1 schema field changed
    • changedInput schema / properties / variant / description
      Previous value: -"Variant in one of two formats: (1) HGVS notation — transcript-relative: ENST00000380152.8:c.2T>A; genomic: 13:g.32316462T>A; (2) Region+allele: chr:start:end:strand/allele — e.g. 1:65568:65568:1/T. For region+allele, strand is 1 (forward) or -1 (reverse); chromosome names use no \"chr\" prefix for vertebrates."New value: +"Variant in one of three formats: (1) HGVS notation — transcript-relative: ENST00000380152.8:c.2T>A; genomic: 13:g.32316462T>A; (2) Region+allele: chr:start:end:strand/allele — e.g. 1:65568:65568:1/T (strand is 1 for forward or -1 for reverse); (3) dbSNP rsID — e.g. rs334. Ensembl normalizes chromosome names; canonical vertebrate output omits the \"chr\" prefix, though a chr-prefixed name is also accepted."
  7. First observed

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower. The description nonetheless adds real behavioral context: default caps on transcript consequences and PubMed IDs, the fact that true totals are always reported, and the 0 / include_all_colocated_pubmed escape hatch. It does not discuss failure modes (bad HGVS, unknown rsID) or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and inputs are front-loaded effectively, but the single dense paragraph repeats the three input formats and the chr-prefix normalization rule almost word-for-word from the input schema, so several sentences do not earn their place. The genuinely additive material (default caps and how to disable them) is buried at the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be documented, yet the description still summarizes the key fields. It covers all three input formats, species defaults, and cap behavior — everything an agent needs to construct a correct call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining *why* the caps default as they do (well-studied variants like rs334 carry 60+ consequences and 100+ citations) and by cross-linking the two cap parameters to include_all_colocated_pubmed, though much of the format syntax is restated verbatim from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('predict the functional consequences of a sequence variant') and identifies the underlying engine (Ensembl VEP). It is clearly distinguishable from siblings like ensembl_query_region or ensembl_lookup_gene, which retrieve coordinates or annotations rather than predicting effect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent which of three input formats to supply and how chromosome naming is normalized, which is genuinely useful usage context. However, it never states when to prefer this tool over the sibling tools (e.g. query_region or lookup_gene) or any conditions under which it should not be used, so tool-selection guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.