Skip to main content
Glama

ensembl-mcp-server

by io.github.cyanheads

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

TableJSON 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 to discover 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

TableJSON 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. Dates show when Glama detected each change.

  1. 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"
-]
  2. 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"
+}
  3. 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."
  4. First observed

TDQS

A4.6/5.0
Behavior5/5

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

The description adds meaningful behavioral context beyond the readOnly/openWorld/idempotent annotations: it reveals that responses are compacted by default, that transcript and PubMed lists are capped, that truthful pre-cap totals are always reported, and that setting a cap to 0 or include_all_colocated_pubmed=true retrieves the full set. No contradiction with annotations.

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

Conciseness4/5

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

The description is front-loaded with the primary purpose and input formats, and it maintains a logical progression from purpose to inputs to outputs to defaults. Some sentences duplicate details already present in the parameter schema (e.g. chr-prefix normalization, set to 0 to return every transcript consequence), which slightly inflates length, but the overall structure remains efficient for the complexity.

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?

Given the output schema and annotations are present, the description covers all necessary information: purpose, accepted formats, example inputs, default behaviors, and how to disable caps. An agent has enough information to select and invoke the tool correctly without inspecting external resources.

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 coverage is 100%, so the baseline is 3. The description adds extra semantic value by explaining why the caps exist ('well-studied variants like rs334 otherwise carry 60+ consequences and 100+ citations') and clarifying how the caps interact with include_all_colocated_pubmed, going beyond the schema's functional definitions without being redundant.

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 opens with a specific verb and resource: 'Predict the functional consequences of a sequence variant using the Ensembl Variant Effect Predictor (VEP).' It goes on to enumerate exactly what is returned (consequence term, transcripts, genes, impact level, colocated variants), which clearly distinguishes it from sibling tools like ensembl_get_sequence, ensembl_lookup_gene, or ensembl_get_homology.

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

Usage Guidelines4/5

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

The description provides clear use context: 'Predict the functional consequences of a sequence variant' and lists the three accepted input formats. It does not explicitly say when not to use this tool or name alternative tools, but the domain is so specific and visually differentiated from the sibling names that an agent can confidently select it for variant effect prediction.

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

All ensembl-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0
Disambiguation5/5

Each tool targets a distinct genomic resource: homology, sequence, xrefs, species metadata, gene lookup, variant prediction, and region query. There is no overlap in their purposes, and the descriptions clearly delineate when to use each.

Naming Consistency5/5

All tool names follow the consistent pattern 'ensembl_' plus an action verb (get, list, lookup, predict, query) and a noun. The naming style is uniformly snake_case and lowercase, making the tool set predictable and easy to navigate.

Tool Count5/5

With 7 tools, the server is well-scoped for its purpose. Each tool addresses a core Ensembl query need without redundancy or bloat, fitting comfortably in the ideal range for a domain-specific toolkit.

Completeness5/5

The tool set covers the primary lifecycle of genomic investigation: discovering species, resolving gene identifiers, fetching sequences, obtaining cross-references, querying regions, finding homologs, and predicting variant consequences. There are no critical gaps for typical use cases.

Resources