pubmed-search

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

1. Search: GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi with db=pubmed&term=<query>&retmode=json&retmax=20.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.