# Exploit — 369 Score variant-agent source APIs

## Winning Approach

Explore found that this ticket should promote a narrow follow-up set rather than build production connectors now. BioMCP should stay a read-only public service/API proxy with source-labelled provenance/status. Agents keep messy entity cleanup, local document search, alias strategy, and clinical interpretation.

Winning follow-up order:
1. service/input/status capability discovery;
2. public variant normalization proxies, first Mutalyzer + VariantValidator;
3. DOI/conference metadata and article access-status proxies, first Crossref + OpenAlex + Unpaywall/OpenAlex;
4. direct exact-allele gnomAD only after normalized coordinate/build handling exists.

## Full-Scale Results

Ticket-defined full scale is a complete durable spike artifact, not runtime connector implementation. The ticket explicitly marks connector/CLI/MCP behavior changes out of scope and requires no repo code modifications.

Full-scale exploit outputs:
- Candidate sources scored: 21.
- Scoring criteria per source: 9.
- Boundary rows: 6 core rows plus explicit COSMIC rejection in the artifact.
- Follow-up recommendations: 4.
- Classification counts: 12 good BioMCP proxy candidates, 8 possible-but-gated, 1 reject/default-exclude.

Key contract scores:
- Top good candidates: Europe PMC 4.89, Crossref 4.89, VariantValidator 4.78, OpenAlex 4.78, PubMed/PMC/NCBI E-utilities 4.67, PubTator3 4.67.
- Other good candidates: MyVariant.info 4.56, Unpaywall 4.56, Mutalyzer 4.44, MyVariant gnomAD fallback 4.44, CIViC 4.44, LitSense2 4.33.
- Gated/rejected: NCBI Variation/SPDI 4.22, Ensembl VEP REST 4.22, ClinVar 4.22, ClinGen Allele Registry 4.11, gnomAD direct API 3.89, Semantic Scholar 3.89, cBioPortal 3.67, OncoKB 3.44, COSMIC 1.78.

## Regression Control

Regression-control files:
- Explore: `architecture/experiments/369-score-variant-agent-source-apis/results/current_biomcp_baseline.json`
- Exploit: `architecture/experiments/369-score-variant-agent-source-apis/results/exploit_current_biomcp_baseline.json`
- Explore: `architecture/experiments/369-score-variant-agent-source-apis/results/external_api_probes.json`
- Exploit: `architecture/experiments/369-score-variant-agent-source-apis/results/exploit_external_api_probes.json`
- Summary: `architecture/experiments/369-score-variant-agent-source-apis/results/exploit_regression_control_summary.json`

Current BioMCP CLI control: all expected success/failure statuses matched and every probe ran faster than explore. Examples: MYD88 variant search 867.68 → 501.91 ms, article search 3459.50 → 2956.64 ms, PMID 29695787 fulltext 1724.60 → 1650.58 ms.

External API control: response status/shape stayed stable for all probes. Latency-only public-network noise carveouts were recorded for Mutalyzer, VariantValidator, ClinGen Allele Registry, MyVariant, Ensembl VEP, gnomAD, Crossref, OpenAlex ASCO DOI, and Unpaywall. These are waived under the noise carveout because no implementation code changed, outputs/statuses stayed stable, and the full-scale matrix contract remained identical. Largest observed noise case: gnomAD exact allele 183.91 → 3352.53 ms with the same HTTP 200 `Variant not found` semantics.

Matrix control: candidate count, classification counts, boundary rows, and follow-up count all matched explore.

## Validation

Validated with a script that checks:
- 21 candidates and 9 score criteria;
- every candidate has all score fields;
- required classifications are present;
- COSMIC is `reject/default-exclude`;
- 6 boundary rows and 4 follow-up tickets;
- durable planning artifact and architecture copies exist;
- regression-control statuses are stable.

Also ran `/home/ian/workspace/scripts/lint-planning.sh biomcp`; result: `all clean`.

No production code was modified.

## Produced Artifacts

Persistent planning artifacts:
- `/home/ian/workspace/planning/biomcp/artifacts/369-score-variant-agent-source-apis/source-api-feasibility.md`
- `/home/ian/workspace/planning/biomcp/artifacts/369-score-variant-agent-source-apis/exploit_current_biomcp_baseline.json`
- `/home/ian/workspace/planning/biomcp/artifacts/369-score-variant-agent-source-apis/exploit_external_api_probes.json`
- `/home/ian/workspace/planning/biomcp/artifacts/369-score-variant-agent-source-apis/exploit_source_feasibility_matrix.json`
- `/home/ian/workspace/planning/biomcp/artifacts/369-score-variant-agent-source-apis/exploit_regression_control_summary.json`

Repo experiment copies:
- `architecture/experiments/369-score-variant-agent-source-apis/source-api-feasibility.md`
- `architecture/experiments/369-score-variant-agent-source-apis/results/exploit_current_biomcp_baseline.json`
- `architecture/experiments/369-score-variant-agent-source-apis/results/exploit_external_api_probes.json`
- `architecture/experiments/369-score-variant-agent-source-apis/results/exploit_source_feasibility_matrix.json`
- `architecture/experiments/369-score-variant-agent-source-apis/results/exploit_regression_control_summary.json`

## Contract Numbers

Downstream spikes can depend on:
- 21 candidate sources covered.
- 12 good candidates, 8 possible-but-gated, 1 reject/default-exclude.
- 4 follow-up tickets in priority order.
- Transcript HGVS `NM_000248.3:c.135del` remains unsupported by current `get variant` and should be addressed by normalization proxies.
- ASCO DOI `10.1200/JCO.2018.36.15_suppl.e24316` remains missed by current `get article` and is the canary for DOI/conference metadata.
- KLHL6 `rs148924291` population remains available through MyVariant-carried gnomAD with `gnomad_af=0`, but this is a labelled fallback, not a direct exact-allele population proof.

## Conclusions

Promote the four-ticket follow-up set. Start with capability discovery because it lets agents know supported source/input/status surfaces before guessing. Then add transcript-HGVS normalization via upstream services, then DOI/access metadata. Direct exact-allele gnomAD should wait until normalized coordinate and dataset contracts are in place. Keep workflow interpretation, local document search, messy report cleanup, and direct COSMIC integration outside BioMCP.
