gnomad-genetics-mcp-server

Fetch the full gnomAD population record for one or more variants — allele count/number/frequency overall and broken down per genetic-ancestry group, homozygote and hemizygote counts, quality flags, transcript consequence, in-silico predictor scores, and joined ClinVar clinical significance. The "how common, is it benign" answer in one call. Accepts a batch of up to 25 IDs (chrom-pos-ref-alt or rsID) with per-item partial success: a malformed or absent ID lands in failed[] — with its reason and a recovery hint — without failing the others. An empty found[] for a well-formed ID means the variant is not in the chosen dataset — pair with gnomad_get_coverage to confirm the position is callable before concluding true absence. Data source: gnomAD (Broad Institute) — https://gnomad.broadinstitute.org/

{
  "type": "object",
  "properties": {
    "variants": {
      "minItems": 1,
      "maxItems": 25,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "description": "Variant ID — chrom-pos-ref-alt (1-based, e.g. 1-55051215-G-GA) on chromosome 1–22, X, or Y with an optional chr prefix, or an rsID (rs11591147). Mitochondrial IDs (M, MT, chrM) are not served. Obtain a variantId from ensembl_predict_variant or a VCF. Malformed IDs are reported per-item in failed[], not rejected wholesale."
      },
      "description": "1–25 variant IDs (chrom-pos-ref-alt or rsID) to look up in one batched call."
    },
    "dataset": {
      "description": "gnomAD dataset: gnomad_r4 (GRCh38, default), gnomad_r3 (GRCh38), gnomad_r2_1 (GRCh37), exac (GRCh37). Echoed in output.",
      "type": "string",
      "enum": [
        "gnomad_r4",
        "gnomad_r3",
        "gnomad_r2_1",
        "exac"
      ]
    },
    "reference_genome": {
      "description": "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.",
      "type": "string",
      "enum": [
        "GRCh38",
        "GRCh37"
      ]
    }
  },
  "required": [
    "variants"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "variant_id": {
            "type": "string",
            "description": "Resolved chrom-pos-ref-alt variant ID."
          },
          "rsids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "dbSNP rsIDs for this variant."
          },
          "reference_genome": {
            "type": "string",
            "description": "Reference build the record is on (GRCh38 or GRCh37)."
          },
          "dataset": {
            "type": "string",
            "description": "Effective gnomAD dataset."
          },
          "ac": {
            "type": "number",
            "description": "Overall allele count across carried callset(s)."
          },
          "an": {
            "type": "number",
            "description": "Overall allele number across carried callset(s)."
          },
          "af": {
            "description": "Overall allele frequency; null when an is 0.",
            "type": [
              "number",
              "null"
            ]
          },
          "homozygote_count": {
            "type": "number",
            "description": "Overall homozygote count."
          },
          "hemizygote_count": {
            "description": "Overall hemizygote count (X/Y only); null otherwise.",
            "type": [
              "number",
              "null"
            ]
          },
          "populations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Genetic-ancestry group: afr, amr, asj, eas, fin, mid, nfe, sas, remaining, or ami (genomes only)."
                },
                "source": {
                  "type": "string",
                  "enum": [
                    "exome",
                    "genome"
                  ],
                  "description": "Which gnomAD callset this group vector came from."
                },
                "ac": {
                  "type": "number",
                  "description": "Allele count in this group."
                },
                "an": {
                  "type": "number",
                  "description": "Allele number (called chromosomes) in this group."
                },
                "af": {
                  "description": "Allele frequency (ac/an); null when an is 0.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "homozygote_count": {
                  "type": "number",
                  "description": "Homozygote count in this group."
                },
                "hemizygote_count": {
                  "description": "Hemizygote count (X/Y only); null otherwise.",
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "id",
                "source",
                "ac",
                "an",
                "af",
                "homozygote_count",
                "hemizygote_count"
              ],
              "additionalProperties": false,
              "description": "One genetic-ancestry group AC/AN/AF vector."
            },
            "description": "Per-ancestry frequency vector — never collapsed to a single global AF."
          },
          "source": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "exome",
                "genome"
              ]
            },
            "description": "Which gnomAD callset(s) carry this variant."
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Quality flags (e.g. lcr, segdup, lc_lof)."
          },
          "consequence": {
            "description": "Worst/transcript VEP consequence term; null when none.",
            "type": [
              "string",
              "null"
            ]
          },
          "transcript_id": {
            "description": "Transcript the consequence is on; null when none.",
            "type": [
              "string",
              "null"
            ]
          },
          "gene_symbol": {
            "description": "Gene symbol for the reported consequence; null when none.",
            "type": [
              "string",
              "null"
            ]
          },
          "in_silico": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Predictor name. Ids vary by dataset — gnomad_r4: cadd, revel_max, spliceai_ds_max, pangolin_largest_ds, phylop, sift_max, polyphen_max; gnomad_r3: cadd, revel, splice_ai, primate_ai; gnomad_r2_1 and exac carry none."
                },
                "value": {
                  "description": "Predictor score; null when not provided for this variant, or when gnomAD gave text with no number (the text is then in annotation).",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "annotation": {
                  "description": "Text gnomAD attaches to the score — on gnomad_r3, the SpliceAI event (e.g. acceptor_gain, no_consequence). Holds the raw text when value is null for lack of a number; null for a plain score.",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "id",
                "value",
                "annotation"
              ],
              "additionalProperties": false,
              "description": "One in-silico predictor score."
            },
            "description": "In-silico predictor scores present for this variant."
          },
          "clinvar": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "clinical_significance": {
                    "description": "ClinVar clinical significance (e.g. Pathogenic, Likely benign); null when no entry.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "review_status": {
                    "description": "ClinVar review status text.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "gold_stars": {
                    "description": "ClinVar 0–4 star review rating.",
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "clinvar_variation_id": {
                    "description": "ClinVar VariationID.",
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "clinical_significance",
                  "review_status",
                  "gold_stars",
                  "clinvar_variation_id"
                ],
                "additionalProperties": false,
                "description": "Joined ClinVar significance from gnomAD. Null when the variant has no ClinVar entry."
              },
              {
                "type": "null"
              }
            ],
            "description": "ClinVar annotation, or null when no entry exists."
          },
          "clinvar_unavailable": {
            "type": "boolean",
            "description": "True when the optional ClinVar resolver failed; false when no entry exists."
          }
        },
        "required": [
          "variant_id",
          "rsids",
          "reference_genome",
          "dataset",
          "ac",
          "an",
          "af",
          "homozygote_count",
          "hemizygote_count",
          "populations",
          "source",
          "flags",
          "consequence",
          "transcript_id",
          "gene_symbol",
          "in_silico",
          "clinvar",
          "clinvar_unavailable"
        ],
        "additionalProperties": false,
        "description": "Full population record for one variant."
      },
      "description": "Variants resolved to a population record."
    },
    "failed": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "variant": {
            "type": "string",
            "description": "The input ID that failed to resolve."
          },
          "error": {
            "type": "string",
            "description": "What went wrong for this ID."
          },
          "reason": {
            "type": "string",
            "enum": [
              "invalid_variant_id",
              "variant_not_found",
              "mitochondrial_unsupported",
              "ambiguous_rsid",
              "graphql_error",
              "upstream_build_mismatch",
              "upstream_unavailable",
              "upstream_timeout",
              "upstream_access",
              "invalid_upstream_response"
            ],
            "description": "Why this ID failed — a reason declared in this tool's error contract. Branch on it rather than on the message."
          },
          "recovery": {
            "type": "string",
            "description": "The next step for this ID — the recovery hint declared for its reason."
          },
          "candidates": {
            "description": "Concrete variant IDs to retry when an rsID is ambiguous.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "variant",
          "error",
          "reason",
          "recovery"
        ],
        "additionalProperties": false,
        "description": "One failed input ID, why it failed, and what to do next."
      },
      "description": "Per-item failures, in input order: malformed IDs, variants absent from the dataset, or upstream errors — each with its reason and recovery hint."
    },
    "dataset": {
      "type": "string",
      "description": "Effective gnomAD dataset used for the batch."
    },
    "reference_genome": {
      "type": "string",
      "description": "Effective reference build used for the batch."
    },
    "notice": {
      "description": "Non-fatal notice when optional ClinVar annotation was unavailable.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `incoherent_build`: reference_genome was supplied but does not match the dataset. `invalid_variant_id`: A variant ID is outside the chrom-pos-ref-alt or rsID grammar; reported per item in failed[]. `variant_not_found`: A well-formed ID is absent from the requested dataset; reported per item in failed[]. `mitochondrial_unsupported`: A variant ID names the mitochondrial chromosome (M, MT, or chrM); reported per item in failed[]. `ambiguous_rsid`: An rsID maps to more than one variant in the dataset; reported per item in failed[]. `graphql_error`: gnomAD rejected the lookup for one ID with a GraphQL error; reported per item in failed[]. `upstream_build_mismatch`: gnomAD answered one ID with a variant on a different reference build; reported per item in failed[]. `upstream_unavailable`: gnomAD stayed unavailable or throttled through every retry for one ID; reported per item in failed[]. `upstream_timeout`: Every attempt to reach gnomAD for one ID timed out; reported per item in failed[]. `upstream_access`: gnomAD refused the request for one ID (access denied); reported per item in failed[]. `invalid_upstream_response`: gnomAD kept answering one ID with a response that failed validation; reported per item in failed[]. Other values are possible when a failure originates below the handler.",
              "examples": [
                "incoherent_build",
                "invalid_variant_id",
                "variant_not_found",
                "mitochondrial_unsupported",
                "ambiguous_rsid",
                "graphql_error",
                "upstream_build_mismatch",
                "upstream_unavailable",
                "upstream_timeout",
                "upstream_access",
                "invalid_upstream_response"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "found",
        "failed",
        "dataset",
        "reference_genome"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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/

{
  "type": "object",
  "properties": {
    "gene": {
      "type": "string",
      "minLength": 2,
      "description": "Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene."
    },
    "dataset": {
      "description": "gnomAD dataset: gnomad_r4 (GRCh38, default), gnomad_r3 (GRCh38), gnomad_r2_1 (GRCh37), exac (GRCh37). Echoed in output.",
      "type": "string",
      "enum": [
        "gnomad_r4",
        "gnomad_r3",
        "gnomad_r2_1",
        "exac"
      ]
    },
    "reference_genome": {
      "description": "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.",
      "type": "string",
      "enum": [
        "GRCh38",
        "GRCh37"
      ]
    }
  },
  "required": [
    "gene"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "gene_id": {
      "type": "string",
      "description": "Ensembl gene ID resolved for the gene."
    },
    "symbol": {
      "type": "string",
      "description": "HGNC gene symbol."
    },
    "dataset": {
      "type": "string",
      "description": "Effective gnomAD dataset."
    },
    "reference_genome": {
      "type": "string",
      "description": "Effective reference build."
    },
    "constraint_release": {
      "type": "string",
      "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."
    },
    "pli": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "pLI — probability of LoF intolerance; >0.9 intolerant. Null when unavailable."
    },
    "oe_lof": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Non-negative observed/expected LoF ratio. Null when unavailable."
    },
    "oe_lof_lower": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "LOEUF confidence-interval lower bound. Null when unavailable."
    },
    "oe_lof_upper": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "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."
    },
    "oe_mis": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Observed/expected missense ratio. Null when unavailable."
    },
    "oe_syn": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Observed/expected synonymous ratio. Null when unavailable."
    },
    "lof_z": {
      "description": "LoF constraint Z-score. Null when unavailable.",
      "type": [
        "number",
        "null"
      ]
    },
    "mis_z": {
      "description": "Missense constraint Z-score. Null when unavailable.",
      "type": [
        "number",
        "null"
      ]
    },
    "syn_z": {
      "description": "Synonymous constraint Z-score. Null when unavailable.",
      "type": [
        "number",
        "null"
      ]
    },
    "obs_lof": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Non-negative observed LoF variant count. Null when unavailable."
    },
    "exp_lof": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Non-negative expected LoF variant count. Null when unavailable."
    },
    "obs_mis": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Non-negative observed missense count. Null when unavailable."
    },
    "exp_mis": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Non-negative expected missense count. Null when unavailable."
    },
    "obs_syn": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Non-negative observed synonymous count. Null when unavailable."
    },
    "exp_syn": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Non-negative expected synonymous count. Null when unavailable."
    },
    "constraint_flags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "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."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "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.",
              "examples": [
                "gene_not_found",
                "incoherent_build",
                "invalid_constraint_data",
                "graphql_error",
                "upstream_unavailable",
                "upstream_timeout",
                "upstream_access",
                "invalid_upstream_response"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "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"
      ]
    }
  ]
}

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/

{
  "type": "object",
  "properties": {
    "gene": {
      "description": "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.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 2,
          "description": "Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene."
        },
        {
          "type": "string",
          "maxLength": 0,
          "description": "Blank — the gene is treated as omitted."
        }
      ]
    },
    "transcript_id": {
      "description": "Ensembl transcript ID (e.g. ENST00000302118). Mutually exclusive with gene and region; blank means omitted.",
      "type": "string"
    },
    "region": {
      "description": "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.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^(?:chr)?[0-9A-Z]+-\\d+-\\d+$",
          "description": "Genomic region chrom-start-stop (1-based inclusive, e.g. 13-32315474-32400266) on chromosome 1–22, X, or Y, optional chr prefix."
        }
      ]
    },
    "consequence_class": {
      "description": "Keep only variants in this consequence class. Omit to return all classes.",
      "type": "string",
      "enum": [
        "lof",
        "missense",
        "synonymous",
        "other"
      ]
    },
    "max_af": {
      "description": "Keep only variants with allele frequency ≤ this value (0–1). Variants with null AF are always kept.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "canvas_id": {
      "description": "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.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    },
    "dataset": {
      "description": "gnomAD dataset: gnomad_r4 (GRCh38, default), gnomad_r3 (GRCh38), gnomad_r2_1 (GRCh37), exac (GRCh37). Echoed in output.",
      "type": "string",
      "enum": [
        "gnomad_r4",
        "gnomad_r3",
        "gnomad_r2_1",
        "exac"
      ]
    },
    "reference_genome": {
      "description": "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.",
      "type": "string",
      "enum": [
        "GRCh38",
        "GRCh37"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "preview": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "variant_id": {
            "type": "string",
            "description": "chrom-pos-ref-alt variant ID."
          },
          "af": {
            "description": "Allele frequency computed from joint allele counts; null when uncomputable.",
            "type": [
              "number",
              "null"
            ]
          },
          "ac": {
            "type": "number",
            "description": "Allele count (joint across carried callsets)."
          },
          "an": {
            "type": "number",
            "description": "Allele number (joint sum across carried callsets)."
          },
          "consequence": {
            "description": "VEP consequence term; null when none.",
            "type": [
              "string",
              "null"
            ]
          },
          "consequence_class": {
            "type": "string",
            "enum": [
              "lof",
              "missense",
              "synonymous",
              "other"
            ],
            "description": "Bucketed consequence class."
          },
          "homozygote_count": {
            "type": "number",
            "description": "Homozygote count (joint across callsets)."
          },
          "source": {
            "type": "string",
            "description": "Carried callset(s), pipe-joined (e.g. exome|genome)."
          },
          "flags": {
            "type": "string",
            "description": "Quality flags, pipe-joined (empty when none)."
          }
        },
        "required": [
          "variant_id",
          "af",
          "ac",
          "an",
          "consequence",
          "consequence_class",
          "homozygote_count",
          "source",
          "flags"
        ],
        "additionalProperties": false,
        "description": "One gene-variant row — also the canvas table column set."
      },
      "description": "Inline preview rows — the immediate answer; every matching variant unless spilled."
    },
    "canvas_id": {
      "type": "string",
      "description": "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."
    },
    "table_name": {
      "type": "string",
      "description": "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."
    },
    "spilled": {
      "type": "boolean",
      "description": "True when the result exceeded the inline preview budget, so the preview holds only the first rows and table_name holds them all."
    },
    "total": {
      "type": "number",
      "description": "Total matching variants, including any beyond the preview."
    },
    "dataset": {
      "type": "string",
      "description": "Effective gnomAD dataset."
    },
    "reference_genome": {
      "type": "string",
      "description": "Effective reference build."
    },
    "notice": {
      "description": "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.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "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.",
              "examples": [
                "invalid_target",
                "incoherent_build",
                "invalid_region",
                "region_too_large",
                "mitochondrial_unsupported",
                "graphql_error",
                "upstream_unavailable",
                "upstream_timeout",
                "upstream_access",
                "invalid_upstream_response"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "preview",
        "canvas_id",
        "table_name",
        "spilled",
        "total",
        "dataset",
        "reference_genome"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch gnomAD sequencing-coverage summary across a gene, transcript, or region — mean and median read depth, plus the mean fraction of samples covered at each depth threshold (1× through 100×), separated by exome and genome track. Use this to disambiguate a true absent variant from an uncallable position: a variant missing from a well-covered region is informative, while one missing from a poorly-covered region is not. Supply exactly one of gene, transcript_id, or region. The optional coverage_source narrows to one track; by default both available tracks are returned. Echoes the effective dataset and build. Data source: gnomAD (Broad Institute) — https://gnomad.broadinstitute.org/

{
  "type": "object",
  "properties": {
    "gene": {
      "description": "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.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 2,
          "description": "Gene — HGNC symbol (e.g. PCSK9) or Ensembl gene ID (e.g. ENSG00000169174). Obtain a stable ID from ensembl_lookup_gene."
        },
        {
          "type": "string",
          "maxLength": 0,
          "description": "Blank — the gene is treated as omitted."
        }
      ]
    },
    "transcript_id": {
      "description": "Ensembl transcript ID (e.g. ENST00000302118). Mutually exclusive with gene and region; blank means omitted.",
      "type": "string"
    },
    "region": {
      "description": "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) and a span (stop − start) under 2,500,000 bp. Mutually exclusive with gene and transcript_id.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^(?:chr)?[0-9A-Z]+-\\d+-\\d+$",
          "description": "Genomic region chrom-start-stop (1-based inclusive, e.g. 1-55039447-55064852) on chromosome 1–22, X, or Y, optional chr prefix."
        }
      ]
    },
    "coverage_source": {
      "description": "Restrict to one coverage track. Omit to return every available track.",
      "type": "string",
      "enum": [
        "exome",
        "genome"
      ]
    },
    "dataset": {
      "description": "gnomAD dataset: gnomad_r4 (GRCh38, default), gnomad_r3 (GRCh38), gnomad_r2_1 (GRCh37), exac (GRCh37). Echoed in output.",
      "type": "string",
      "enum": [
        "gnomad_r4",
        "gnomad_r3",
        "gnomad_r2_1",
        "exac"
      ]
    },
    "reference_genome": {
      "description": "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.",
      "type": "string",
      "enum": [
        "GRCh38",
        "GRCh37"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "The resolved target (gene symbol/ID, transcript ID, or region) the coverage describes."
    },
    "target_kind": {
      "type": "string",
      "enum": [
        "gene",
        "transcript",
        "region"
      ],
      "description": "Which target type was queried."
    },
    "summaries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "exome",
              "genome"
            ],
            "description": "Which gnomAD coverage track this summary covers."
          },
          "positions": {
            "type": "number",
            "description": "Number of base positions summarized across the target."
          },
          "mean_depth": {
            "description": "Mean read depth averaged across positions; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "median_depth": {
            "description": "Median read depth across positions; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "fraction_over_1": {
            "description": "Mean fraction of samples covered at ≥1×; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "fraction_over_5": {
            "description": "Mean fraction of samples covered at ≥5×; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "fraction_over_10": {
            "description": "Mean fraction of samples covered at ≥10×; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "fraction_over_15": {
            "description": "Mean fraction of samples covered at ≥15×; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "fraction_over_20": {
            "description": "Mean fraction of samples covered at ≥20×; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "fraction_over_25": {
            "description": "Mean fraction of samples covered at ≥25×; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "fraction_over_30": {
            "description": "Mean fraction of samples covered at ≥30×; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "fraction_over_50": {
            "description": "Mean fraction of samples covered at ≥50×; null when no data.",
            "type": [
              "number",
              "null"
            ]
          },
          "fraction_over_100": {
            "description": "Mean fraction of samples covered at ≥100×; null when no data.",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "source",
          "positions",
          "mean_depth",
          "median_depth",
          "fraction_over_1",
          "fraction_over_5",
          "fraction_over_10",
          "fraction_over_15",
          "fraction_over_20",
          "fraction_over_25",
          "fraction_over_30",
          "fraction_over_50",
          "fraction_over_100"
        ],
        "additionalProperties": false,
        "description": "Aggregate coverage for one callset track over the target."
      },
      "description": "Per-track coverage summaries (exome and/or genome)."
    },
    "dataset": {
      "type": "string",
      "description": "Effective gnomAD dataset."
    },
    "reference_genome": {
      "type": "string",
      "description": "Effective reference build."
    },
    "notice": {
      "description": "Guidance when no coverage data is available for the target.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "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, beyond what gnomAD summarizes at once. `mitochondrial_unsupported`: The gene, transcript, or region is on the mitochondrial chromosome (M or MT). `graphql_error`: gnomAD rejected the coverage 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.",
              "examples": [
                "invalid_target",
                "incoherent_build",
                "invalid_region",
                "region_too_large",
                "mitochondrial_unsupported",
                "graphql_error",
                "upstream_unavailable",
                "upstream_timeout",
                "upstream_access",
                "invalid_upstream_response"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "target",
        "target_kind",
        "summaries",
        "dataset",
        "reference_genome"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "gene": {
      "type": "string",
      "minLength": 2,
      "description": "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."
    },
    "clinical_significance": {
      "description": "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.",
      "type": "string"
    },
    "min_review_stars": {
      "description": "Keep only variants with at least this gold-star review rating (0–4).",
      "type": "integer",
      "minimum": 0,
      "maximum": 4
    },
    "offset": {
      "default": 0,
      "description": "Zero-based position of the first ClinVar record in this window. Pass next_offset from the previous call to continue.",
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647
    },
    "limit": {
      "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "canvas_id": {
      "description": "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.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "gene"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "preview": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "clinvar_variation_id": {
            "type": "string",
            "description": "ClinVar VariationID (uid)."
          },
          "accession": {
            "type": "string",
            "description": "ClinVar accession (e.g. VCV004855003)."
          },
          "title": {
            "type": "string",
            "description": "Variant title (HGVS expression)."
          },
          "obj_type": {
            "type": "string",
            "description": "Variant object type (e.g. single nucleotide variant)."
          },
          "clinical_significance": {
            "description": "Germline classification (e.g. Pathogenic); null when none.",
            "type": [
              "string",
              "null"
            ]
          },
          "review_status": {
            "description": "ClinVar review-status text; null when none.",
            "type": [
              "string",
              "null"
            ]
          },
          "gold_stars": {
            "type": "number",
            "description": "0–4 star review rating derived from review status."
          },
          "last_evaluated": {
            "description": "Date the classification was last evaluated; null when unknown.",
            "type": [
              "string",
              "null"
            ]
          },
          "molecular_consequences": {
            "type": "string",
            "description": "Molecular consequences, semicolon-joined."
          },
          "protein_change": {
            "type": "string",
            "description": "Protein change(s), comma-joined as ClinVar reports them."
          },
          "conditions": {
            "type": "string",
            "description": "Associated conditions/traits, semicolon-joined."
          },
          "submission_count": {
            "type": "number",
            "description": "Number of submitted (SCV) records."
          },
          "canonical_spdi": {
            "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"
            ]
          },
          "rsids": {
            "type": "string",
            "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."
          },
          "grch38_variant_id": {
            "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"
            ]
          }
        },
        "required": [
          "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"
        ],
        "additionalProperties": false,
        "description": "One ClinVar variant row — also the canvas table column set."
      },
      "description": "Inline preview rows — the immediate answer; the window's every row unless spilled."
    },
    "canvas_id": {
      "type": "string",
      "description": "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."
    },
    "table_name": {
      "type": "string",
      "description": "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."
    },
    "spilled": {
      "type": "boolean",
      "description": "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."
    },
    "total": {
      "type": "number",
      "description": "Rows in this window that passed the filters, including any beyond the preview."
    },
    "total_found": {
      "type": "number",
      "description": "ClinVar records matching the gene and filter terms across every window, counted before the post-fetch significance and star filters."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when ClinVar records remain past this window; continue with next_offset."
    },
    "next_offset": {
      "description": "offset for the next window; null when this window reaches the end.",
      "type": [
        "number",
        "null"
      ]
    },
    "unavailable_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "VariationIDs in this window that ClinVar returned no summary for, so they have no row; empty when none."
    },
    "notice": {
      "description": "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.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "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.",
              "examples": [
                "upstream_unavailable",
                "upstream_timeout",
                "upstream_access",
                "invalid_upstream_response"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "preview",
        "canvas_id",
        "table_name",
        "spilled",
        "total",
        "total_found",
        "truncated",
        "next_offset",
        "unavailable_ids"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Run a read-only SQL SELECT against a canvas table staged by gnomad_list_gene_variants (table gene_variants) or gnomad_search_clinvar (table clinvar_variants) and return one page of the result. Use the canvas_id and table_name those tools returned to rank by allele frequency, group by consequence class, count loss-of-function variants, or filter the full set the inline preview only sampled. A page holds up to limit rows (default 100, max 500) and ends early once its rows reach 10,000 characters of JSON; continue from next_offset until it is null. Each page re-runs the SQL, so stable paging needs an ORDER BY over a unique key (such as variant_id) and an unchanged table. Paging reaches the server row cap: above it total is null and later rows are reachable only by filtering or aggregating in SQL. SELECT statements only — writes, DDL, and file/HTTP table functions are rejected by the canvas gate. Call gnomad_dataframe_describe first to discover staged table and column names.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by gnomad_list_gene_variants or gnomad_search_clinvar."
    },
    "sql": {
      "type": "string",
      "minLength": 1,
      "description": "Read-only SQL SELECT. Reference tables by the names the staging tool returned (e.g. gene_variants). Add an ORDER BY over a unique key when paging."
    },
    "offset": {
      "default": 0,
      "description": "Row offset of the page to return. Start at 0, then pass next_offset from the previous page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "default": 100,
      "description": "Maximum rows on the page (1–500). A page also ends before its rows pass 10,000 characters of JSON.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "canvas_id",
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": {},
        "description": "One result row — dynamic columns per the SQL projection."
      },
      "description": "This page of result rows, in result order."
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Column names in the result, in order."
    },
    "offset": {
      "type": "number",
      "description": "Row offset this page starts at."
    },
    "returned": {
      "type": "number",
      "description": "Rows on this page — fewer than limit when the 10,000-character row budget or the end of the result ends it early."
    },
    "total": {
      "description": "Rows the SQL produced; null when the result exceeds the server row cap, whose later rows paging cannot reach.",
      "type": [
        "number",
        "null"
      ]
    },
    "truncated": {
      "type": "boolean",
      "description": "True when result rows exist after this page, including rows past the row cap that next_offset cannot reach."
    },
    "next_offset": {
      "description": "offset for the next page; null when no page follows (end of the result, or the row cap reached).",
      "type": [
        "number",
        "null"
      ]
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not enabled on this server instance. `row_too_large`: The first row of the requested page serializes to more than 10,000 characters of JSON, so no page can hold it. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_disabled",
                "row_too_large"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "rows",
        "columns",
        "offset",
        "returned",
        "total",
        "truncated",
        "next_offset"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List the tables staged on a canvas and their columns (name and type) so you can write correct SQL for gnomad_dataframe_query. Use the canvas_id returned by gnomad_list_gene_variants or gnomad_search_clinvar. Returns one entry per table with its row count and column schema.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by a prior staging call (gnomad_list_gene_variants or gnomad_search_clinvar)."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "tables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Table name to reference in SQL."
          },
          "row_count": {
            "type": "number",
            "description": "Number of rows in the table."
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Column name."
                },
                "type": {
                  "type": "string",
                  "description": "Column SQL type (DuckDB type)."
                }
              },
              "required": [
                "name",
                "type"
              ],
              "additionalProperties": false,
              "description": "One column: name and SQL type."
            },
            "description": "Column schema, in order."
          }
        },
        "required": [
          "name",
          "row_count",
          "columns"
        ],
        "additionalProperties": false,
        "description": "One staged table: name, row count, and column schema."
      },
      "description": "Tables staged on the canvas."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not enabled on this server instance. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_disabled"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "tables"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}