| name | pubmed-search |
| description | Search PubMed via NCBI E-utilities to ground questionnaire items in primary literature. Use when the user asks for evidence, citations, or "what does the research say about X." Produces an organized research bundle with PubMed metadata, abstracts when available, and source-grounded notes. |
PubMed search
When to use this
- The user asks for primary evidence behind a question, an instrument,
a threshold, or a recommendation.
- You're proposing a new item and want to attach a real citation
(paper-typed) rather than only an instrument-typed reference.
- You're checking whether a draft item or scoring rule is
contradicted by recent literature.
How to do it
- Search: GET
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi
with db=pubmed&term=<query>&retmode=json&retmax=20.
- Fetch: GET
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi
with db=pubmed&id=<comma-separated-PMIDs>&retmode=xml for full
metadata + abstract; or &retmode=json&rettype=abstract for a
compact JSON shape.
- Rate limit: 3 requests/second without a key, 10/sec with one
(
&api_key=<NCBI_API_KEY> if process.env.NCBI_API_KEY is set).
Always include &tool=formtastic-studio&email=ops@example per
NCBI policy.
- Output: write the durable research record to
$FORMTASTIC_RUN_DIR/output/research/bundle.json. Put each selected
citation in sources[] with { id, kind: "paper", title, url, year, authors, citation, identifiers: { pmid, doi? }, abstract?, relevance, sourceFile, extractFile? }. Record the actual E-utilities query in
searches[] with transcriptFile, and put short synthesis notes in
notes[] with noteFile.
- Supporting files: write the query transcript under
output/research/searches/, selected PMID/source metadata under
output/research/sources/, and brief paraphrased extraction notes under
output/research/extracts/ when the source supports a specific item,
threshold, or answer choice.
- Synthesis: write
$FORMTASTIC_RUN_DIR/output/findings.json only
as a compact UI-facing claim/evidence summary derived from the bundle.
Query patterns that work
- Free text + MeSH:
"migraine"[MeSH] AND prophylaxis AND ("randomized controlled trial"[pt] OR "systematic review"[pt]).
- Recent: append
AND ("last 5 years"[dp]).
- Restrict to humans:
AND humans[mh].
- Instrument validation:
<instrument name>[Title/Abstract] AND (validation[ti] OR psychometric[ti]).
Citing what you find
In Questionnaire JSON, attach a paper-typed citation:
{
"url": "https://formtastic.studio/fhir/StructureDefinition/citation",
"extension": [
{ "url": "refType", "valueCode": "paper" },
{ "url": "refId", "valueUri": "https://pubmed.ncbi.nlm.nih.gov/<PMID>" },
{ "url": "note", "valueMarkdown": "Brief 1-line takeaway." }
]
}
Use valueUri (not valueCanonical) for papers.
Common pitfalls
- Hallucinated PMIDs. Only cite IDs that came back from esearch this
turn. If you can't find one, say so in
reply.md.
- Quoting the abstract verbatim. Paraphrase; the abstract is
copyrighted. Cite the PMID and let the UI link out.
- Saving full article text. Store metadata, abstracts/snippets when
available, and your own extraction notes — not copied full text.
- Misattributing pre-prints. medRxiv/bioRxiv are NOT PubMed-indexed;
use the DOI as
valueUri and flag pre-print status in note.
