How to: find articles¶
This guide shows practical literature-search patterns.
Translate a question into filters¶
When the gene, disease, or drug is already known, put that anchor in a typed
flag and keep the mechanism, phenotype, dataset, or outcome in -k.
Known anchor plus concept:
Unknown entity, keyword first:
Do not guess -g, -d, or --drug when the question is trying to identify
the entity itself. Keep the first search keyword-only, or start with
biomcp discover "<question>" if you want a typed follow-up command first.
Question-format terms can stay in the article filters: PubMed ESearch cleans
bounded filler words from unfielded gene, disease, drug, and keyword terms
provider-locally, while query echoes and non-PubMed sources keep the original
wording.
If the whole keyword exactly matches a gene, drug, or disease vocabulary label
or alias, keyword-only article search may return a typed get suggestion in
See also, _meta.next_commands, and JSON _meta.suggestions[]. Treat that
as a structured follow-up option, but do not expect direct entity suggestions
for multi-concept phrases such as BRAF V600E or lung cancer immunotherapy.
Dataset or method question:
Refine with typed flags before paginating:
If the first page reveals the gene, disease, or drug that actually anchors the question, rerun with that typed flag before you spend time paginating a noisy keyword-only result set.
Avoid keyword reformulation loops¶
When an agent is iterating on one literature task, pass a short local
--session label and request JSON. If the next keyword search overlaps the
previous same-session keyword by at least 60% after BioMCP removes common
search filler words, JSON _meta.suggestions[] can point to a better fallback:
inspect the prior hits with batch article --mode compact, map the topic with discover, or
narrow by publication year when the current page supports that retry.
biomcp --json search article -k "Oncotype DX review" --session lit-review-1 --limit 5
biomcp --json search article -k "Oncotype DX DCIS" --session lit-review-1 --limit 5
Treat --session as a non-secret local correlation label. Do not put PHI,
credentials, email addresses, or user identifiers in it. Markdown article
search output does not show loop-breaker suggestions.
Start from a known anchor¶
search article always works without credentials. BioMCP keeps
sort=relevance as the default, but the effective ranking mode depends on the
query: keyword-bearing searches default to hybrid scoring, while entity-only
searches default to lexical directness. The default source set stays PubTator3,
Europe PMC, PubMed, and compatible Semantic Scholar; use --source
semanticscholar or --source litsense2 explicitly when you want one of those
sources alone. S2_API_KEY upgrades Semantic Scholar
requests to authenticated quota; without it, BioMCP uses the shared pool.
Explicit --source routes do not contact Semantic Scholar for enrichment;
responses show candidate and enrichment sources separately.
BioMCP also caps each federated source's contribution after deduplication and
before ranking. Default: 40% of --limit on federated pools with at least
three surviving primary sources. Rows count against their primary source after
deduplication. Use --max-per-source <N> to override that cap, use
--max-per-source 0 for the default cap explicitly, and set it equal to
--limit to disable capping.
Find papers for one exact variant¶
When the question starts with a specific allele, use the variant pivot rather than manually trying one spelling at a time:
The default union resolves the variant once, searches compatible PubTator
annotations and normalized exact aliases, adds validated source citations,
then merges, ranks, and paginates once. JSON preserves each paper's route,
source, and matched-alias provenance. Use --strategy annotation or
--strategy lexical only to diagnose route recall. If a selected provider is
incomplete, inspect complete, truncated, pagination.total, and
source_status rather than treating an empty page as a complete miss.
The command applies one 60-second monotonic provider-work deadline to the
entire invocation, including all items in a batch. Work completed before the
deadline is retained. Incomplete responses use an unknown total and
has_more: true; a zero-row incomplete item carries deadline_exceeded or
source_unavailable, while a healthy empty search keeps error: null.
For a bounded shortlist across several exact variants, write 1-10 structured objects and make one JSON request:
[
{"request_id":"braf-v600e","gene":"BRAF","protein":"p.V600E"},
{"request_id":"myd88-s219c","gene":"MYD88","protein":"p.S219C"}
]
biomcp --json variant articles --input variants.json --limit 5
biomcp --json variant articles --input variants.json --debug-plan
The compact ordered items retain resolution, route/source, pagination,
completeness, and retraction facts without abstracts or hydrated article cards.
Use _meta.next_commands for batch/detail/full-text/assets/citation follow-ups.
The opt-in plan explains normalized aliases, providers, calls/pages, ranking,
and the two-worker, 50-work-unit-per-item bounds.
At most ten provider exchanges run concurrently across those two workers.
When your authority is an assembly-aware RefSeq identity, use either complete form in the same array:
[
{"request_id":"atm-hgvs","genomic":"NC_000011.10:g.108248927T>G","build":"GRCh38"},
{"request_id":"atm-fields","gene":"ATM","transcript":"NM_000051.4","coding":"c.1066-6T>G","accession":"NC_000011.10","position":108248927,"ref":"T","alt":"G","build":"GRCh38"}
]
caller_supplied means BioMCP accepted the supplied fields as one caller
assertion; it validated syntax but did not establish cross-coordinate
equivalence. resolution.basis is caller_supplied, provider_confirmed, or
null. MyVariant validation is confirmed, not_found, indeterminate,
contradictory, or unavailable; matched_alias is non-null only when
confirmed and contradictory_field only when contradictory. Article
provenance.query_aliases separately records retrieval inputs, not observed or
verified article identity. Invalid items use resolution: null.
| Validation | Retrieval meaning |
|---|---|
| confirmed | provider-confirmed exact routes and source citation |
| not found | caller-supplied RefSeq exact routes; citation skipped without degradation |
| indeterminate | caller exact routes continue, but completion and total remain unknown |
| contradictory | no exact route; only explicitly labelled best-effort fallback |
| unavailable | caller exact routes continue, but output is incomplete and truncated |
Only caller-present transcript/coding, gene/coding, and RefSeq genomic aliases
enter exact RefSeq retrieval. BioMCP does not liftover, convert accessions to
chr, flip strands, select transcripts, or infer coordinate aliases. Existing
chrN inputs remain valid, and versioned RefSeq always requires GRCh37 or
GRCh38.
Search PubMed directly¶
Direct PubMed search and the compatible federated PubMed leg apply the same question-format cleanup before ESearch, so a keyword question can still echo as written while PubMed receives content terms.
Add disease context¶
Tune semantic versus lexical balance¶
biomcp search article -k "Hirschsprung disease ganglion cells" --ranking-mode hybrid --weight-semantic 0.5 --weight-lexical 0.2 --limit 5
Use --ranking-mode lexical to force the old directness comparator on a
keyword query, --ranking-mode semantic to sort by the LitSense2-derived
semantic signal first, or --weight-* flags to retune the default hybrid
formula 0.4*semantic + 0.3*lexical + 0.2*citations + 0.1*position. Rows
without LitSense2 provenance contribute semantic=0 in semantic-aware
ranking modes. In hybrid mode, the lexical component is the fraction of unique
query anchors found in the title or abstract; an anchor found in both counts
once. Lexical mode keeps its tiered title/abstract comparator.
For keyword relevance searches, BioMCP warns when the top result has only
partial literal query coverage. In Markdown, inspect the Why column before
citing the result. In JSON, the warning appears in _meta.warnings[] for both
compact and --full output; use --full to inspect row-level ranking metadata.
This warning describes literal coverage only and does not declare a semantic or
synonym match irrelevant.
Cap one source explicitly¶
Constrain by date¶
Exclude preprints when supported¶
Pull the full-text section¶
Fetch several shortlisted papers at once¶
Use batch article --mode compact after search when you already know the candidate PMIDs or
DOIs and want compact title/journal/year/entity cards before opening one paper
in full detail. The helper preserves input order and still works when
S2_API_KEY is unset.
Use --type carefully¶
--type on the default --source all route uses Europe PMC + PubMed when the
other selected filters are PubMed-compatible. If you also need
--open-access or --no-preprints, PubMed drops out and the search collapses
to Europe PMC-only with an explicit note. Use --source pubmed when you want
PubMed-only article search on the compatible filter set and do not need those
PubMed-incompatible filters.
Inspect the ranking rationale in JSON¶
Look for semantic_scholar_enabled, row-level matched_sources, and
ranking metadata to see why a paper ranked where it did. Hybrid rows expose
normalized semantic, lexical, citation, and source-position components plus the
composite score; lexical rows preserve the existing directness metadata.
Inspect the executed search plan¶
Markdown:
JSON / MCP-friendly text output:
--debug-plan adds a top-level debug_plan payload in JSON and prepends the
same payload as a fenced JSON block in markdown. Request JSON+plan for MCP
callers with --json --debug-plan.
Follow-up pattern¶
After identifying key papers, pivot to trials or variants: