Skip to main content
Glama

gnomad-genetics-mcp-server

gnomad-genetics-mcp-server: list gene variants

gnomad_list_gene_variants
Read-onlyIdempotent

List every gnomAD variant in a gene, transcript, or region with allele frequencies and predicted consequences, optionally filtered to one consequence class (lof, missense, synonymous, other) and/or a maximum allele frequency. A result too large to inline is staged on a DataCanvas table named gene_variants, returned as canvas_id and table_name beside an inline preview — call gnomad_dataframe_describe for its columns, then gnomad_dataframe_query to rank by AF, count by consequence, or group across every row rather than the preview. A result that fits inline stages no table unless canvas_id is supplied. When the canvas is disabled (CANVAS_PROVIDER_TYPE != duckdb) the tool returns a capped inline preview and the SQL path is unavailable. Supply exactly one of gene, transcript_id, or region. Echoes the effective dataset and build. Data source: gnomAD (Broad Institute) — https://gnomad.broadinstitute.org/

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
geneNoGene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene. Mitochondrial genes (e.g. MT-TL1) are not served. Mutually exclusive with transcript_id and region; blank means omitted.
max_afNoKeep only variants with allele frequency ≤ this value (0–1). Variants with null AF are always kept.
regionNoGenomic region chrom-start-stop (1-based inclusive, e.g. 13-32315474-32400266): chromosome 1–22, X, or Y with an optional chr prefix (mitochondrial regions are not served), a span (stop − start) under 2,500,000 bp, and at most ~30,000 variants. Mutually exclusive with gene and transcript_id.
datasetNognomAD dataset: gnomad_r4 (GRCh38, default), gnomad_r3 (GRCh38), gnomad_r2_1 (GRCh37), exac (GRCh37). Echoed in output.
canvas_idNoOptional canvas ID from a prior call, to reuse the same canvas. When supplied, this call always writes its result to the gene_variants table on that canvas, replacing (not appending to) the previous one — even when the result fits inline; a result with no variants removes the table. Omit to stage on a fresh canvas only when the result is too large to inline.
transcript_idNoEnsembl transcript ID (e.g. ENST00000302118). Mutually exclusive with gene and region; blank means omitted.
reference_genomeNoReference build. Derived from dataset when omitted (v4/v3=GRCh38, v2.1/ExAC=GRCh37). If supplied it must match the dataset, or the call is rejected. Keep aligned with ensembl coordinates.
consequence_classNoKeep only variants in this consequence class. Omit to return all classes.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
totalNoTotal matching variants, including any beyond the preview.
noticeNoGuidance when no variants matched, when the canvas is disabled and the preview is capped, and — when a table was staged — its name with the next steps: gnomad_dataframe_describe, then gnomad_dataframe_query.
datasetNoEffective gnomAD dataset.
previewNoInline preview rows — the immediate answer; every matching variant unless spilled.
spilledNoTrue when the result exceeded the inline preview budget, so the preview holds only the first rows and table_name holds them all.
canvas_idNoCanvas holding table_name (or the canvas_id you supplied) — pass it to gnomad_dataframe_describe, then gnomad_dataframe_query. Empty when this call used no canvas: the result fit inline and no canvas_id was supplied, or the canvas is disabled.
table_nameNoCanvas table this call staged (gene_variants), holding every matching variant — inspect it with gnomad_dataframe_describe, then query it with gnomad_dataframe_query. Empty when this call staged no table.
reference_genomeNoEffective reference build.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / gene / description
      Previous value: -"Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene. Mutually exclusive with transcript_id and region; blank means omitted."New value: +"Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene. Mitochondrial genes (e.g. MT-TL1) are not served. Mutually exclusive with transcript_id and region; blank means omitted."
    • changedInput schema / properties / region / anyOf
      Previous value: -[
      -  {
      -    "const": "",
      -    "type": "string"
      -  },
      -  {
      -    "description": "Genomic region chrom-start-stop (1-based inclusive, e.g. 13-32315474-32400266).",
      -    "pattern": "^[0-9XYM]+-\\d+-\\d+$",
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "const": "",
      +    "type": "string"
      +  },
      +  {
      +    "description": "Genomic region chrom-start-stop (1-based inclusive, e.g. 13-32315474-32400266) on chromosome 1–22, X, or Y, optional chr prefix.",
      +    "pattern": "^(?:chr)?[0-9A-Z]+-\\d+-\\d+$",
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / region / description
      Previous value: -"Genomic region chrom-start-stop (1-based inclusive). Mutually exclusive with gene and transcript_id."New value: +"Genomic region chrom-start-stop (1-based inclusive, e.g. 13-32315474-32400266): chromosome 1–22, X, or Y with an optional chr prefix (mitochondrial regions are not served), a span (stop − start) under 2,500,000 bp, and at most ~30,000 variants. Mutually exclusive with gene and transcript_id."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_target`: Not exactly one of gene, transcript_id, or region was supplied. `incoherent_build`: reference_genome was supplied but does not match the dataset. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_target`: Not exactly one of gene, transcript_id, or region was supplied. `incoherent_build`: reference_genome was supplied but does not match the dataset. `invalid_region`: The region names a chromosome outside 1–22, X, Y, or breaks the coordinate bounds. `region_too_large`: The region spans 2,500,000 bp or more, or holds more variants (~30,000) than gnomAD lists at once. `mitochondrial_unsupported`: The gene, transcript, or region is on the mitochondrial chromosome (M or MT). `graphql_error`: gnomAD rejected the variant-list query with a GraphQL error. `upstream_unavailable`: gnomAD stayed unavailable or throttled through every retry. `upstream_timeout`: Every attempt to reach gnomAD timed out. `upstream_access`: gnomAD refused the request (access denied). `invalid_upstream_response`: gnomAD kept answering with a response that failed validation. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_target",
      -  "incoherent_build"
      -]New value: +[
      +  "invalid_target",
      +  "incoherent_build",
      +  "invalid_region",
      +  "region_too_large",
      +  "mitochondrial_unsupported",
      +  "graphql_error",
      +  "upstream_unavailable",
      +  "upstream_timeout",
      +  "upstream_access",
      +  "invalid_upstream_response"
      +]
  2. Changed12 schema fields changed
    • changedInput schema / properties / canvas_id / description
      Previous value: -"Optional canvas ID from a prior call, to reuse the same canvas. Reusing it REPLACES (overwrites) the gene_variants table with this call's results — it does not append. Omit to start a fresh canvas; the response returns a new one."New value: +"Optional canvas ID from a prior call, to reuse the same canvas. When supplied, this call always writes its result to the gene_variants table on that canvas, replacing (not appending to) the previous one — even when the result fits inline; a result with no variants removes the table. Omit to stage on a fresh canvas only when the result is too large to inline."
    • addedInput schema / properties / gene / anyOf
      Added value: +[
      +  {
      +    "description": "Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene.",
      +    "minLength": 2,
      +    "type": "string"
      +  },
      +  {
      +    "description": "Blank — the gene is treated as omitted.",
      +    "maxLength": 0,
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / gene / description
      Previous value: -"Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene."New value: +"Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene. Mutually exclusive with transcript_id and region; blank means omitted."
    • removedInput schema / properties / gene / minLength
      Removed value: -2
    • removedInput schema / properties / gene / type
      Removed value: -"string"
    • changedInput schema / properties / transcript_id / description
      Previous value: -"Ensembl transcript ID (e.g. ENST00000302118). Mutually exclusive with gene and region."New value: +"Ensembl transcript ID (e.g. ENST00000302118). Mutually exclusive with gene and region; blank means omitted."
    • changedOutput schema / properties / canvas_id / description
      Previous value: -"Canvas ID — pass to gnomad_dataframe_query. Empty string when canvas is disabled."New value: +"Canvas holding table_name (or the canvas_id you supplied) — pass it to gnomad_dataframe_describe, then gnomad_dataframe_query. Empty when this call used no canvas: the result fit inline and no canvas_id was supplied, or the canvas is disabled."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no variants matched, or when the canvas is disabled and the preview is capped."New value: +"Guidance when no variants matched, when the canvas is disabled and the preview is capped, and — when a table was staged — its name with the next steps: gnomad_dataframe_describe, then gnomad_dataframe_query."
    • changedOutput schema / properties / preview / description
      Previous value: -"Inline preview rows — the immediate answer."New value: +"Inline preview rows — the immediate answer; every matching variant unless spilled."
    • changedOutput schema / properties / spilled / description
      Previous value: -"True when the full result was staged on the canvas beyond the preview."New value: +"True when the result exceeded the inline preview budget, so the preview holds only the first rows and table_name holds them all."
    • changedOutput schema / properties / table_name / description
      Previous value: -"Canvas table holding the full set (gene_variants); empty when not spilled."New value: +"Canvas table this call staged (gene_variants), holding every matching variant — inspect it with gnomad_dataframe_describe, then query it with gnomad_dataframe_query. Empty when this call staged no table."
    • changedOutput schema / properties / total / description
      Previous value: -"Total matching variants (staged row count when spilled, else preview length)."New value: +"Total matching variants, including any beyond the preview."
  3. Changed5 schema fields changed
    • addedInput schema / properties / canvas_id / pattern
      Added value: +"^[A-Za-z0-9_-]{10}$"
    • removedOutput schema / properties / preview / items / properties / af / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / preview / items / properties / af / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / preview / items / properties / consequence / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / preview / items / properties / consequence / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  4. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, openWorldHint), and the description goes well beyond them: staging semantics (table named gene_variants, canvas_id + table_name plus inline preview), replacement-not-append behavior, table removal on empty results, no table when the result fits inline and no canvas_id is given, and capped preview degradation when canvas is disabled. This is exactly the extra behavioral context that agents need.

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?

Dense but front-loaded: purpose first, then routing, then edge cases and provenance. Every sentence carries information (canvas replacement, disabled-canvas fallback, dataset echoing). The long canvas passage is somewhat packed, which keeps it from a 5, but there is little filler.

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?

With an output schema present, return-value shape need not be explained, and the description still covers the non-obvious return facts (canvas_id/table_name, inline preview, echoed dataset/build). Combined with the schema's mutual-exclusion and format constraints, 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; the description adds the cross-parameter constraint ("Supply exactly one of gene, transcript_id, or region") and the filter semantics for consequence_class and max_af that tie the parameters to the tool's purpose. It does not add syntax or format detail beyond the schema, so it clears the baseline but not by much.

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 opens with a specific verb and resource ("List every gnomAD variant in a gene, transcript, or region") plus the payload (allele frequencies and predicted consequences) and the filter scope. That is enough to separate it from gnomad_get_variant (single variant), gnomad_get_gene_constraint (aggregate constraint), and the dataframe siblings (post-processing).

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?

Strong routing guidance: it tells the agent to call gnomad_dataframe_describe then gnomad_dataframe_query for ranking/grouping across the full row set, and warns that the SQL path is unavailable when CANVAS_PROVIDER_TYPE != duckdb. It also spells out the exactly-one-selector rule. It stops short of naming retrieval alternatives (e.g. when to prefer gnomad_get_variant instead), so no explicit when-not for sibling selection.

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.