Clarity Clinical

Query clinical variant data from ClinVar and gnomAD via Clarity Protocol. Use when the user asks about ClinVar classification, clinical significance, pathoge...

Security Scan

The skill's code, instructions, and requirements are consistent with its stated purpose of querying ClinVar/gnomAD via Clarity Protocol; it only needs optional CLARITY_API_KEY and internet access and does not request unrelated credentials or system access.

Purpose & Capability

Name/description (clinical variant queries) align with the included client and query scripts. The API_BASE, endpoints, and declared rate limits match the stated functionality; no unrelated services or credentials are requested.

Instruction Scope

SKILL.md and scripts only direct the agent to call the Clarity Protocol API and format results. The instructions do not read unrelated system files, environment variables beyond optional CLARITY_API_KEY, or send data to unexpected endpoints.

Install Mechanism

There is no install spec (instruction-only + included scripts), which minimizes installer risk. The scripts import the Python requests library but the skill does not declare dependencies — user environment must have Python and requests available. This is an operational note rather than a security incoherence.

Credentials

Only an optional CLARITY_API_KEY is referenced (used to raise rate limits). No other secrets, keys, or unrelated environment variables are required or accessed.

Persistence & Privilege

The skill is not always-enabled, does not request persistent system modifications, and does not attempt to modify other skills or global agent settings. It performs outbound API calls only when invoked.

Assessment

This skill appears to do what it claims: call clarityprotocol.io to retrieve ClinVar/gnomAD-derived annotations. Before installing, confirm you are comfortable with the agent making outbound requests to https://clarityprotocol.io. If you plan to use an API key, store CLARITY_API_KEY securely; the key is only sent as an X-API-Key header to the Clarity Protocol domain. Ensure your environment has Python and the requests package available. If you will query sensitive patient data or PHI, be mindful that any variant identifiers you submit will go to the third-party API — avoid sending protected health information unless your usage complies with your policies and local regulations.

Clarity Clinical Skill

Access clinical variant annotations from ClinVar and population frequency data from gnomAD through Clarity Protocol's integrated database.

Quick Start

List all clinical variants:

python scripts/query_clinical.py

Filter by gene symbol:

python scripts/query_clinical.py --gene-symbol MAPT

Get details for a specific variant:

python scripts/query_clinical.py --gene MAPT --variant NM_005910.6:c.926C>T

Get variant details in readable format:

python scripts/query_clinical.py --gene MAPT --variant NM_005910.6:c.926C>T --format summary

Clinical Variant Fields

Each clinical variant includes:

• gene_symbol: HGNC gene symbol
• variant_notation: Full HGVS notation (transcript-based)
• clinvar_significance: Clinical significance classification (e.g., "Pathogenic", "Benign")
• clinvar_review_status: Review status stars (e.g., "criteria provided, multiple submitters")
• clinvar_last_evaluated: Date of last ClinVar evaluation
• gnomad_af: Allele frequency in gnomAD (population prevalence)
• gnomad_ac: Allele count in gnomAD
• gnomad_an: Total allele number in gnomAD
• fetched_at: When this data was retrieved from ClinVar/gnomAD

ClinVar Significance Values

• Pathogenic: Strong evidence for disease causation
• Likely pathogenic: Moderate evidence for disease causation
• Benign: Strong evidence of no disease causation
• Likely benign: Moderate evidence of no disease causation
• Uncertain significance: Insufficient evidence
• Conflicting interpretations: Disagreement among submitters

gnomAD Frequency Interpretation

• af < 0.0001: Very rare (< 0.01%)
• af < 0.001: Rare (< 0.1%)
• af < 0.01: Uncommon (< 1%)
• af >= 0.01: Common (>= 1%)

Rate Limits

• Anonymous (no API key): 10 requests/minute
• With API key: 100 requests/minute

To use an API key, set the CLARITY_API_KEY environment variable:

export CLARITY_API_KEY=your_key_here
python scripts/query_clinical.py --gene-symbol MAPT

Get your API key at https://clarityprotocol.io

Error Handling

404 Not Found: The specified gene/variant combination does not exist in the clinical database.

429 Rate Limit: You've exceeded the rate limit. The script will display how long to wait.

500 Server Error: The API server encountered an error. Try again later.

Timeout: The request took longer than 30 seconds.

Pagination

Clinical variant lists are paginated. The API returns a next_cursor field if more results are available.

Use Cases

• Check if a variant is pathogenic in ClinVar
• Get population frequency data for a mutation
• Compare clinical significance across variants in a gene
• Assess variant review status quality
• Filter common vs. rare variants using gnomAD