Skip to main content
Glama

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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "ensembl_lookup_gene"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoEnsembl 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.
idsNoBatch 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… or LRG 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.
symbolNoGene 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.
speciesNoSpecies 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.
symbolsNoBatch 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_transcriptsNoWhen 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

NameRequiredDescriptionDefault
geneNoSingle gene record. Present for an id lookup, or a symbol lookup that resolved to one gene.
batchNoBatch results. Present for ids or symbols lookups.
errorNoPresent when the call failed. Absent on success.
noticeNoGuidance for resubmitting unattempted batch queries.
ambiguousNoPresent 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.

  1. Changed1 schema field changed
    • changedInput schema / properties / ids / description
      Previous 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."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… or LRG 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."
  2. Changed19 schema fields changed
    • 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"
      +}
    • addedOutput 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"
      +}
    • addedOutput 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"
      +}
  3. Changed34 schema fields changed
    • 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"
      +}
  4. Changed2 schema fields changed
    • addedInput schema / properties / ids / items / minLength
      Added value: +1
    • addedInput schema / properties / symbols / items / minLength
      Added value: +1
  5. Changed5 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": [
      +      "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"
      +}
  6. Changed4 schema fields changed
    • 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."
  7. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnly/openWorld/idempotent; the description goes well beyond by disclosing alias resolution (HER2 → ERBB2 reported as matchedAlias), the ambiguous-result behavior with candidate listing for retry by id, and the batch truncation rule where only the first 20 distinct queries resolve and batch.omitted names the remainder. That truncation and ambiguity behavior are non-obvious traits an agent must know before calling.

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 purpose and return shape, then progressively details alias matching, batching, and the one-of constraint. Some content duplicates the schema's own parameter text (batch limits, exactly-one-of) and the species tip is repeated from the species parameter description, so it is not maximally tight.

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 six parameters, a 100%-covered schema and an existing output schema, the description supplies everything an agent needs: input modes, defaults, alias/ambiguity outcomes, and batch truncation behavior. Return-shape explanation is correctly omitted since the output schema covers it.

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, and the description adds real meaning on top: the mutual-exclusivity constraint across symbol/id/ids/symbols, the homo_sapiens default that applies only to symbol lookups, and synonym/ambiguous semantics for symbol parameters. It does not mention expand_transcripts, but the schema documents that fully with a default.

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) plus the resource (a gene) and enumerates exactly what is returned: Ensembl ID, genomic location chr:start-end:strand, biotype, description, transcript list. It also positions itself as the entry point whose outputs feed other tools, which separates it cleanly from siblings like ensembl_query_region or ensembl_get_sequence.

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?

Explicitly covers symbol lookup (BRCA2 + homo_sapiens) versus direct ID lookup (ENSG00000139618), states that species is only needed for symbol lookups, and enforces 'provide exactly one of symbol, id, ids, or symbols'. It also routes the agent to ensembl_list_species with nameContains for discovering valid species names, giving a concrete alternative for a prerequisite step.

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.