/biomcp-research

name: biomcp-research
description: Do biomedical literature and variant research with the BioMCP CLI, and file what you learn about the tool itself as issues in the biomcp repo.
user-invocable: true
metadata:
  short-description: Research with BioMCP, and feed back what it lacks

Research with BioMCP

`biomcp` is on PATH; source is `repos/biomcp`. `biomcp list` is the command reference, `-j/--json` for machine-readable output.

Two jobs run together here. **Answer the question** you were asked, and **notice what the tool could not do** while answering it. The second is not a distraction — a research session is the only time anyone finds out where the gaps are, and if they are not written down that day they are lost.

The loop

1. **Web search first, breadth.** Find out what exists — the paper, the registry entry, the guideline. BioMCP is precise, not exploratory; it answers about things you can already name. 2. **BioMCP for the record.** `get article <pmid>` for the citable metadata and abstract, `search article` / `article citations` / `article references` to walk outward from a seed. 3. **Go to the primary source.** If the answer lives in a registry, a database, or a specification, fetch it directly. Quote it. 4. **Prefer practice over prose.** When a document contradicts itself, what people actually did settles it better than what the document meant. Say which one you used.

Context discipline

`get article <id> fulltext` prints a **path**, not the text. That is deliberate: a paper is tens of kilobytes and dumping it pins that cost into the session for good. Do not reflexively read the whole file back.

Read the abstract from `get article <id>` first — it answers more questions than you expect. If you must open the cached file, grep it for the term you need, or read a bounded range. Read it whole only when you are genuinely going to use most of it.

Same for `--json` output. Pipe it through a filter; do not print manifests to the transcript to look at one field.

Verify before you trust it

Cross-entity data is joined from several upstreams and the joins can be wrong. A protein change and a cDNA change on the same line can come from different transcripts. A `.xlsx` that arrives as `text/html` is a download placeholder, not a spreadsheet.

Before a fact goes in a deliverable, check it against a second source or against internal consistency. When something looks off, query the upstream directly (MyVariant, Europe PMC, NCBI) to find out whether the defect is BioMCP's or inherited — the answer decides whether it is a bug or a feature request.

Open sources BioMCP does not cover

All keyless, all JSON, all worth knowing:

• **ClinGen CSpec registry** — gene-specific classification rules.

`https://cspec.genome.network/cspec/SequenceVariantInterpretation/id/GN003`, and attachments at `…/cspec/File/id/<entId>/data` using ids found inside the payload.

• **ClinGen Evidence Repository** — expert panel assertions with

their applied evidence codes and guideline version. `https://erepo.genome.network/evrepo/api/classifications?gene=PTEN&matchLimit=500`

• **Europe PMC** — open-access checks and full text.

`https://www.ebi.ac.uk/europepmc/webservices/rest/search?query=EXT_ID:<pmid>&resultType=core&format=json`

• **gnomAD documentation** as source markdown, since the browser is

a JavaScript app that WebFetch cannot read: `github.com/broadinstitute/gnomad-browser/tree/main/browser/help/topics`

Report honestly

A researched negative is a result. "I looked in these three places and it is not published" changes what gets built; a silent gap does not. Say which sources you read, quote the sentence you are relying on, and label inference as inference — especially when you are reasoning from what someone did rather than what they wrote.

Paywalls are findings too. Name the article, say it is paywalled, and say what you could and could not establish without it.

Feeding back: issues in the biomcp repo

Bugs and feature ideas both go in `repos/biomcp/sdlc/issues/`, one file each, kebab-case filename that reads as a sentence. Feature ideas take a `feature-` prefix so the two are separable at a glance. Open with an `# H1` title and a `Severity:` line (`blocking` / `should-fix` / `nice-to-have`). The `triage` skill promotes them to tickets later; that is a conversation with Ian, not something to do here.

They are opposite kinds of claim and want opposite evidence.

**A bug says the tool is wrong.** Carry the reproduction, the observed output, the correct value, and the root cause if you found it. Trace it into the source and cite `file.rs:line`. Say whether the defect is BioMCP's or inherited from upstream, because that decides who fixes it. Diagnose before you file — an issue that ends at "this warning appears" costs the next person the whole investigation, and you already had the terminal open.

**A feature says the tool is incomplete.** The evidence is different and it is easy to file the wrong thing.

• **Lead with the question you could not answer**, not the feature

you want. "Every ACMG frequency criterion is defined on filtering allele frequency and nothing here reports it" is an argument. "Add FAF support" is a preference.

• **Say what you did instead.** The workaround is the cost estimate.

Downloading 19MB and grepping it is a strong case for a command; one extra web search is not.

• **Check it does not already exist.** Read `biomcp list` and try

it. Filing a request for a shipped feature wastes everyone's time and makes the rest of the batch less trustworthy.

• **Propose a shape, ranked cheapest first**, and be honest that the

cheapest one may be enough. Most of the value usually sits in the first item.

• **Record the negative results you already paid for**, so nobody

repeats the search. "No expert panel has written this policy anywhere; all 122 specifications were searched" is worth as much as the request itself.