gnomad-genetics-mcp-server

gnomad-genetics-mcp-server: get gene constraint

gnomad_get_gene_constraint

Read-onlyIdempotent

Fetch gnomAD loss-of-function constraint for a gene — pLI (probability of LoF intolerance; >0.9 intolerant), LOEUF (oe_lof_upper, the headline metric) plus its lower bound, observed/expected ratios for LoF, missense, and synonymous variation, and the three Z-scores. This is the orthogonal axis to allele frequency: a loss-of-function variant matters far more in a gene intolerant to being broken. Accepts an HGNC symbol (PCSK9) or an Ensembl gene ID (ENSG00000169174). constraint_release names the release the metrics come from: gnomAD v4.1.2 for gnomad_r4 and gnomad_r3 (gnomAD publishes no v3 constraint), gnomAD v2.1.1 for gnomad_r2_1, and ExAC r0.3 for exac. gnomAD recommends LOEUF < 0.45 to call a gene LoF-intolerant on v4.1.2 and LOEUF < 0.35 on v2.1.1. ExAC r0.3 publishes only pLI, the Z-scores, and observed/expected counts, so on exac the ratios and LOEUF are null, constraint_flags is empty, and pLI is the intolerance measure. Many genes have null constraint (sparse upstream) — null fields are reported as such, never fabricated. Echoes the effective dataset and reference build. Data source: gnomAD (Broad Institute) — https://gnomad.broadinstitute.org/

Input Schema

TableJSON Schema

Name	Required	Description
`gene`	Yes	Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene.
`dataset`	No	gnomAD dataset: gnomad_r4 (GRCh38, default), gnomad_r3 (GRCh38), gnomad_r2_1 (GRCh37), exac (GRCh37). Echoed in output.
`reference_genome`	No	Reference 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.

Output Schema

TableJSON Schema

Name	Required	Description
`pli`	No	pLI — probability of LoF intolerance; >0.9 intolerant. Null when unavailable.
`error`	No	Present when the call failed. Absent on success.
`lof_z`	No	LoF constraint Z-score. Null when unavailable.
`mis_z`	No	Missense constraint Z-score. Null when unavailable.
`syn_z`	No	Synonymous constraint Z-score. Null when unavailable.
`oe_lof`	No	Non-negative observed/expected LoF ratio. Null when unavailable.
`oe_mis`	No	Observed/expected missense ratio. Null when unavailable.
`oe_syn`	No	Observed/expected synonymous ratio. Null when unavailable.
`symbol`	No	HGNC gene symbol.
`dataset`	No	Effective gnomAD dataset.
`exp_lof`	No	Non-negative expected LoF variant count. Null when unavailable.
`exp_mis`	No	Non-negative expected missense count. Null when unavailable.
`exp_syn`	No	Non-negative expected synonymous count. Null when unavailable.
`gene_id`	No	Ensembl gene ID resolved for the gene.
`obs_lof`	No	Non-negative observed LoF variant count. Null when unavailable.
`obs_mis`	No	Non-negative observed missense count. Null when unavailable.
`obs_syn`	No	Non-negative observed synonymous count. Null when unavailable.
`oe_lof_lower`	No	LOEUF confidence-interval lower bound. Null when unavailable.
`oe_lof_upper`	No	LOEUF (oe_lof_upper) — the headline intolerance metric; gnomAD recommends < 0.45 on v4.1.2 and < 0.35 on v2.1.1 to call a gene LoF-intolerant. Null when unavailable, and always null on exac.
`constraint_flags`	No	Caveat flags gnomAD attaches to the gene’s constraint (e.g. no_exp_lof, mis_too_many, syn_outlier); empty when none, and always empty on exac, where ExAC publishes no flags.
`reference_genome`	No	Effective reference build.
`constraint_release`	No	Constraint release the metrics come from: gnomAD v4.1.2 for gnomad_r4 and gnomad_r3 (gnomAD publishes no v3 constraint, so gnomad_r3 serves the GRCh38 table), gnomAD v2.1.1 for gnomad_r2_1, ExAC r0.3 for exac.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedSep 30, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "gene_id",
-      "symbol",
-      "dataset",
-      "reference_genome",
-      "pli",
-      "oe_lof",
-      "oe_lof_lower",
-      "oe_lof_upper",
-      "oe_mis",
-      "oe_syn",
-      "lof_z",
-      "mis_z",
-      "syn_z",
-      "obs_lof",
-      "exp_lof",
-      "obs_mis",
-      "exp_mis",
-      "obs_syn",
-      "exp_syn",
-      "constraint_flags"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "gene_id",
+      "symbol",
+      "dataset",
+      "reference_genome",
+      "constraint_release",
+      "pli",
+      "oe_lof",
+      "oe_lof_lower",
+      "oe_lof_upper",
+      "oe_mis",
+      "oe_syn",
+      "lof_z",
+      "mis_z",
+      "syn_z",
+      "obs_lof",
+      "exp_lof",
+      "obs_mis",
+      "exp_mis",
+      "obs_syn",
+      "exp_syn",
+      "constraint_flags"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / constraint_flags / description

Previous value: -"Constraint caveat flags (e.g. beta/experimental notes for v4)."New value: +"Caveat flags gnomAD attaches to the gene’s constraint (e.g. no_exp_lof, mis_too_many, syn_outlier); empty when none, and always empty on exac, where ExAC publishes no flags."

addedOutput schema / properties / constraint_release

Added value: +{
+  "description": "Constraint release the metrics come from: gnomAD v4.1.2 for gnomad_r4 and gnomad_r3 (gnomAD publishes no v3 constraint, so gnomad_r3 serves the GRCh38 table), gnomAD v2.1.1 for gnomad_r2_1, ExAC r0.3 for exac.",
+  "type": "string"
+}

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `gene_not_found`: No gene matched the symbol or Ensembl ID in this build. `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: `gene_not_found`: No gene matched the symbol or Ensembl ID in this build. `incoherent_build`: reference_genome was supplied but does not match the dataset. `invalid_constraint_data`: gnomAD returned constraint metrics outside their valid ranges, such as a pLI above 1. `graphql_error`: gnomAD rejected the constraint 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: -[
-  "gene_not_found",
-  "incoherent_build"
-]New value: +[
+  "gene_not_found",
+  "incoherent_build",
+  "invalid_constraint_data",
+  "graphql_error",
+  "upstream_unavailable",
+  "upstream_timeout",
+  "upstream_access",
+  "invalid_upstream_response"
+]

changedOutput schema / properties / oe_lof_upper / description

Previous value: -"LOEUF (oe_lof_upper) — the headline intolerance metric. Null when unavailable."New value: +"LOEUF (oe_lof_upper) — the headline intolerance metric; gnomAD recommends < 0.45 on v4.1.2 and < 0.35 on v2.1.1 to call a gene LoF-intolerant. Null when unavailable, and always null on exac."

Changed6 schema fields changedSep 20, 2026

removedOutput schema / properties / lof_z / anyOf

Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / lof_z / type
```
Added value: +[
+  "number",
+  "null"
+]
```

removedOutput schema / properties / mis_z / anyOf

Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / mis_z / type
```
Added value: +[
+  "number",
+  "null"
+]
```

removedOutput schema / properties / syn_z / anyOf

Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / syn_z / type
```
Added value: +[
+  "number",
+  "null"
+]
```

Changed19 schema fields changedAug 31, 2026

changedOutput schema / properties / exp_lof / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / exp_lof / description

Previous value: -"Expected LoF variant count. Null when unavailable."New value: +"Non-negative expected LoF variant count. Null when unavailable."

changedOutput schema / properties / exp_mis / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / exp_mis / description

Previous value: -"Expected missense count. Null when unavailable."New value: +"Non-negative expected missense count. Null when unavailable."

changedOutput schema / properties / exp_syn / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / exp_syn / description

Previous value: -"Expected synonymous count. Null when unavailable."New value: +"Non-negative expected synonymous count. Null when unavailable."

changedOutput schema / properties / obs_lof / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / obs_lof / description

Previous value: -"Observed LoF variant count. Null when unavailable."New value: +"Non-negative observed LoF variant count. Null when unavailable."

changedOutput schema / properties / obs_mis / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / obs_mis / description

Previous value: -"Observed missense count. Null when unavailable."New value: +"Non-negative observed missense count. Null when unavailable."

changedOutput schema / properties / obs_syn / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / obs_syn / description

Previous value: -"Observed synonymous count. Null when unavailable."New value: +"Non-negative observed synonymous count. Null when unavailable."

changedOutput schema / properties / oe_lof / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / oe_lof / description

Previous value: -"Observed/expected LoF ratio. Null when unavailable."New value: +"Non-negative observed/expected LoF ratio. Null when unavailable."

changedOutput schema / properties / oe_lof_lower / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / oe_lof_upper / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / oe_mis / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / oe_syn / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / pli / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "maximum": 1,
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "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?

With annotations covering safety (readOnly, idempotent, openWorld), the description adds substantial behavioral context: null fields are reported as null and never fabricated, ExAC r0.3 returns null LOEUF/ratios with empty constraint_flags, and reference_genome is rejected if it mismatches the dataset. These are caveats an agent cannot infer from annotations or schema.

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 headline metric (LOEUF) and its interpretation threshold, followed by edge-case caveats in descending priority. It is dense and long-ish, but nearly every clause (thresholds, release mapping, null handling) is actionable, so little is wasted.

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?

An output schema exists, so return structure need not be described, and the description still supplies the interpretive context (LOEUF < 0.45 on v4.1.2, < 0.35 on v2.1.1) an agent needs to use the result correctly. Nothing required to call or interpret the tool is missing.

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% and the schema already documents gene, dataset, and reference_genome, so the baseline is 3. The description earns above baseline by mapping each dataset to its actual constraint release (v4.1.2, v2.1.1, ExAC r0.3) and by noting that reference build is derived from dataset and echoed in output — meaning beyond what the schema's enum text conveys.

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 (fetch) and resource (gnomAD loss-of-function constraint for a gene) and enumerates exactly which metrics are returned (pLI, LOEUF, observed/expected ratios, three Z-scores). It also positions itself against siblings by calling constraint 'the orthogonal axis to allele frequency', so an agent can distinguish it from get_variant or list_gene_variants.

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?

It tells the agent what to do with the result — interpret variant impact via gene intolerance — and specifies accepted identifiers and dataset/release alignment rules. It does not, however, explicitly name a sibling or state when to prefer another tool, so it stops just short of full routing guidance.

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.