gnomad-genetics-mcp-server

gnomad-genetics-mcp-server: search clinvar

gnomad_search_clinvar

Read-onlyIdempotent

Search ClinVar (NCBI E-utilities) for a gene and return its classified variants — clinical significance, review status with a 0–4 star rating, associated conditions, molecular consequences, submission counts, and gnomAD-compatible identifiers (canonical SPDI, rsIDs, GRCh38 variant ID for gnomad_get_variant) — turning the variant-level significance gnomAD joins into a gene-panel curation view. Optionally filter by clinical_significance (e.g. pathogenic) and a minimum star rating. Each call returns one window of up to 500 ClinVar records: total_found is the ClinVar candidate count for the search terms, taken before the significance and star filters narrow each window, and next_offset continues through the rest via offset. A window too large to inline is staged on a DataCanvas table named clinvar_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 or count across the window. A window that fits inline stages no table unless canvas_id is supplied. Keyless, but honors NCBI_API_KEY for a higher rate limit. When the canvas is disabled the tool returns a capped inline preview. Credit: ClinVar, NCBI.

Input Schema

TableJSON Schema

Name	Required	Description
`gene`	Yes	Gene HGNC symbol (e.g. PCSK9). ClinVar indexes HGNC symbols only — Ensembl gene IDs (ENSG…) are not resolved here, unlike the other gnomAD tools; resolve one to its symbol via ensembl_lookup_gene.
`limit`	No	ClinVar records to fetch in this window (1–500). Counted before the clinical_significance and min_review_stars filters, so a window can return fewer rows.
`offset`	No	Zero-based position of the first ClinVar record in this window. Pass next_offset from the previous call to continue.
`canvas_id`	No	Optional canvas ID from a prior call, to reuse the same canvas. When supplied, each search writes its window to the clinvar_variants table on that canvas, replacing (not appending to) the previous one — even when the window fits inline; a window with no rows removes the table. An Ensembl gene ID searches nothing and leaves the canvas as it was. Omit to stage on a fresh canvas only when the window is too large to inline.
`min_review_stars`	No	Keep only variants with at least this gold-star review rating (0–4).
`clinical_significance`	No	Filter by ClinVar clinical significance term (e.g. pathogenic, likely_pathogenic, uncertain significance), matched as whole words; underscores read as spaces. Blank means no filter.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`total`	No	Rows in this window that passed the filters, including any beyond the preview.
`notice`	No	Guidance on completeness (the offset that continues the list, or an offset past the end), no-match results, a capped preview when the canvas is disabled, the staged table with its next steps (gnomad_dataframe_describe, then gnomad_dataframe_query), and which identifier to pass to gnomad_get_variant.
`preview`	No	Inline preview rows — the immediate answer; the window's every row unless spilled.
`spilled`	No	True when this window's rows exceeded the inline preview budget, so the preview holds only the first rows and table_name holds them all.
`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 window fit inline and no canvas_id was supplied, the gene was an Ensembl ID (nothing was searched), or the canvas is disabled.
`truncated`	No	True when ClinVar records remain past this window; continue with next_offset.
`table_name`	No	Canvas table this call staged (clinvar_variants), holding this window's rows — inspect it with gnomad_dataframe_describe, then query it with gnomad_dataframe_query. Empty when this call staged no table.
`next_offset`	No	offset for the next window; null when this window reaches the end.
`total_found`	No	ClinVar records matching the gene and filter terms across every window, counted before the post-fetch significance and star filters.
`unavailable_ids`	No	VariationIDs in this window that ClinVar returned no summary for, so they have no row; empty when none.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 30, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_unavailable`: NCBI E-utilities is unreachable, failing, or rate-limiting after retries. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_unavailable`: NCBI E-utilities is unreachable, failing, or rate-limiting after retries. `upstream_timeout`: Every attempt to reach NCBI E-utilities timed out. `upstream_access`: NCBI E-utilities refused the request (access denied). `invalid_upstream_response`: NCBI E-utilities 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: -[
-  "upstream_unavailable"
-]New value: +[
+  "upstream_unavailable",
+  "upstream_timeout",
+  "upstream_access",
+  "invalid_upstream_response"
+]

Changed21 schema fields changedSep 24, 2026

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 clinvar_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, each search writes its window to the clinvar_variants table on that canvas, replacing (not appending to) the previous one — even when the window fits inline; a window with no rows removes the table. An Ensembl gene ID searches nothing and leaves the canvas as it was. Omit to stage on a fresh canvas only when the window is too large to inline."

changedInput schema / properties / clinical_significance / description

Previous value: -"Filter by ClinVar clinical significance term (e.g. pathogenic, likely_pathogenic, benign)."New value: +"Filter by ClinVar clinical significance term (e.g. pathogenic, likely_pathogenic, uncertain significance), matched as whole words; underscores read as spaces. Blank means no filter."

addedInput schema / properties / limit

Added value: +{
+  "default": 500,
+  "description": "ClinVar records to fetch in this window (1–500). Counted before the clinical_significance and min_review_stars filters, so a window can return fewer rows.",
+  "maximum": 500,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Zero-based position of the first ClinVar record in this window. Pass next_offset from the previous call to continue.",
+  "maximum": 2147483647,
+  "minimum": 0,
+  "type": "integer"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "preview",
-      "canvas_id",
-      "table_name",
-      "spilled",
-      "total"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "preview",
+      "canvas_id",
+      "table_name",
+      "spilled",
+      "total",
+      "total_found",
+      "truncated",
+      "next_offset",
+      "unavailable_ids"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

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 window fit inline and no canvas_id was supplied, the gene was an Ensembl ID (nothing was searched), or the canvas is disabled."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `ncbi_unreachable`: NCBI E-utilities is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_unavailable`: NCBI E-utilities is unreachable, failing, or rate-limiting after retries. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples
```
Previous value: -[
-  "ncbi_unreachable"
-]New value: +[
+  "upstream_unavailable"
+]
```

addedOutput schema / properties / next_offset

Added value: +{
+  "description": "offset for the next window; null when this window reaches the end.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no ClinVar records matched, or when the canvas is disabled and the preview is capped."New value: +"Guidance on completeness (the offset that continues the list, or an offset past the end), no-match results, a capped preview when the canvas is disabled, the staged table with its next steps (gnomad_dataframe_describe, then gnomad_dataframe_query), and which identifier to pass to gnomad_get_variant."

changedOutput schema / properties / preview / description

Previous value: -"Inline preview rows — the immediate answer."New value: +"Inline preview rows — the immediate answer; the window's every row unless spilled."

addedOutput schema / properties / preview / items / properties / canonical_spdi

Added value: +{
+  "description": "Canonical SPDI of the variant (GRCh38, e.g. NC_000001.11:55039973:G:T); null for multi-allele records, CNVs, and records without one.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / preview / items / properties / grch38_variant_id

Added value: +{
+  "description": "gnomAD variant ID (chrom-pos-ref-alt, GRCh38) for gnomad_get_variant with the GRCh38 datasets (gnomad_r4, gnomad_r3). Set for SNVs, MNVs, and delins; null for deletions, insertions, duplications, mitochondrial variants, and multi-allele records.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / preview / items / properties / rsids

Added value: +{
+  "description": "dbSNP rsIDs (e.g. rs11591147), semicolon-joined; empty when none. One rsID can match several gnomAD variants, so prefer grch38_variant_id for gnomad_get_variant.",
+  "type": "string"
+}

changedOutput schema / properties / preview / items / required

Previous value: -[
-  "clinvar_variation_id",
-  "accession",
-  "title",
-  "obj_type",
-  "clinical_significance",
-  "review_status",
-  "gold_stars",
-  "last_evaluated",
-  "molecular_consequences",
-  "protein_change",
-  "conditions",
-  "submission_count"
-]New value: +[
+  "clinvar_variation_id",
+  "accession",
+  "title",
+  "obj_type",
+  "clinical_significance",
+  "review_status",
+  "gold_stars",
+  "last_evaluated",
+  "molecular_consequences",
+  "protein_change",
+  "conditions",
+  "submission_count",
+  "canonical_spdi",
+  "rsids",
+  "grch38_variant_id"
+]

changedOutput schema / properties / spilled / description

Previous value: -"True when the full result was staged on the canvas beyond the preview."New value: +"True when this window's rows 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 (clinvar_variants); empty when not spilled."New value: +"Canvas table this call staged (clinvar_variants), holding this window's rows — 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 ClinVar records (staged row count when spilled, else preview length)."New value: +"Rows in this window that passed the filters, including any beyond the preview."

addedOutput schema / properties / total_found

Added value: +{
+  "description": "ClinVar records matching the gene and filter terms across every window, counted before the post-fetch significance and star filters.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when ClinVar records remain past this window; continue with next_offset.",
+  "type": "boolean"
+}

addedOutput schema / properties / unavailable_ids

Added value: +{
+  "description": "VariationIDs in this window that ClinVar returned no summary for, so they have no row; empty when none.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed7 schema fields changedSep 20, 2026
- addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```
- removedOutput schema / properties / preview / items / properties / clinical_significance / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / preview / items / properties / clinical_significance / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / preview / items / properties / last_evaluated / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / preview / items / properties / last_evaluated / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / preview / items / properties / review_status / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / preview / items / properties / review_status / type
```
Added value: +[
+  "string",
+  "null"
+]
```
First observedAug 22, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover read-only/idempotent/open-world, but the description adds substantial unsurfaced behavior: window-vs-inline staging, canvas table replacement semantics (not appending), table removal on empty windows, the capped preview when canvas is disabled, and the NCBI_API_KEY rate-limit behavior. This is unusually rich disclosure beyond what annotations provide.

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?

Front-loaded with the core action and return shape, and every section carries information. However the description is very long and dense, with pagination, canvas, and credit details packed into single sprawling sentences that could be tightened.

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?

Covers the full agent workflow for a complex, multi-mode tool: filtering, pagination via next_offset, the canvas staging path and its follow-up tools, and graceful degradation. With an output schema present, no further return-value explanation is required.

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 genuine interaction semantics — limit is counted before the significance/star filters so a window can return fewer rows, and filters narrow each window. It reinforces rather than merely restates the schema.

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?

States a specific verb and resource (search ClinVar for a gene) and enumerates exactly what comes back — clinical significance, review stars, conditions, consequences, gnomAD-compatible IDs. It also distinguishes the tool from gnomad_get_variant by naming the latter as the consumer of the returned GRCh38 variant ID.

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 clear operational routing: use gnomad_dataframe_describe then gnomad_dataframe_query when a window is staged, and pass next_offset to continue pagination. It does not explicitly state when to prefer this over the sibling gnomad_list_gene_variants, so the when-not case is left to inference.

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 tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.