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. The response returns up to max_results features (default 100) while totalCount always reports the full count; set max_results to 0 for every feature, or query a smaller region to see a different slice. Exon rows carry the parent transcript ID, so the same exon appears once per transcript it belongs to.

Input Schema

NameRequiredDescriptionDefault
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, 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.
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_resultsNoMaximum 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.

Output Schema

NameRequiredDescriptionDefault
capNoThe max_results limit applied to the feature list.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of features returned after the max_results cap.
noticeNoGuidance about the result set: empty, large, capped, 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.
featuresNoGenomic features found in the requested region, capped to max_results. totalCount reports the full count found before the cap.
truncatedNoTrue when the feature list was capped at max_results.
totalCountNoTotal number of features found in the region before the max_results cap. Exceeds the returned features count when the list was capped.
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. 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."
  2. 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."
  3. 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"
      +}
  4. 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"
      -]
  5. 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"
      +}
  6. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description layers on non-obvious behavior: chromosome-name normalization and chr-prefix omission in output, default gene-only feature set, the totalCount-vs-max_results split, max_results=0 as uncapped, and exon rows duplicating per parent transcript. This is exactly the extra context annotations cannot express.

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?

It is long but well front-loaded: purpose, return shape, then region format, then per-parameter caveats. Some sentences (region format, chr-prefix handling) restate schema content, which costs a point, but nothing is padding.

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?

Despite an output schema existing, the description still frames the return shape and adds the pagination/truncation semantics an agent needs to interpret results. Combined with the species-precedence and region-format rules, an agent has everything required to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds rationale the schema lacks: why feature defaults to gene, why variation should be limited to small loci, and the operational meaning of max_results=0 vs the default cap. The region-format explanation largely duplicates the schema, keeping it below 5.

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 five feature types returned. An agent can immediately distinguish this region-scan tool from ensembl_lookup_gene, ensembl_get_sequence, or ensembl_get_homology without opening any schema.

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?

Gives concrete usage context ('what's in this locus?', seeding follow-up lookups) and explicit guidance on when to include variation/regulatory/transcript/exon ('only when needed', with the 85 kb → 44,000 entries rationale). It does not explicitly name a sibling as the alternative for overlapping use cases, so it falls short of a 5.

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.