Skip to main content
Glama

Variant 3-D Structural Triage

triage_variant_3d
Read-onlyIdempotent

Retrieves source-reported variant evidence and fuses ClinVar pathogenicity with gnomAD gene-constraint signals into a prioritised research report, showing source status and lookup failures.

Instructions

Retrieve source-reported variant evidence for research.

Fuses the upstream signals this tool currently wires into a single prioritised report:

  1. Pathogenicity — ClinVar interpretation + review status. The alphamissense_score / alphamissense_interpretation fields are always null / "Not available" here: AlphaMissense is not wired into this tool. For an AlphaMissense pathogenicity score use generate_variant_clinical_report.

  2. Population genetics — gnomAD LOEUF / pLI gene-constraint scores. Per-variant allele frequencies and the per-ancestry breakdown are not wired into this tool.

  3. Disease associations — a placeholder note pointing at get_target_diseases(); the Open Targets / MONDO traversal is a roadmap (Wave-3) item.

  4. Structural context — a text note pointing at analyze_structural_confidence (resolve the gene to a UniProt accession first); the AlphaFold pLDDT / PAE join into this report is a roadmap (Wave-3) item.

Returns the legacy pathogenicity_tier key as NOT_ASSESSED. Raw verified ClinVar classifications remain source-attributed in the pathogenicity section; they are not converted into a local risk tier. Gene-relative candidates remain explicitly unverified. AlphaMissense is not wired into this particular tool. The report is not a calibrated risk estimate.

status summarises the evidence lookups that were attempted: success when none failed, partial when some failed and some answered, error when all failed and no source evidence was retrieved. data_sources_status gives each source's state, and lookup_summary groups the sources into attempted, answered, failed and skipped with a reason for each failure. A lookup that finds nothing (no_data) is an answer. gnomAD is skipped, and counts neither way, when include_gnomad is false or a transcript's gene could not be verified. A failed lookup is not evidence about the variant: the fields it feeds keep their defaults (clinvar_classification "Not provided", empty population_genetics).

Example: triage_variant_3d(hgvs='BRCA1:c.181T>G')

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "params": "<params>"
    },
    "name": "triage_variant_3d"
  }
}

Input Schema

NameRequiredDescriptionDefault
paramsYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.5.9
    • changedInput schema / properties / params / properties / hgvs / description
      Previous value: -"HGVS variant expression. Supports coding DNA notation e.g. 'BRCA1:c.181T>G', 'TP53:c.817C>T', or genomic e.g. 'chr17:g.43094692G>A'."New value: +"HGVS variant expression, e.g. 'BRCA1:c.181T>G' for candidate discovery or 'NM_007294.4(BRCA1):c.181T>G' for versioned-transcript identity matching. Gene-only coordinates cannot verify allele identity."
  2. Changed3 schema fields changedv1.2.0
    • changedInput schema / properties / params / properties / include_disease_context / description
      Previous value: -"Fetch MONDO disease + Open Targets evidence."New value: +"Add a placeholder disease-context note. The MONDO / Open Targets traversal is a Wave-3 roadmap item (stub)."
    • changedInput schema / properties / params / properties / include_gnomad / description
      Previous value: -"Fetch population allele frequencies from gnomAD."New value: +"Fetch gnomAD gene-CONSTRAINT scores (LOEUF / pLI) only. Per-variant allele frequencies are not wired into this tool."
    • changedInput schema / properties / params / properties / include_structure / description
      Previous value: -"Retrieve AlphaFold structure for context."New value: +"Add a pointer note toward structural-confidence analysis. The full AlphaFold pLDDT/PAE join is a Wave-3 roadmap item (not wired into this tool yet)."
  3. First observedv1.1.8

TDQS

A4.2/5.0
Behavior5/5

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

Goes well beyond the readOnly/openWorld/idempotent annotations: it defines status semantics (success/partial/error), explains data_sources_status and lookup_summary buckets, states that no_data counts as an answer, that gnomAD is 'skipped and counts neither way' when include_gnomad is false or the gene cannot be verified, and that failed lookups leave fields at defaults ('Not provided', empty population_genetics). It also warns the report is not a calibrated risk estimate and that pathogenicity_tier returns NOT_ASSESSED.

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

Conciseness3/5

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

The numbered section structure is scannable and the example call is welcome, but the text is long and repetitive — 'AlphaMissense is not wired into this particular tool' is stated three separate times, and the Wave-3 roadmap disclaimers are restated in both prose and parameters. Several sentences could be collapsed without losing information.

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?

For a tool with nested params, an output schema, and many partially-stubbed data sources, the description covers the essential unknowns: which sections are real vs placeholders, how failures are surfaced, and what defaults failed lookups leave behind. An agent can call this correctly and interpret partial results from the description alone.

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?

Each input is given operational meaning: include_gnomad fetches gene-CONSTRAINT only with no per-variant frequencies, include_structure adds merely a pointer note, include_disease_context adds a placeholder stub, and HGVS format guidance is supplied with an example. The gnomAD skip condition tied to transcript gene verification is additional semantics not obvious from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Retrieve source-reported variant evidence') and frames the output as a 'single prioritised report' fusing ClinVar, gnomAD constraint, disease and structural signals. It also explicitly distinguishes itself from siblings (generate_variant_clinical_report for AlphaMissense, analyze_structural_confidence for structural, get_target_diseases for disease). The only drag is that the actual purpose is partly obscured by long enumerations of what is NOT wired in.

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?

Provides concrete routing for each sub-need: 'For an AlphaMissense pathogenicity score use generate_variant_clinical_report', structural context points to analyze_structural_confidence, disease associations to get_target_diseases(). What is missing is an explicit statement of when to prefer this consolidated report over going straight to those tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.