gnomad-genetics-mcp-server: list gene variants
gnomad_list_gene_variantsList every gnomAD variant in a gene, transcript, or region with allele frequencies, filtering allele frequencies, zygosity counts, predicted consequences with LOFTEE's loss-of-function call, and QC status, optionally filtered to one consequence class (lof, missense, synonymous, other), a LOFTEE confidence (lof_confidence HC or LC), a maximum allele frequency, and/or a maximum filtering allele frequency (faf95_max, the value to test against a disease threshold such as ACMG/AMP BA1 or BS1). Pass annotations: true to add each row's HGVS c. and p. notation, LOFTEE filter and flags, and rsIDs. Every row carries its exome and genome QC filters and a qc_status; qc_filtered counts the matching variants that failed QC in every callset carrying them (often AC0, no high-quality carrier, at AF 0), which gnomAD's browser hides by default — read them as low-confidence, not observed variants, or pass pass_only to drop them. Each call returns one page: up to limit matching variants from offset, in gnomAD's genomic order, with total counting every match; pass next_offset as offset until it is null. gnomAD lists a target only whole, so each page re-fetches the whole target — page a large gene with filters and a large limit. At offset 0, a result too large to inline is also staged on a DataCanvas table named gene_variants holding every matching variant, returned as canvas_id and table_name — 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 one page. A result that fits inline stages no table unless canvas_id is supplied, and a page past offset 0 never stages. Supply exactly one of gene, transcript_id, or region. Echoes the resolved target, the row filters, and the effective dataset and build. Data source: gnomAD (Broad Institute) — https://gnomad.broadinstitute.org/
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "gnomad_list_gene_variants"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gene | No | 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. | |
| limit | No | Matching variants on this page. Default 25; a value above 3,000 is clamped to 3,000, with a notice. | |
| max_af | No | Keep only variants with allele frequency ≤ this value (0–1). Variants with null AF are always kept. | |
| offset | No | Zero-based position, among the variants the filters keep, of the first one on this page. Pass next_offset from the previous call to continue. | |
| region | No | Genomic region chrom-start-stop (1-based inclusive, e.g. 1-55039447-55064852): 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. | |
| dataset | No | gnomAD dataset, default gnomad_r4: gnomad_r4 and its subset gnomad_r4_non_ukb (GRCh38); gnomad_r3 and its subsets gnomad_r3_controls_and_biobanks, gnomad_r3_non_cancer, gnomad_r3_non_neuro, gnomad_r3_non_topmed, gnomad_r3_non_v2 (GRCh38); gnomad_r2_1 and its subsets gnomad_r2_1_controls, gnomad_r2_1_non_cancer, gnomad_r2_1_non_neuro, gnomad_r2_1_non_topmed (GRCh37); exac (GRCh37). A subset keeps only part of its parent release's samples (non_cancer leaves out cancer-study samples, non_ukb UK Biobank's) and can leave a callset unchanged: gnomad_r4_non_ukb genome counts equal gnomad_r4's, and gnomad_r2_1_non_cancer genome counts equal gnomad_r2_1's. No subset publishes joint data, and gnomAD publishes no subset coverage or constraint, so those come from the parent. Echoed in output. | |
| max_faf | No | Keep only variants whose filtering allele frequency (faf95_max) is ≤ this value (0–1) — the test against a disease threshold such as ACMG/AMP BA1 or BS1. Variants with a null faf95_max are always kept, and a notice counts them among total. gnomad_r3, its subsets, and exac list rows carry no FAF, so there it filters nothing and the notice says so. | |
| canvas_id | No | Optional canvas ID from a prior call, to reuse the same canvas. When supplied, a call at offset 0 always writes its result to the gene_variants table on that canvas, replacing (not appending to) the previous one, its columns included: the table takes this call's annotations shape — even when the result fits inline; a result with no variants removes the table. A page past offset 0 leaves the table as it was. Omit to stage on a fresh canvas only when the result is too large to inline. | |
| pass_only | No | Keep only variants that passed gnomAD QC in at least one callset carrying them (qc_status pass), with the counts gnomAD's browser table shows by default: a row without joint data (every dataset but gnomad_r4, gnomad_r4_non_ukb included) reads ac, an, af, homozygote_count, hemizygote_count, and faf95_max from its passing callsets only, and max_af and max_faf filter on those values; gnomad_r4 rows keep their joint counts. The drop follows consequence_class, lof_confidence, max_af, and max_faf, and qc_filtered still counts the dropped rows. Omit to list every matching variant with its QC columns and a QC-failed callset's counts included — a single-position region then never reads as absent because of QC. | |
| annotations | No | Add five columns describing each row's transcript_id after every default column, on the rows and in the staged gene_variants table: hgvsc, hgvsp, lof_filter, lof_flags, and rsids (pipe-joined). Omitted or false, the rows and the table carry none of them. A column toggle, not a filter: it keeps every row and filters does not echo it. It widens every row by about a quarter and every page's re-fetch of the target from gnomAD by about as much. | |
| transcript_id | No | Ensembl transcript ID (e.g. ENST00000302118). Mutually exclusive with gene and region; blank means omitted. | |
| lof_confidence | No | Keep only variants whose lof — LOFTEE's call on the row's transcript_id — equals this: HC high-confidence or LC low-confidence. A row with lof null or OS matches neither. consequence_class lof reads the consequence term instead, so it keeps LoF terms LOFTEE did not call. Omit to keep every call. | |
| reference_genome | No | Reference build. Derived from dataset when omitted: GRCh38 for gnomad_r4, gnomad_r3, and their subsets; GRCh37 for gnomad_r2_1, its subsets, and exac. If supplied it must match the dataset, or the call is rejected. Keep aligned with ensembl coordinates. | |
| consequence_class | No | Keep only variants in this gnomAD consequence category, read from each row's consequence: lof (pLoF) is transcript_ablation, splice_acceptor_variant, splice_donor_variant, stop_gained, frameshift_variant; missense (missense / inframe indel) is missense_variant, stop_lost, start_lost, inframe_insertion, inframe_deletion; synonymous is synonymous_variant; other is every other term and a null consequence. Omit to return all classes. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| total | No | Total matching variants across every page, not just this one — counted after pass_only drops QC-failed rows when it is set, so it then excludes the qc_filtered rows. | |
| notice | No | Guidance when no variants matched, when matching variants failed gnomAD QC (the qc_filtered count, and what pass_only dropped), when max_faf is set (how many variants in total it kept untested for a null faf95_max, or that the dataset carries no FAF on its rows), when limit was clamped to its cap, the next offset when no staged table holds the rest, an offset past the end, and — when a table was staged — its name with the next steps: gnomad_dataframe_describe, then gnomad_dataframe_query. | |
| target | No | The resolved target the rows describe: gene symbol or Ensembl gene ID, transcript ID, or region, as normalized for the lookup. | |
| dataset | No | Effective gnomAD dataset. | |
| filters | No | The row filters this call applied, each null when not set. offset, limit, canvas_id, and annotations are not filters. | |
| preview | No | This page: up to limit matching variants from offset, in genomic order — the immediate answer. | |
| spilled | No | True when the matching variants exceeded the inline budget at offset 0, so this call staged every one of them in table_name; the page holds at most limit of them either way. | |
| canvas_id | No | 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 page started past offset 0. | |
| truncated | No | True when matching variants remain past this page; continue with next_offset. | |
| table_name | No | 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, as on every page past offset 0. | |
| next_offset | No | offset for the next page; null when this page reaches the last matching variant. | |
| qc_filtered | No | Matching variants that failed gnomAD QC in every callset carrying them (qc_status filtered), counted over every match — not just this page — before pass_only drops them. | |
| target_kind | No | Which target type was queried. | |
| reference_genome | No | Effective reference build. |