Skip to main content
Glama

Query Genomic Region

ensembl_query_region
Read-onlyIdempotent

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, plus the genome assembly the coordinates are on. Useful for "what's in this locus?" and for seeding follow-up lookups. Region format is chr:start-end with species set (e.g. 13:32315086-32400268 for the BRCA2 locus), or species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268), spanning at most 5,000,000 bases. 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 — requesting variation in an 85 kb region matches 44,000+ entries. Explicitly include variation, regulatory, transcript, or exon only when needed. Features come in one fixed order — by requested feature type, then start, end, ID, and parent transcript — max_results at a time (default 25); totalCount reports every match, and when more follow, nextOffset is the offset for the next page. Exon rows carry the parent transcript ID, so the same exon appears once per transcript it belongs to.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "region": "<region>"
    },
    "name": "ensembl_query_region"
  }
}

Input Schema

NameRequiredDescriptionDefault
offsetNo0-based position in the ordered features where the returned page starts. Default 0. Pass nextOffset from a previous response to fetch the following page; an offset at or past totalCount returns no features.
regionYesGenomic region as chr:start-end with species set (e.g. 13:32315086-32400268), or species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268), with start at or below end. Ensembl serves at most 5,000,000 bases per region; split a larger area into smaller windows. 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 mitochondrion is MT in vertebrates, mitochondrion_genome in Drosophila, and MtDNA in C. elegans; M and chrM are accepted only where Ensembl resolves them to the mitochondrion (Drosophila, for one) and otherwise fail as invalid_region naming the mitochondrion of the species. For large regions (>100 kb), limit to gene feature type to avoid overwhelming results.
biotypeNoOptional biotype filter (e.g. protein_coding, lncRNA), applied by Ensembl to gene, transcript, and exon features — an exon by its parent transcript's biotype. Variation and regulatory features carry no biotype and come back unfiltered. Case-sensitive (lncRNA, not lncrna); remove the filter to inspect every matching feature.
featureNoFeature types to retrieve — at least one. Default is gene only. Requesting variation in a large region can match tens of thousands of features. Include variation only for targeted small regions (single gene loci or smaller).
speciesNoSpecies in Ensembl internal format (e.g. homo_sapiens, mus_musculus). Required for a bare chr:start-end region; for the species:chr:start-end form the species in region takes precedence and this field is ignored. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values.
max_resultsNoNumber of features to return, counted from offset. Default 25; 0 returns 5,000 and says so. A value above 5,000 is clamped to 5,000 with a notice, or rejected where the server is set to reject it. totalCount always reports the full number found.

Output Schema

NameRequiredDescriptionDefault
capNoThe max_results value applied to this page, after any clamp to 5,000.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of features returned on this page.
noticeNoGuidance about the result set: empty, offset past the end, max_results clamped, more features following, biotype not applied to a requested type, large, or missing assembly.
regionNoThe region queried, as provided minus any species prefix (reported as species).
speciesNoThe species queried: the region's species prefix when it has one, otherwise the species field.
featuresNoOne page of the features overlapping the region: at most max_results, starting at offset, ordered by requested feature type, then start, end, ID, and parent transcript.
truncatedNoTrue when more features follow this page; pass nextOffset as offset to continue.
nextOffsetNoOffset of the first feature after this page — pass it as offset to fetch the next page. Present only when more features follow.
totalCountNoTotal number of features overlapping the region, before offset and max_results. Exceeds the returned features count when the list was paged.
assemblyNameNoGenome assembly the coordinates are on (e.g. GRCh38). Omitted only when it could not be resolved, in which case the notice says so.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changed
    • changedInput schema / properties / biotype / description
      Previous value: -"Optional biotype filter (e.g. protein_coding, lncRNA, SNV). Case-sensitive (lncRNA, not lncrna); remove the filter to inspect all matching feature types. Applied server-side by Ensembl. Not all feature types support biotype filtering."New value: +"Optional biotype filter (e.g. protein_coding, lncRNA), applied by Ensembl to gene, transcript, and exon features — an exon by its parent transcript's biotype. Variation and regulatory features carry no biotype and come back unfiltered. Case-sensitive (lncRNA, not lncrna); remove the filter to inspect every matching feature."
    • changedInput schema / properties / max_results / default
      Previous value: -100New value: +25
    • changedInput schema / properties / max_results / description
      Previous value: -"Maximum number of features to return. A gene-length region can hold tens of thousands of variation features; the default keeps the response compact. Set to 0 to return every feature uncapped. totalCount always reports the true number found before this cap."New value: +"Number of features to return, counted from offset. Default 25; 0 returns 5,000 and says so. A value above 5,000 is clamped to 5,000 with a notice, or rejected where the server is set to reject it. totalCount always reports the full number found."
    • removedInput schema / properties / max_results / maximum
      Removed value: -9007199254740991
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "0-based position in the ordered features where the returned page starts. Default 0. Pass nextOffset from a previous response to fetch the following page; an offset at or past totalCount returns no features.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / cap / description
      Previous value: -"The max_results limit applied to the feature list."New value: +"The max_results value applied to this page, after any clamp to 5,000."
    • changedOutput schema / properties / features / description
      Previous value: -"Genomic features found in the requested region, capped to max_results. totalCount reports the full count found before the cap."New value: +"One page of the features overlapping the region: at most max_results, starting at offset, ordered by requested feature type, then start, end, ID, and parent transcript."
    • changedOutput schema / properties / features / items / properties / biotype / description
      Previous value: -"Biotype of the feature (e.g. protein_coding, lncRNA, SNV)."New value: +"Biotype of a gene or transcript feature (e.g. protein_coding, lncRNA). Exon, variation, and regulatory rows carry none."
    • addedOutput schema / properties / nextOffset
      Added value: +{
      +  "description": "Offset of the first feature after this page — pass it as offset to fetch the next page. Present only when more features follow.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance about the result set: empty, large, capped, or missing assembly."New value: +"Guidance about the result set: empty, offset past the end, max_results clamped, more features following, biotype not applied to a requested type, large, or missing assembly."
    • changedOutput schema / properties / shown / description
      Previous value: -"Number of features returned after the max_results cap."New value: +"Number of features returned on this page."
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Total number of features found in the region before the max_results cap. Exceeds the returned features count when the list was capped."New value: +"Total number of features overlapping the region, before offset and max_results. Exceeds the returned features count when the list was paged."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the feature list was capped at max_results."New value: +"True when more features follow this page; pass nextOffset as offset to continue."
  2. Changed1 schema field changed
    • changedInput schema / properties / biotype / description
      Previous value: -"Optional biotype filter (e.g. protein_coding, lncRNA, SNV). Applied server-side by Ensembl. Not all feature types support biotype filtering."New value: +"Optional biotype filter (e.g. protein_coding, lncRNA, SNV). Case-sensitive (lncRNA, not lncrna); remove the filter to inspect all matching feature types. Applied server-side by Ensembl. Not all feature types support biotype filtering."
  3. Changed7 schema fields changed
    • changedInput schema / properties / region / description
      Previous value: -"Genomic region in chr:start-end format (e.g. 13:32315086-32400268). Ensembl serves at most 5,000,000 bases per region; split a larger area into smaller windows. 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."New value: +"Genomic region as chr:start-end with species set (e.g. 13:32315086-32400268), or species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268), with start at or below end. Ensembl serves at most 5,000,000 bases per region; split a larger area into smaller windows. 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 mitochondrion is MT in vertebrates, mitochondrion_genome in Drosophila, and MtDNA in C. elegans; M and chrM are accepted only where Ensembl resolves them to the mitochondrion (Drosophila, for one) and otherwise fail as invalid_region naming the mitochondrion of the species. For large regions (>100 kb), limit to gene feature type to avoid overwhelming results."
    • changedInput schema / properties / species / description
      Previous value: -"Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). Use ensembl_list_species to discover valid values."New value: +"Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). Required for a bare chr:start-end region; for the species:chr:start-end form the species in region takes precedence and this field is ignored. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values."
    • changedInput schema / required
      Previous value: -[
      -  "species",
      -  "region"
      -]New value: +[
      +  "region"
      +]
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_region`: The region string could not be parsed, contains invalid coordinates, or spans more than the 5,000,000-base maximum. `invalid_species`: The species string was not recognized by Ensembl. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_region`: The region string could not be parsed, has its start greater than its end, names the mitochondrion M or chrM where Ensembl resolves that to another region or none, contains coordinates outside the sequence region, or spans more than the 5,000,000-base maximum. `invalid_species`: The species (the species field or the region's species prefix) was not recognized by Ensembl. `missing_species`: A bare chr:start-end region was given without a species. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_region",
      -  "invalid_species"
      -]New value: +[
      +  "invalid_region",
      +  "invalid_species",
      +  "missing_species"
      +]
    • changedOutput schema / properties / region / description
      Previous value: -"The region queried, as provided."New value: +"The region queried, as provided minus any species prefix (reported as species)."
    • changedOutput schema / properties / species / description
      Previous value: -"The species queried."New value: +"The species queried: the region's species prefix when it has one, otherwise the species field."
  4. Changed14 schema fields changed
    • changedInput schema / properties / feature / description
      Previous value: -"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)."New value: +"Feature types to retrieve — at least one. Default is gene only. Requesting variation in a large region can match tens of thousands of features. Include variation only for targeted small regions (single gene loci or smaller)."
    • addedInput schema / properties / feature / minItems
      Added value: +1
    • addedInput schema / properties / max_results
      Added value: +{
      +  "default": 100,
      +  "description": "Maximum number of features to return. A gene-length region can hold tens of thousands of variation features; the default keeps the response compact. Set to 0 to return every feature uncapped. totalCount always reports the true number found before this cap.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / region / description
      Previous value: -"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."New value: +"Genomic region in chr:start-end format (e.g. 13:32315086-32400268). Ensembl serves at most 5,000,000 bases per region; split a larger area into smaller windows. 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."
    • addedInput schema / properties / region / minLength
      Added value: +1
    • addedInput schema / properties / species / minLength
      Added value: +1
    • addedOutput schema / properties / assemblyName
      Added value: +{
      +  "description": "Genome assembly the coordinates are on (e.g. GRCh38). Omitted only when it could not be resolved, in which case the notice says so.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The max_results limit applied to the feature list.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_region`: The region string could not be parsed or contains invalid coordinates. `invalid_species`: The species string was not recognized by Ensembl. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_region`: The region string could not be parsed, contains invalid coordinates, or spans more than the 5,000,000-base maximum. `invalid_species`: The species string was not recognized by Ensembl. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / features / description
      Previous value: -"Genomic features found in the requested region."New value: +"Genomic features found in the requested region, capped to max_results. totalCount reports the full count found before the cap."
    • changedOutput schema / properties / notice / description
      Previous value: -"Warning or guidance about the result set."New value: +"Guidance about the result set: empty, large, capped, or missing assembly."
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Number of features returned after the max_results cap.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Number of features returned. Note: very large regions may return truncated results."New value: +"Total number of features found in the region before the max_results cap. Exceeds the returned features count when the list was capped."
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when the feature list was capped at max_results.",
      +  "type": "boolean"
      +}
  5. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "features",
      +      "totalCount",
      +      "region",
      +      "species"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `invalid_region`: The region string could not be parsed or contains invalid coordinates. `invalid_species`: The species string was not recognized by Ensembl. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "invalid_region",
      +            "invalid_species"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "features",
      -  "totalCount",
      -  "region",
      -  "species"
      -]
  6. Changed3 schema fields changed
    • changedInput schema / properties / region / description
      Previous value: -"Genomic region in chr:start-end format (e.g. 13:32315086-32400268). Chromosome names use Ensembl format — no \"chr\" prefix for vertebrates (13, not chr13). For large regions (>100 kb), limit to gene feature type to avoid overwhelming results."New value: +"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."
    • addedOutput schema / properties / features / items / properties / parentId
      Added value: +{
      +  "description": "Parent transcript ID (ENST…) for exon features. An exon is reported once per parent transcript it belongs to, so the same exon ID can appear on multiple rows that differ only by this field — not duplicates.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / features / items / properties / rank
      Added value: +{
      +  "description": "Position (1-based) of an exon within its parent transcript.",
      +  "type": "number"
      +}
  7. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: it discloses the fixed result ordering (feature type, start, end, ID, parent transcript), pagination contract (max_results default 25, totalCount, nextOffset), the 5,000,000-base region ceiling, chromosome-name normalization and the chr-prefix omission in output, plus the exon-per-transcript duplication quirk.

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

Conciseness3/5

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

Front-loaded and logically ordered (what it does, format, defaults, pagination, caveats), but several passages duplicate schema text verbatim in spirit, notably the region format/chr-prefix rules and the max_results/maximum guidance. Trimming those repetitions would sharpen it without losing 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 six-parameter, paged, read-only genomic query tool, every decision an agent must make — region syntax, species precedence, biotype scoping, feature selection, paging loop — is covered. Output schema exists, and the description's return details are additive rather than redundant.

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 description mainly restates parameter facts already documented (region format, chr prefix handling, max_results default). It does add rationale the schema lacks — why feature defaults to gene, and the concrete match-volume example — but the payoff over the schema is modest.

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?

Opens with a specific verb+resource ("Find genomic features overlapping a chromosomal region") and enumerates the feature types returned. It also names what is returned per feature (stable ID, type, location, biotype, name) and the assembly, which distinguishes it clearly from siblings like ensembl_lookup_gene 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?

Gives an explicit use case ("what's in this locus?" and seeding follow-ups), states the default behavior (gene only) and when to widen it ("Explicitly include variation, regulatory, transcript, or exon only when needed"), and explains the cost of not doing so (44,000+ entries for variation in 85 kb). It also routes species resolution to ensembl_list_species.

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.