Skip to main content
Glama

ensembl-mcp-server

by io.github.cyanheads

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). Supports batch lookup of up to 20 IDs or symbols in one call via the ids or symbols field. 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 to discover valid species names.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoEnsembl stable gene ID (e.g. ENSG00000139618 or ENSG00000139618.7 with version). Species is not required for ID lookup.
idsNoBatch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. 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.
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 to discover valid values.
symbolsNoBatch 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.
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

TableJSON Schema
NameRequiredDescriptionDefault
geneNoSingle gene record. Present for symbol or id lookups.
batchNoBatch results. Present for ids or symbols lookups.
errorNoPresent when the call failed. Absent on success.

TDQS

A4.5/5.0
Behavior4/5

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds batch behavior, a 20-item cap, the succeeded/failed batch split, and the fact that returned stable IDs and coordinates feed other tools. It does not contradict the annotations, though it could say more about single-lookup failure or ambiguity behavior.

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

Conciseness5/5

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

The description front-loads the core purpose and outputs, then explains modes, defaults, and related tool usage. It is dense but every sentence contributes to correct tool selection or invocation, with no wasted words or tautological restating of the title.

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 read-only lookup tool with a rich input schema, an output schema, and strong annotations, the description covers the important gaps: entry-point role, species discovery, batch usage, exclusivity constraints, and linkage to downstream tools. Nothing critical is missing for an agent to successfully select and invoke 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?

The input schema already documents all six parameters, so the description does not need to re-explain them. It adds meaningful cross-parameter semantics: exactly one of symbol, id, ids, or symbols must be provided, and species handling changes depending on which mode is used. This goes beyond the schema's per-field descriptions, though the schema still carries most of the load.

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 states a specific verb and resource: 'Resolve a gene' to a concrete set of outputs (Ensembl ID, location, biotype, description, transcript list). It also distinguishes the tool from siblings by labeling it the 'entry point for most workflows' and explaining that the returned IDs and coordinates are inputs to other tools.

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 gives strong usage context: symbol vs stable ID lookup, batch mode, the one-of exclusion rule, species defaults, and a pointer to ensembl_list_species for valid species names. It does not fully state when to prefer sibling tools such as ensembl_query_region or ensembl_get_sequence instead, so it stops short of complete when/when-not guidance.

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