ensembl-mcp-server
Server Details
Look up genes, fetch sequences, predict variant consequences, find orthologs and xrefs via Ensembl.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/ensembl-mcp-server
- GitHub Stars
- 2
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.6/5 across 7 of 7 tools scored.
Each tool targets a distinct operation: listing species, looking up genes, fetching sequences, finding homologs, retrieving cross-references, predicting variant effects, and querying genomic regions. There is no functional overlap.
All tools follow a consistent 'ensembl_verb_object' pattern using underscore_case (e.g., ensembl_list_species, ensembl_lookup_gene). The naming is predictable and unambiguous.
Seven tools provide a well-scoped coverage of the Ensembl API's core functionality for a bioinformatics MCP server. The count is appropriate for the domain's complexity.
The tool set covers the essential operations for genomic data access (species discovery, gene lookup, sequence, homology, xrefs, variant prediction, region queries). Minor gaps like batch sequence retrieval or gene list operations could be added, but the current set is largely complete.
Available Tools
7 toolsensembl_get_homologyGet Gene HomologsARead-onlyIdempotentInspect
Find orthologs and/or paralogs of a gene across species. Returns each homolog's stable ID, species, homology type (ortholog_one2one, ortholog_one2many, paralog_many2many, etc.), perc_id (percent identity), perc_pos (percent positives), and taxonomy level. Essential for cross-species research — for example, "what is the mouse equivalent of human TP53?" or "how conserved is BRCA2 across mammals?". Provide either symbol + species or a stable gene ID. Target species can be filtered to a single species or left open to return all available homologs.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Ensembl stable gene ID (e.g. ENSG00000139618). Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol. | |
| type | No | Type of homologs to return. orthologues: genes related by speciation (cross-species equivalents). paralogues: genes related by duplication (within or across species). all: both orthologs and paralogs. | orthologues |
| symbol | No | Gene symbol in the source species (e.g. BRCA2, TP53). Species defaults to homo_sapiens; set species for other organisms. Cannot be combined with id. | |
| species | No | Source species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species to discover valid values. | homo_sapiens |
| max_results | No | Maximum number of homologs to return. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs; the default keeps responses focused. Set to 0 to return every homolog uncapped. totalCount always reports the true number available before this cap. | |
| target_species | No | Filter to homologs in a single target species (e.g. mus_musculus for mouse). Omit to return homologs across all available species. Use ensembl_list_species to discover valid values. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The max_results limit applied to the homolog list. |
| shown | No | Number of homologs returned after the max_results cap. |
| notice | No | Guidance when no homologs are found or the list was capped. |
| queryId | Yes | The resolved Ensembl gene ID used for the homology query. |
| homologs | Yes | Homologous genes found for the query gene, capped to max_results. totalCount reports the full count available before the cap. |
| queryType | Yes | The homology type queried (orthologues, paralogues, or all). |
| truncated | No | True when the homolog list was capped at max_results. |
| totalCount | Yes | Total number of homologs available before the max_results cap. Exceeds the returned homologs count when the list was capped. |
| querySpecies | Yes | The source species used for the query. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnly, openWorld, idempotent. The description adds details: return fields (stable ID, species, homology type, perc_id, perc_pos, taxonomy level) and explains the max_results cap behavior. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise and front-loaded with the core purpose. Each sentence adds information, though it could be slightly trimmed (e.g., the example sentences are helpful but somewhat lengthy).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters (all described), an output schema exists, and the description covers input, output, filtering, and edge cases (e.g., max_results=0). It references sibling tools (ensembl_lookup_gene, ensembl_list_species) for support. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions (100% coverage). The description adds context: explains mutual exclusivity of id/symbol, clarifies that omitting target_species returns all species, and notes that max_results=0 uncaps. This extra guidance is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds orthologs and/or paralogs across species, with specific examples. It distinguishes from sibling tools (e.g., ensembl_lookup_gene returns stable IDs, not homologs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes concrete examples (mouse TP53, BRCA2 conservation) and explains input options (symbol+species or stable ID) and filtering. It lacks explicit 'when not to use' but the sibling list implies no overlap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ensembl_get_sequenceGet SequenceARead-onlyIdempotentInspect
Fetch the DNA, cDNA, CDS, or protein sequence for a gene, transcript, protein, or genomic region. Returns the sequence with its stable ID, molecule type, and character count — large sequences are returned in full but the length is stated so callers can budget context. The type parameter selects which sequence is fetched: genomic (default, includes introns), cdna (spliced transcript), cds (coding sequence only), protein. For region mode, set id to a region — either species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end with species set (e.g. id 13:32315086-32400268, species homo_sapiens). Protein sequences require a transcript or protein stable ID (ENST…/ENSP…), not a gene ID — use ensembl_lookup_gene with expand_transcripts=true to get the canonical transcript ID first.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Ensembl stable ID (ENSG…, ENST…, ENSP…) or a genomic region for region mode. Region accepts species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) or a bare chr:start-end (e.g. 13:32315086-32400268) when the species field is set. | |
| type | No | Sequence type to retrieve. genomic: full genomic DNA including introns (default). cdna: spliced transcript sequence (requires ENST… ID). cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). protein: amino acid sequence (requires ENST… or ENSP… ID). | genomic |
| species | No | Species in Ensembl internal format (e.g. homo_sapiens). Required for a bare chr:start-end region; optional for the species:chr:start-end form (the embedded species is used when the field is omitted). Optional for stable ID lookups — Ensembl infers species from the ID prefix. | |
| expand_3prime | No | Number of base pairs to extend downstream (3' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries. | |
| expand_5prime | No | Number of base pairs to extend upstream (5' direction) of the requested feature. Default 0. Only applies to genomic sequences and region queries. |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | The stable ID or region used for the lookup. |
| seq | Yes | The full sequence. DNA sequences use IUPAC nucleotide codes (ACGT + ambiguity codes). Protein sequences use single-letter amino acid codes. Large genomic sequences (e.g. 85 kb for BRCA2) are returned in full. |
| type | Yes | Sequence type returned (genomic, cdna, cds, or protein). |
| length | Yes | Sequence length in characters — nucleotides for genomic/cdna/cds, amino-acid residues for protein. Use this to budget context window usage before processing the sequence. |
| description | No | Sequence description from Ensembl, if provided. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that large sequences are returned in full with length stated for context budgeting, which adds value beyond the readOnlyHint and idempotentHint annotations. No contradictions; provides useful behavioral insights.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loading the main purpose, then detailing parameters and usage examples. Every sentence adds value, and it remains concise without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description covers the return format (stable ID, molecule type, character count) and addresses key aspects like type selection and region mode. Fully adequate for a sequence retrieval tool with annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description still enriches understanding by elaborating on the type parameter options and region mode syntax with explicit examples, such as 'homo_sapiens:13:32315086-32400268'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches DNA, cDNA, CDS, or protein sequence for various biological entities. It distinguishes from sibling tools like ensembl_get_homology, ensembl_lookup_gene, etc., by specifying the exact resource and action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool and explicitly mentions an alternative (ensembl_lookup_gene) for obtaining transcript IDs for protein sequences. It explains parameter roles but lacks an explicit 'when not to use' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ensembl_get_xrefsGet Cross-Database ReferencesARead-onlyIdempotentInspect
Retrieve cross-database references for a gene or feature — HGNC, UniProt, EntrezGene, OMIM, RefSeq, Reactome, and others. Returns each xref with its database name, primary ID, display ID, and description. The dbname filter narrows to specific databases; omit to return all xrefs. IDs returned here chain to protein (pubchem via UniProt), literature (pubmed via PubMed IDs), disease (OMIM via MIM_GENE), and pathway (Reactome) resources. Requires an Ensembl stable ID — use ensembl_lookup_gene to get the ENSG… ID first. Common dbname values: HGNC, Uniprot_gn, EntrezGene, MIM_GENE, RefSeq_mRNA, RefSeq_peptide, Reactome, GO (Gene Ontology), ChEMBL.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Ensembl stable gene ID (ENSG…) or transcript ID (ENST…). Use ensembl_lookup_gene to get the stable ID from a gene symbol. xrefs/id returns the full cross-reference set (56+ entries for well-annotated genes like BRCA2). | |
| dbname | No | Filter to a specific external database by its Ensembl internal name. Examples: HGNC (HGNC gene ID), Uniprot_gn (UniProt gene name), EntrezGene (NCBI Gene ID), MIM_GENE (OMIM disease gene), RefSeq_mRNA (NCBI RefSeq transcript), Reactome (pathway IDs), GO (Gene Ontology terms). Omit to return all available xrefs. |
Output Schema
| Name | Required | Description |
|---|---|---|
| xrefs | Yes | Cross-database references for the queried Ensembl ID. |
| notice | No | Guidance when no cross-references are found. |
| queriedId | Yes | The Ensembl stable ID that was queried. |
| totalCount | Yes | Total number of cross-references returned. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by explaining the return structure (fields: database name, primary ID, display ID, description) and how the returned IDs can chain to other resources (proteins, literature, diseases, pathways). No contradictions 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that effectively front-loads the main purpose, then provides usage order, then detail. It is concise with no wasted words, though it could be slightly more structured (e.g., bullet points) for even easier parsing. Still, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown but stated), the description explains what is returned and the relationship to other resources. It also covers the prerequisite tool (ensembl_lookup_gene) and the optional filtering. This is fairly complete for a lookup tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning beyond what the schema provides: it specifies that 'id' must be an Ensembl stable ID and gives examples of common dbname values (e.g., HGNC, Uniprot_gn, EntrezGene). This helps the agent select appropriate parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves cross-database references for a gene or feature, listing specific databases (HGNC, UniProt, etc.). It differentiates from siblings by explicitly mentioning the prerequisite use of ensembl_lookup_gene to obtain the stable ID, and its function is distinct from other tools like ensembl_get_homology 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: it requires an Ensembl stable ID and directs users to ensembl_lookup_gene first. It also explains how to use the dbname filter to narrow results. However, it does not explicitly state when not to use this tool, though the context is clear from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ensembl_list_speciesList Ensembl SpeciesARead-onlyIdempotentInspect
List species supported by Ensembl with display name, common name, assembly, taxon ID, and division. Required discovery step — species names like homo_sapiens are opaque to non-biologists and are the input format every other Ensembl tool expects. Filter by division to select one; use nameContains to find a species by partial name match. With no division, returns the endpoint default division — the vertebrates (~356 species on the default GRCh38 endpoint); pass a division to list that division.
| Name | Required | Description | Default |
|---|---|---|---|
| division | No | Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return the endpoint default division (vertebrates). | |
| nameContains | No | Case-insensitive substring filter applied locally after fetching. Matches against species name, display name, and common name. Example: "sapiens" matches homo_sapiens; "mouse" matches mus_musculus. |
Output Schema
| Name | Required | Description |
|---|---|---|
| notice | No | Guidance when the filter matches no species. |
| species | Yes | Species matching the filter criteria, sorted by internal name. |
| totalCount | Yes | Total number of matching species after local filtering. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so description adds context about default division behavior and filtering. No contradictions. Description adds value without over-justifying beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose. Every sentence adds value—no fluff. Efficiently conveys reason, filter options, and default behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given tool has only 2 parameters and output schema, description covers purpose, usage, filtering, and default. Completely sufficient for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds meaning: explains division enum values and default, gives concrete examples for nameContains. Significantly enhances understanding beyond schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'List', resource 'Ensembl species', and explicit fields (display name, common name, assembly, taxon ID, division) make the purpose crystal clear. Distinguishes from siblings like ensembl_get_homology which serve different functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it's a required discovery step because species names are opaque. Provides clear context on when to use division filter (select a division) vs nameContains (partial match) and notes default behavior with no division.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ensembl_lookup_geneLookup GeneARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Ensembl stable gene ID (e.g. ENSG00000139618 or ENSG00000139618.7 with version). Species is not required for ID lookup. | |
| ids | No | Batch lookup: up to 20 Ensembl stable IDs (ENSG…, ENST…). Returns a succeeded/failed split. 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. | |
| 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 to discover valid values. | |
| symbols | No | 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. | |
| 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 symbol or id lookups. |
| batch | No | Batch results. Present for ids or symbols lookups. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint. Description adds batch limits (20), succeeded/failed split, expand_transcripts behavior, and default species. Adds useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured, front-loaded with main action. Slightly verbose with repeated 'Provide exactly one' but overall efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers all key aspects: input modes, batch behavior, default species, parameter interrelations, and link to list_species. Output schema exists, so no need to detail return structure. Complete for a lookup tool with rich annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description reinforces mutual exclusivity, gives example IDs/symbols, explains default species, and notes case-insensitivity for symbols – adding flavor beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves a gene to Ensembl ID, genomic location, biotype, description, and transcript list. It distinguishes from siblings by calling it the entry point for most workflows and notes that returned IDs/coordinates feed other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use symbol+species vs ID lookup, batch via ids/symbols, mutual exclusivity of inputs, default species, and pointer to ensembl_list_species for valid species names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ensembl_predict_variantPredict Variant EffectARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| species | No | Species in Ensembl internal format. Default is homo_sapiens. For non-human variants, set the appropriate species (e.g. mus_musculus for mouse). Use ensembl_list_species to discover valid values. | homo_sapiens |
| variant | Yes | 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. | |
| max_pubmed_ids_per_variant | No | 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. | |
| max_transcript_consequences | No | 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. | |
| include_all_colocated_pubmed | No | When true, return every PubMed ID for each colocated variant, overriding max_pubmed_ids_per_variant. Default false to keep responses compact. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The max_transcript_consequences limit applied. |
| shown | No | Total transcript consequences returned across all records after the cap. |
| notice | No | Guidance when no results are returned or when caps omitted detail. |
| results | Yes | VEP consequence records — typically one per input variant. Multiple records appear when a single notation matches multiple genomic positions. |
| truncated | No | True when transcript consequences were capped at max_transcript_consequences. |
| totalCount | Yes | Number of VEP consequence records returned. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. The description adds crucial behavioral details: capping of transcript consequences and PubMed IDs with explanation of totals, and the ability to uncap by setting to 0 or using include_all_colocated_pubmed. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the purpose. It uses clear sections for input formats, and every sentence adds value without redundancy. It strikes an excellent balance between completeness and brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, output schema exists), the description is highly complete. It covers all input formats, explains the capping mechanism, and notes species flexibility. The existing output schema handles return values, so the description focuses on usage and behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant value beyond the schema by explaining the behavior of max_transcript_consequences and max_pubmed_ids_per_variant caps, as well as providing examples for the variant parameter formats. This enhances understanding beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: predicting functional consequences of sequence variants using Ensembl VEP. It specifies the verb 'predict' and the resource 'variant effect', distinguishing it from sibling tools like ensembl_get_sequence or ensembl_lookup_gene.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides excellent guidance on when to use this tool (to predict variant consequences) and details three input formats with examples. However, it does not explicitly state when NOT to use it or directly compare to sibling tools, which would have merited a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ensembl_query_regionQuery Genomic RegionARead-onlyIdempotentInspect
Find genomic features overlapping a chromosomal region: genes, transcripts, variants, regulatory elements, or exons. Returns each feature with its stable ID, type, location, biotype, and name. Useful for "what's in this locus?" and for seeding follow-up lookups. Region format is chr:start-end (e.g. 13:32315086-32400268 for the BRCA2 locus). Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (13, not chr13); a chr-prefixed name like chr13 is also accepted. The feature parameter defaults to gene only to prevent overwhelming returns — requesting variation in an 85 kb region returns 44,000+ entries. Explicitly include variation, regulatory, transcript, or exon only when needed. Exon rows carry the parent transcript ID, so the same exon appears once per transcript it belongs to.
| Name | Required | Description | Default |
|---|---|---|---|
| region | Yes | Genomic region in chr:start-end format (e.g. 13:32315086-32400268). Ensembl normalizes chromosome names and canonical vertebrate output omits the chr prefix (13, not chr13); a chr-prefixed name like chr13 is also accepted. For large regions (>100 kb), limit to gene feature type to avoid overwhelming results. | |
| biotype | No | Optional biotype filter (e.g. protein_coding, lncRNA, SNV). Applied server-side by Ensembl. Not all feature types support biotype filtering. | |
| feature | No | Feature types to retrieve. Default is gene only. Requesting variation in a large region can return tens of thousands of features. Include variation only for targeted small regions (single gene loci or smaller). | |
| species | Yes | Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). Use ensembl_list_species to discover valid values. |
Output Schema
| Name | Required | Description |
|---|---|---|
| notice | No | Warning or guidance about the result set. |
| region | Yes | The region queried, as provided. |
| species | Yes | The species queried. |
| features | Yes | Genomic features found in the requested region. |
| totalCount | Yes | Number of features returned. Note: very large regions may return truncated results. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=true. The description adds behavioral details: region format normalization (chr prefix), default feature type to prevent overload, and exon rows with parent transcript IDs. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with purpose first, then usage notes, format details, and warnings. It is concise but slightly lengthy; still every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, output schema present, and no nested objects, the description covers return values, region format, normalization, default behavior, and performance caveats. It is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds context beyond the schema, such as performance implications of feature selection and the concrete example of 44k+ variation entries. This enhances semantic understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds genomic features overlapping a chromosomal region, listing specific feature types (genes, transcripts, etc.). It distinguishes from sibling tools by focusing on region-based queries for 'what's in this locus?' rather than single-gene lookups or sequence retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use: for exploring a genomic locus and seeding follow-up lookups. Warns about large returns when requesting variation and recommends limiting to gene by default. Could mention alternatives like ensembl_lookup_gene for single-gene queries, but overall helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!