ensembl-mcp-server

Lookup Gene

ensembl_lookup_gene

Read-onlyIdempotent

Resolve a gene by symbol + species (or by stable ID) to its Ensembl ID, genomic location (chr:start-end:strand), biotype, description, and transcript list. Entry point for most workflows — the stable ID and coordinates returned here are inputs to other tools. Accepts both symbol lookup (BRCA2 + homo_sapiens) and direct ID lookup (ENSG00000139618). A symbol that is not a current gene name is matched against synonyms and former symbols (HER2 → ERBB2), reported as matchedAlias; when it maps to several genes the result is ambiguous, listing the candidates to retry by id. Supports batch submission of up to 1,000 IDs or symbols: the first 20 distinct queries are resolved, and batch.omitted names the unattempted remainder to resubmit. Provide exactly one of symbol, id, ids, or symbols. For symbol lookups species defaults to homo_sapiens (override for other organisms); for ID lookups species is not needed. Use ensembl_list_species with nameContains (a genus or common name) to find valid species names.

Input Schema

Name	Required	Description
`id`	No	Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix on an ENS… ID (ENSG00000139618.19) is dropped before the lookup, which returns the current version. Species is not required for ID lookup.
`ids`	No	Batch submission: up to 1,000 Ensembl stable IDs (ENSG…, ENST…); resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. A version suffix on an ENS… ID is dropped before the lookup. Returns a succeeded/failed/omitted partition; each attempted item carries its query — the ID as submitted, version included — and each failed item a reason and recovery. Provide exactly one of symbol, id, ids, or symbols.
`symbol`	No	Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Species defaults to homo_sapiens; set species for other organisms. Case-insensitive in most species. A synonym or former symbol (HER2, TB1) resolves too; one shared by several genes returns ambiguous with the candidates instead of gene.
`species`	No	Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Optional for symbol lookups — defaults to homo_sapiens; set it for other organisms. Use ensembl_list_species with nameContains (a genus or common name) to find valid values.
`symbols`	No	Batch submission: up to 1,000 gene symbols; resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed/omitted partition; each attempted item carries its submitted query. Synonyms and former symbols resolve with matchedAlias; one shared by several genes fails with reason ambiguous and its candidates. Provide exactly one of symbol, id, ids, or symbols.
`expand_transcripts`	No	When true, include the full transcript list in the response. Each transcript has its ID, biotype, canonical flag, and coordinates. Default is false to keep responses compact.

Output Schema

Name	Required	Description
`gene`	No	Single gene record. Present for an id lookup, or a symbol lookup that resolved to one gene.
`batch`	No	Batch results. Present for ids or symbols lookups.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance for resubmitting unattempted batch queries.
`ambiguous`	No	Present instead of gene when a symbol is not a current gene name and is a synonym or former symbol of several genes.

Schema Changelog

Changes observed during successful MCP inspections.

Changed19 schema fields changedOct 19, 2026

changedInput schema / properties / ids / description

Previous value: -"Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). A version suffix on an ENS… ID is dropped before the lookup. Returns a succeeded/failed split; each item carries its query — the ID as submitted, version included — and each failed item a reason and recovery. Provide exactly one of symbol, id, ids, or symbols."New value: +"Batch submission: up to 1,000 Ensembl stable IDs (ENSG…, ENST…); resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. A version suffix on an ENS… ID is dropped before the lookup. Returns a succeeded/failed/omitted partition; each attempted item carries its query — the ID as submitted, version included — and each failed item a reason and recovery. Provide exactly one of symbol, id, ids, or symbols."

changedInput schema / properties / ids / maxItems
```
Previous value: -20New value: +1000
```

changedInput schema / properties / symbols / description

Previous value: -"Batch lookup: up to 20 gene symbols. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed split; each item carries its submitted query. Synonyms and former symbols resolve with matchedAlias; one shared by several genes fails with reason ambiguous and its candidates. Provide exactly one of symbol, id, ids, or symbols."New value: +"Batch submission: up to 1,000 gene symbols; resolves the first 20 distinct trimmed queries. batch.omitted names the remainder to resubmit. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed/omitted partition; each attempted item carries its submitted query. Synonyms and former symbols resolve with matchedAlias; one shared by several genes fails with reason ambiguous and its candidates. Provide exactly one of symbol, id, ids, or symbols."

changedInput schema / properties / symbols / maxItems
```
Previous value: -20New value: +1000
```

addedOutput schema / properties / ambiguous / properties / candidates / items / properties / canonicalTranscript

Added value: +{
+  "description": "Canonical Ensembl transcript ID, including its version when supplied. Use for a primary protein sequence.",
+  "type": "string"
+}

addedOutput schema / properties / ambiguous / properties / candidates / items / properties / parentGeneId

Added value: +{
+  "description": "Parent gene stable ID for a transcript-ID lookup. Absent for other object types.",
+  "type": "string"
+}

addedOutput schema / properties / ambiguous / properties / candidates / items / properties / transcripts / items / properties / maneSelect
```
Added value: +{
+  "description": "MANE Select RefSeq transcript accession, when supplied by Ensembl.",
+  "type": "string"
+}
```

added

Output schema / properties / batch / properties / failed / items / properties / candidates / items / properties / canonicalTranscript

Added value: +{
+  "description": "Canonical Ensembl transcript ID, including its version when supplied. Use for a primary protein sequence.",
+  "type": "string"
+}

added

Output schema / properties / batch / properties / failed / items / properties / candidates / items / properties / parentGeneId

Added value: +{
+  "description": "Parent gene stable ID for a transcript-ID lookup. Absent for other object types.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / failed / items / properties / candidates / items / properties / transcripts / items / properties / maneSelect
```
Added value: +{
+  "description": "MANE Select RefSeq transcript accession, when supplied by Ensembl.",
+  "type": "string"
+}
```

addedOutput schema / properties / batch / properties / omitted

Added value: +{
+  "description": "Queries past the first 20 distinct items, in first-occurrence order. Resubmit these separately.",
+  "items": {
+    "description": "A distinct submitted query not attempted in this call.",
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / canonicalTranscript

Added value: +{
+  "description": "Canonical Ensembl transcript ID, including its version when supplied. Use for a primary protein sequence.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / parentGeneId

Added value: +{
+  "description": "Parent gene stable ID for a transcript-ID lookup. Absent for other object types.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / transcripts / items / properties / maneSelect
```
Added value: +{
+  "description": "MANE Select RefSeq transcript accession, when supplied by Ensembl.",
+  "type": "string"
+}
```

changedOutput schema / properties / batch / required

Previous value: -[
-  "succeeded",
-  "failed"
-]New value: +[
+  "omitted",
+  "succeeded",
+  "failed"
+]

addedOutput schema / properties / gene / properties / canonicalTranscript

Added value: +{
+  "description": "Canonical Ensembl transcript ID, including its version when supplied. Use for a primary protein sequence.",
+  "type": "string"
+}

addedOutput schema / properties / gene / properties / parentGeneId

Added value: +{
+  "description": "Parent gene stable ID for a transcript-ID lookup. Absent for other object types.",
+  "type": "string"
+}

addedOutput schema / properties / gene / properties / transcripts / items / properties / maneSelect

Added value: +{
+  "description": "MANE Select RefSeq transcript accession, when supplied by Ensembl.",
+  "type": "string"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance for resubmitting unattempted batch queries.",
+  "type": "string"
+}

Changed34 schema fields changedOct 13, 2026

changedInput schema / properties / id / description

Previous value: -"Ensembl stable gene ID (e.g. ENSG00000139618 or ENSG00000139618.7 with version). Species is not required for ID lookup."New value: +"Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix on an ENS… ID (ENSG00000139618.19) is dropped before the lookup, which returns the current version. Species is not required for ID lookup."

changedInput schema / properties / ids / description

Previous value: -"Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols."New value: +"Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). A version suffix on an ENS… ID is dropped before the lookup. Returns a succeeded/failed split; each item carries its query — the ID as submitted, version included — and each failed item a reason and recovery. Provide exactly one of symbol, id, ids, or symbols."

changedInput schema / properties / species / description

Previous value: -"Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Optional for symbol lookups — defaults to homo_sapiens; set it for other organisms. Use ensembl_list_species to discover valid values."New value: +"Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Optional for symbol lookups — defaults to homo_sapiens; set it for other organisms. Use ensembl_list_species with nameContains (a genus or common name) to find valid values."

changedInput schema / properties / symbol / description

Previous value: -"Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Species defaults to homo_sapiens; set species for other organisms. Case-insensitive in most species."New value: +"Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Species defaults to homo_sapiens; set species for other organisms. Case-insensitive in most species. A synonym or former symbol (HER2, TB1) resolves too; one shared by several genes returns ambiguous with the candidates instead of gene."

changedInput schema / properties / symbols / description

Previous value: -"Batch lookup: up to 20 gene symbols. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols."New value: +"Batch lookup: up to 20 gene symbols. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed split; each item carries its submitted query. Synonyms and former symbols resolve with matchedAlias; one shared by several genes fails with reason ambiguous and its candidates. Provide exactly one of symbol, id, ids, or symbols."

addedOutput schema / properties / ambiguous

Added value: +{
+  "additionalProperties": false,
+  "description": "Present instead of gene when a symbol is not a current gene name and is a synonym or former symbol of several genes.",
+  "properties": {
+    "candidates": {
+      "description": "Every gene the symbol maps to. Retry with id set to the intended one.",
+      "items": {
+        "additionalProperties": false,
+        "description": "A gene the symbol is a synonym or former symbol of.",
+        "properties": {
+          "assemblyName": {
+            "description": "Genome assembly name (e.g. GRCh38). All coordinates are relative to this assembly.",
+            "type": "string"
+          },
+          "biotype": {
+            "description": "Gene biotype (e.g. protein_coding, lncRNA, pseudogene).",
+            "type": "string"
+          },
+          "chromosome": {
+            "description": "Chromosome or sequence region name.",
+            "type": "string"
+          },
+          "description": {
+            "description": "Brief gene description from Ensembl.",
+            "type": "string"
+          },
+          "displayName": {
+            "description": "Gene symbol or display name (e.g. BRCA2, TP53).",
+            "type": "string"
+          },
+          "end": {
+            "description": "Gene end position on the chromosome (1-based).",
+            "type": "number"
+          },
+          "id": {
+            "description": "Ensembl gene stable ID (ENSG…). Use this as input to other Ensembl tools.",
+            "type": "string"
+          },
+          "species": {
+            "description": "Species in Ensembl internal format (e.g. homo_sapiens). Echoed from lookup.",
+            "type": "string"
+          },
+          "start": {
+            "description": "Gene start position on the chromosome (1-based).",
+            "type": "number"
+          },
+          "strand": {
+            "description": "Strand: 1 for forward, -1 for reverse.",
+            "type": "number"
+          },
+          "transcripts": {
+            "description": "Transcript list. Present only when expand_transcripts is true.",
+            "items": {
+              "additionalProperties": false,
+              "description": "A single transcript summary entry.",
+              "properties": {
+                "biotype": {
+                  "description": "Transcript biotype (e.g. protein_coding, lncRNA, retained_intron).",
+                  "type": "string"
+                },
+                "displayName": {
+                  "description": "Transcript display name.",
+                  "type": "string"
+                },
+                "end": {
+                  "description": "Transcript end position on the chromosome (1-based).",
+                  "type": "number"
+                },
+                "id": {
+                  "description": "Ensembl transcript stable ID (ENST…).",
+                  "type": "string"
+                },
+                "isCanonical": {
+                  "description": "True when this is the canonical transcript for the gene.",
+                  "type": "boolean"
+                },
+                "lengthInBp": {
+                  "description": "Transcript length in base pairs.",
+                  "type": "number"
+                },
+                "start": {
+                  "description": "Transcript start position on the chromosome (1-based).",
+                  "type": "number"
+                },
+                "strand": {
+                  "description": "Strand: 1 for forward, -1 for reverse.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "id",
+                "isCanonical"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "guidance": {
+      "description": "How to pick a candidate and retry by id.",
+      "type": "string"
+    },
+    "query": {
+      "description": "The submitted symbol.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "query",
+    "candidates",
+    "guidance"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / batch / properties / failed / description

Previous value: -"IDs/symbols that could not be resolved, with per-item query and error fields."New value: +"IDs/symbols that did not resolve to one gene, in input order."

changedOutput schema / properties / batch / properties / failed / items / additionalProperties
```
Previous value: -{}New value: +false
```

changedOutput schema / properties / batch / properties / failed / items / description

Previous value: -"A failed lookup entry with query (the submitted ID or symbol) and error (reason string) fields."New value: +"One unresolved ID or symbol."

addedOutput schema / properties / batch / properties / failed / items / properties / candidates

Added value: +{
+  "description": "Every gene the symbol maps to. Present only when reason is ambiguous.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A gene the symbol is a synonym or former symbol of.",
+    "properties": {
+      "assemblyName": {
+        "description": "Genome assembly name (e.g. GRCh38). All coordinates are relative to this assembly.",
+        "type": "string"
+      },
+      "biotype": {
+        "description": "Gene biotype (e.g. protein_coding, lncRNA, pseudogene).",
+        "type": "string"
+      },
+      "chromosome": {
+        "description": "Chromosome or sequence region name.",
+        "type": "string"
+      },
+      "description": {
+        "description": "Brief gene description from Ensembl.",
+        "type": "string"
+      },
+      "displayName": {
+        "description": "Gene symbol or display name (e.g. BRCA2, TP53).",
+        "type": "string"
+      },
+      "end": {
+        "description": "Gene end position on the chromosome (1-based).",
+        "type": "number"
+      },
+      "id": {
+        "description": "Ensembl gene stable ID (ENSG…). Use this as input to other Ensembl tools.",
+        "type": "string"
+      },
+      "species": {
+        "description": "Species in Ensembl internal format (e.g. homo_sapiens). Echoed from lookup.",
+        "type": "string"
+      },
+      "start": {
+        "description": "Gene start position on the chromosome (1-based).",
+        "type": "number"
+      },
+      "strand": {
+        "description": "Strand: 1 for forward, -1 for reverse.",
+        "type": "number"
+      },
+      "transcripts": {
+        "description": "Transcript list. Present only when expand_transcripts is true.",
+        "items": {
+          "additionalProperties": false,
+          "description": "A single transcript summary entry.",
+          "properties": {
+            "biotype": {
+              "description": "Transcript biotype (e.g. protein_coding, lncRNA, retained_intron).",
+              "type": "string"
+            },
+            "displayName": {
+              "description": "Transcript display name.",
+              "type": "string"
+            },
+            "end": {
+              "description": "Transcript end position on the chromosome (1-based).",
+              "type": "number"
+            },
+            "id": {
+              "description": "Ensembl transcript stable ID (ENST…).",
+              "type": "string"
+            },
+            "isCanonical": {
+              "description": "True when this is the canonical transcript for the gene.",
+              "type": "boolean"
+            },
+            "lengthInBp": {
+              "description": "Transcript length in base pairs.",
+              "type": "number"
+            },
+            "start": {
+              "description": "Transcript start position on the chromosome (1-based).",
+              "type": "number"
+            },
+            "strand": {
+              "description": "Strand: 1 for forward, -1 for reverse.",
+              "type": "number"
+            }
+          },
+          "required": [
+            "id",
+            "isCanonical"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / batch / properties / failed / items / properties / error

Added value: +{
+  "description": "What went wrong for this item.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / failed / items / properties / query

Added value: +{
+  "description": "The submitted ID or symbol.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / failed / items / properties / reason

Added value: +{
+  "description": "not_found: nothing matched. ambiguous: the symbol is a synonym of several genes, listed in candidates. unavailable: Ensembl did not answer the synonym lookup for this symbol after retries, so whether it matches is unknown — retry it.",
+  "enum": [
+    "not_found",
+    "ambiguous",
+    "unavailable"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / failed / items / properties / recovery
```
Added value: +{
+  "description": "The next step for this item.",
+  "type": "string"
+}
```
addedOutput schema / properties / batch / properties / failed / items / required
```
Added value: +[
+  "query",
+  "reason",
+  "error",
+  "recovery"
+]
```

changedOutput schema / properties / batch / properties / succeeded / description

Previous value: -"Gene records for IDs/symbols that resolved successfully. Same shape as gene."New value: +"Records for IDs/symbols that resolved to one gene, in input order."

changedOutput schema / properties / batch / properties / succeeded / items / additionalProperties
```
Previous value: -{}New value: +false
```

changedOutput schema / properties / batch / properties / succeeded / items / description

Previous value: -"A resolved gene record with the same shape as the gene output field."New value: +"A resolved gene record carrying its submitted query."

addedOutput schema / properties / batch / properties / succeeded / items / properties / assemblyName

Added value: +{
+  "description": "Genome assembly name (e.g. GRCh38). All coordinates are relative to this assembly.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / biotype

Added value: +{
+  "description": "Gene biotype (e.g. protein_coding, lncRNA, pseudogene).",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / chromosome

Added value: +{
+  "description": "Chromosome or sequence region name.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / description

Added value: +{
+  "description": "Brief gene description from Ensembl.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / displayName

Added value: +{
+  "description": "Gene symbol or display name (e.g. BRCA2, TP53).",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / end

Added value: +{
+  "description": "Gene end position on the chromosome (1-based).",
+  "type": "number"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / id

Added value: +{
+  "description": "Ensembl gene stable ID (ENSG…). Use this as input to other Ensembl tools.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / matchedAlias

Added value: +{
+  "description": "The submitted symbol, present when it matched a synonym or former symbol rather than the current gene name; displayName holds the current name.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / query

Added value: +{
+  "description": "The submitted ID or symbol this record resolved from.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / species

Added value: +{
+  "description": "Species in Ensembl internal format (e.g. homo_sapiens). Echoed from lookup.",
+  "type": "string"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / start

Added value: +{
+  "description": "Gene start position on the chromosome (1-based).",
+  "type": "number"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / strand

Added value: +{
+  "description": "Strand: 1 for forward, -1 for reverse.",
+  "type": "number"
+}

addedOutput schema / properties / batch / properties / succeeded / items / properties / transcripts

Added value: +{
+  "description": "Transcript list. Present only when expand_transcripts is true.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A single transcript summary entry.",
+    "properties": {
+      "biotype": {
+        "description": "Transcript biotype (e.g. protein_coding, lncRNA, retained_intron).",
+        "type": "string"
+      },
+      "displayName": {
+        "description": "Transcript display name.",
+        "type": "string"
+      },
+      "end": {
+        "description": "Transcript end position on the chromosome (1-based).",
+        "type": "number"
+      },
+      "id": {
+        "description": "Ensembl transcript stable ID (ENST…).",
+        "type": "string"
+      },
+      "isCanonical": {
+        "description": "True when this is the canonical transcript for the gene.",
+        "type": "boolean"
+      },
+      "lengthInBp": {
+        "description": "Transcript length in base pairs.",
+        "type": "number"
+      },
+      "start": {
+        "description": "Transcript start position on the chromosome (1-based).",
+        "type": "number"
+      },
+      "strand": {
+        "description": "Strand: 1 for forward, -1 for reverse.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "id",
+      "isCanonical"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / batch / properties / succeeded / items / required
```
Added value: +[
+  "id",
+  "query"
+]
```

changedOutput schema / properties / gene / description

Previous value: -"Single gene record. Present for symbol or id lookups."New value: +"Single gene record. Present for an id lookup, or a symbol lookup that resolved to one gene."

addedOutput schema / properties / gene / properties / matchedAlias

Added value: +{
+  "description": "The submitted symbol, present when it matched a synonym or former symbol rather than the current gene name; displayName holds the current name.",
+  "type": "string"
+}

Changed2 schema fields changedSep 24, 2026
- addedInput schema / properties / ids / items / minLength
```
Added value: +1
```
- addedInput schema / properties / symbols / items / minLength
```
Added value: +1
```

Changed5 schema fields changedAug 22, 2026

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": [
+      "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: `not_found`: The gene symbol or stable ID was not found in Ensembl. `invalid_species`: The species string was not recognized by Ensembl. `no_input`: Neither symbol, id, ids, nor symbols was provided. `conflicting_input`: More than one of symbol, id, ids, or symbols was provided. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "not_found",
+            "invalid_species",
+            "no_input",
+            "conflicting_input"
+          ],
+          "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"
+}

Changed4 schema fields changedJun 22, 2026

changedInput schema / properties / ids / description

Previous value: -"Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. Cannot be combined with symbol or id."New value: +"Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols."

changedInput schema / properties / species / description

Previous value: -"Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Required when using symbol. Default is homo_sapiens for symbol-based lookups. Use ensembl_list_species to discover valid values."New value: +"Species in Ensembl internal format: lowercase scientific name with underscores (e.g. homo_sapiens, mus_musculus, danio_rerio). Optional for symbol lookups — defaults to homo_sapiens; set it for other organisms. Use ensembl_list_species to discover valid values."

changedInput schema / properties / symbol / description

Previous value: -"Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Requires species to be set. Case-insensitive in most species."New value: +"Gene symbol to look up (e.g. BRCA2, TP53, EGFR). Species defaults to homo_sapiens; set species for other organisms. Case-insensitive in most species."

changedInput schema / properties / symbols / description

Previous value: -"Batch lookup: up to 20 gene symbols. Requires species to be set. Returns a succeeded/failed split. Cannot be combined with symbol, id, or ids."New value: +"Batch lookup: up to 20 gene symbols. Species defaults to homo_sapiens; set species for other organisms. Returns a succeeded/failed split. Provide exactly one of symbol, id, ids, or symbols."

First observedJun 7, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantive behavior beyond them: batch truncation to the first 20 distinct queries with batch.omitted naming the remainder, alias/former-symbol matching surfaced as matchedAlias, ambiguous multi-gene hits returning candidates rather than a gene, and version-suffix normalization on ENS… IDs.

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?

Front-loaded with the verb+resource+returns, then constraints, then routing to a sibling — a sensible order. It is dense prose in one block and the batch/alias/ambiguity details could be trimmed or split, but nearly every sentence carries invocation-relevant information.

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?

For a lookup tool with a full output schema, the description supplies everything needed to call it correctly: exactly-one-of input rule, species defaults and format, batch cap and resubmission behavior, and alias/ambiguity handling. Nothing material is left to inference.

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, but the description adds meaning the schema cannot express: the mutual-exclusivity rule across symbol/id/ids/symbols (no oneOf in the schema), the homo_sapiens default only for symbol lookups, and that species is unnecessary for ID lookups. These are genuinely decision-relevant cross-parameter semantics.

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?

States a specific verb (resolve/lookup) and resource (gene) plus the exact return payload: Ensembl ID, location, biotype, description, transcript list. It also positions itself against siblings by declaring it the entry point whose outputs feed other tools, so an agent can place it in the workflow without opening a schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use (entry point for most workflows), the alternatives/next steps (other tools consume the returned ID and coordinates), a routing rule for a sibling (use ensembl_list_species with nameContains to find valid species), and a hard input constraint (provide exactly one of symbol, id, ids, or symbols).

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 tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Lookup Gene

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources