Skip to main content
Glama

gnomad-genetics-mcp-server

by io.github.cyanheads

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. The full result is staged on a DataCanvas table named gene_variants and an inline preview is returned alongside canvas_id and table_name — run gnomad_dataframe_query against them to rank by AF, count by consequence, or group across the complete set rather than the preview. When the canvas is disabled (CANVAS_PROVIDER_TYPE != duckdb) the tool returns a capped inline preview with spilled=false and canvas_id empty; the SQL path is then 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.
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). 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. 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.
transcript_idNoEnsembl transcript ID (e.g. ENST00000302118). Mutually exclusive with gene and region.
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 (staged row count when spilled, else preview length).
noticeNoGuidance when no variants matched, or when the canvas is disabled and the preview is capped.
datasetNoEffective gnomAD dataset.
previewNoInline preview rows — the immediate answer.
spilledNoTrue when the full result was staged on the canvas beyond the preview.
canvas_idNoCanvas ID — pass to gnomad_dataframe_query. Empty string when canvas is disabled.
table_nameNoCanvas table holding the full set (gene_variants); empty when not spilled.
reference_genomeNoEffective reference build.

TDQS

A3.9/5.0
Behavior1/5

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

The description is transparent about staging results and about the destructive replacement behavior: 'Reusing it REPLACES (overwrites) the gene_variants table... it does not append.' However, this directly contradicts the annotation readOnlyHint=true, which indicates the tool does not modify its environment. Because the description contradicts structured annotations, the score must be 1 and this is an Annotation Contradiction.

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

Conciseness5/5

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

The description is long but every sentence earns its place: core behavior, optional filters, staging flow, disabled-canvas fallback, selector exclusivity, dataset/build echo, and data source. The main purpose is front-loaded, and the canvas details are logically sequenced without 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?

Given the tool's complexity — 8 parameters, canvas staging, and a disabled-canvas fallback — the description is complete. It covers result staging, inline preview, canvas_id semantics, capped preview behavior when canvas is disabled, selector exclusivity, and dataset/build behavior. Since an output schema exists, not detailing return fields is acceptable.

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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by stating the cross-parameter constraint 'Supply exactly one of gene, transcript_id, or region,' explaining what canvas_id reuse does, and noting the effective dataset/build echo. This is meaningful context that the individual property descriptions do not fully convey.

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 with allele frequencies and predicted consequences.' This clearly distinguishes it from siblings like gnomad_get_variant (single variant) and gnomad_get_coverage or gnomad_get_gene_constraint. An agent can tell what this tool does without opening the 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?

The description gives clear usage context: filter by consequence class and max AF, supply exactly one of gene/transcript/region, and use gnomad_dataframe_query to operate on the full staged result. It does not explicitly contrast this tool with alternatives such as when to prefer gnomad_get_variant or search_clinvar, so it stops 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.

All gnomad-genetics-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.2/5.0
Disambiguation5/5

Every tool has a clearly distinct role: specific variant lookup, gene constraint, coverage, ClinVar search, and canvas SQL describe/query. The closest pair, gnomad_get_variant and gnomad_list_gene_variants, is separated by input type and the depth of data returned.

Naming Consistency4/5

Most tools follow a gnomad_<verb>_<object> pattern like get_coverage, get_variant, list_gene_variants, and search_clinvar. The two canvas helpers break this with gnomad_dataframe_describe and gnomad_dataframe_query, but they form a readable and internally consistent sub-pattern.

Tool Count5/5

Seven tools is well-scoped for a gnomAD/ClinVar genetics server. Each tool addresses a distinct query need, and the two dataframe utilities add real analytic value without bloating the API.

Completeness5/5

The surface covers the core read-only workflows: variant lookup, gene variant listing with filters, constraint, coverage, and ClinVar curation. The dataframe query path prevents dead ends when working with large staged result sets.

Resources