Pubmed Database

PubMed API

Prerequisites

1. `uv`: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH. 2. User Notification: If LICENSE_NOTIFICATION.txt does not already exist in this skill directory then (1) prominently notify the user to check the terms at https://pubmed.ncbi.nlm.nih.gov/disclaimer/ and https://www.ncbi.nlm.nih.gov/home/about/policies/ and to always check the license of the papers retrieved by the skill for any restrictions, then (2) create the file recording the notification text and timestamp. 3. `.env` file: Make sure the .env file exists in your home directory. Create one if it does not exist. 4. `NCBI_API_KEY` (optional): Raises the NCBI E-utilities rate limit from 3 to 10 requests/second. The skill works without it, but a key is recommended if the user plans many queries or encounters a 429 error. The user can obtain one for free by registering at https://www.ncbi.nlm.nih.gov/account/settings/ 5. `USER_EMAIL` (optional but recommended): Identifies the caller to NCBI (recommended by their Terms of Use).

If the variables are missing from .env, do NOT ask the user to paste them into the chat (this would leak keys into the agent's context). Instead, give the user these commands — substituting `ENV_FILE` with the resolved literal path to the `.env` file:

printf "Enter NCBI API key (typing hidden): " && read -s key && echo && echo "NCBI_API_KEY=$key" >> "ENV_FILE" && echo "Saved."

printf "Enter contact email: " && read email && echo "USER_EMAIL=$email" >> "ENV_FILE" && echo "Saved."

The scripts load credentials automatically via dotenv. NEVER read, print, or inspect the .env file or its variables (e.g. no cat, grep, echo, printenv, or os.environ.get on keys). Credentials must stay out of the agent's context.

This skill provides CLI access to the NCBI PubMed and PubMed Central APIs via scripts/pubmed_api.py — a single CLI with 10 functions covering search, fetch, linking, full text, spelling, discovery, citation matching, and caching.

Core Rules

• API Use: Always use the provided wrapper scripts/pubmed_api.py which

manages rate limits automatically and prevents API abuse. Setting the NCBI_API_KEY environment variable raises the rate limit from 3 to 10 requests/second. Querying the API any other way (e.g. via curl, wget, or hand-written code) is strictly forbidden.

• JSON Processing: Use jq to filter and transform JSON output (or python

equivalents if jq is not available) to prevent hallucinations and context overflow.

• Temporary Files: To avoid polluting the working directory with JSON

files, use a temporary directory inside the current directory. When running multiple agents or tasks in parallel, ensure each uses a unique subdirectory name (e.g., tmp_$TASK_ID/) to avoid file collisions.

• Notification: If this skill is used, ensure this is mentioned in the

output AND list the URLs of all papers that were used in producing the output.

Structure of the skill folder

• SKILL.md - This file
• scripts/pubmed_api.py - The skill CLI
• references/ - Directory with detailed function specifications
• advanced-linking.md
• advanced-search.md
• bulk-workflows.md
• citation-matching.md
• cross-database-linking.md
• fetch-and-resolve.md
• search-and-discovery.md
• utilities.md

CLI Usage

uv run scripts/pubmed_api.py <output_file> <function_name> <required_args> [--flag value ...]

• Positional Arguments: Arguments are positional; list arguments are

passed as comma-separated strings without spaces (e.g. "35113657,31234568").

• Flag Options: Optional arguments can be passed as --flag value instead

of positional args.

• Output Handling: On success, JSON is written to output_file. On error,

the process exits with a non-zero code and no output file is written.

Example Usage

uv run scripts/pubmed_api.py ./search_results.json search_pubmed "BRCA1" --max_results 5
cat ./search_results.json | jq '.[]' -r
uv run scripts/pubmed_api.py ./abstracts.json fetch_article_abstracts "35113657"
cat ./abstracts.json | jq '.[0].title' -r

Essential Recipes

Join PMIDs for the next call (most common chaining pattern):

cat ./search_results.json | jq -r 'join(",")'

Slim abstracts to essential fields and truncate long abstracts:

cat ./abstracts.json | jq '[.[] | {pmid, title, snippet: (.abstract // "")[:500]}]'

Filter by keyword (null-safe):

cat ./abstracts.json | jq '[.[] | select((.title // "") | contains("Review"))]'

Context Management & Accuracy

When processing larger result sets (>10 abstracts):

1. Filter Early: Use jq to verify keywords in abstracts before reading the full JSON into context. 2. Slimming: Extract only title and abstract fields unless explicitly instructed otherwise. Author lists and metadata contribute to noise. 3. Bulk Operations (N > 10): Avoid fetching or processing IDs one-by-one. The API and History Server are designed for bulk retrieval. Fetch all data in a single turn and use shell pipelines to slim the results before reading into context. This prevents turn exhaustion and context overflow. 4. Grounding: Never use internal knowledge to provide specific identifiers (PMIDs, CIDs, Gene IDs) if no results are found. Report the tool's output accurately to ensure results are grounded in the current database state. 5. Search Termination: When asked to find papers that may not exist, limit exploration to 3–5 high-quality, varied search queries. If no results match after these attempts, conclude that no papers meet the criteria rather than continuing to iterate — unless explicitly instructed to be thorough.

Functions

⚠️ MANDATORY: You MUST read the linked reference file for a function

group before calling any function in that group. The tables below only

describe what each function does — not how to call it. Argument names,

argument order, flags, and output schemas are only documented in the

reference files. Do NOT guess or infer arguments from function names. If

you call a function without first reading its reference, you will produce

incorrect invocations.

Search

• search_pubmed: Find PMIDs matching a free-text or structured NCBI query.
• global_database_discovery: Count how many records match a query across

every NCBI database.

Fetch & Resolve

• fetch_article_abstracts: Retrieve metadata and abstracts for a batch of

PMIDs.

• get_full_text_pmc: Retrieve open-access full text from PMC.
• fetch_database_summary: Resolve opaque UIDs from any NCBI database into

human-readable metadata.

Cross-Database Linking

• find_linked_biological_data: Find records in other NCBI databases linked

to a source record.

• discover_available_links: List all available ELink linknames for a given

record.

Bulk Workflows

When working with more than ~10 PMIDs, avoid processing IDs one-by-one. Upload them to the NCBI History Server via cache_results_history to get a session handle (webenv + query_key), then pass that handle to fetch_article_abstracts or find_linked_biological_data for a single bulk call. Chain with jq shell pipelines to slim results before reading into context. This prevents turn exhaustion and context overflow. See the reference for complete workflow recipes (search→fetch, cross-db exploration, citation resolution, and bulk retrieval with data slimming).

• cache_results_history: Upload PMIDs to the NCBI History Server for bulk

retrieval.

Utilities

• verify_medical_spelling: Spell-check biomedical terms before searching.
• match_raw_citations: Resolve incomplete bibliographic citations to PMIDs.

Advanced Biological Database Linking (ELink)

1. Core Concepts: Database vs. Linkname

A query requires both a target_database and a linkname:

• Target Database: The destination repository (e.g., gene, nuccore,

pccompound).

• Linkname: The specific "semantic bridge" defined by NCBI. Linknames follow

the naming convention: dbfrom_db_subset. One database pair can have multiple linknames representing different relationships.

Common Database and Linkname Pairs

• pubmed, pubmed_pubmed_citedin: Forward Citations — Find papers

that cite the source paper.

• pubmed, pubmed_pubmed_refs: Backward Citations — Extract the

source paper's bibliography.

• pubmed, pubmed_pubmed: Similar Articles — Papers sharing MeSH

terms or keywords.

• pmc, pubmed_pmc: Full Text — Resolve a PMID to a PMCID (required

for BioC API).

• pccompound, pubmed_pccompound: Chemicals — Find specific chemicals

or drugs mentioned (CIDs).

• pcassay, pubmed_pcassay: PubChem BioAssays — Link to experimental

results and screening data.

• gene, pubmed_gene: Genetics — Identify specific NCBI Gene records

discussed.

• nuccore, pubmed_nuccore: Sequence Data — Link to

GenBank/nucleotide sequences.

• protein, pubmed_protein: Proteins — Link to RefSeq or GenPept

protein records.

• clinvar, pubmed_clinvar: Clinical Variants — Find links to the

ClinVar database (mutations).

• snp, pubmed_snp: SNPs — Find specific Single Nucleotide

Polymorphisms.

• sra, pubmed_sra: Raw Data — Find raw datasets in the Sequence Read

Archive.

• structure, pubmed_structure: 3D Structures — Find molecular

structures (PDB) for proteins/ligands.

This list covers the most common pubmed → X links. For the full list of all ELink linknames across all NCBI databases, see the NCBI Entrez Links catalog.

--------------------------------------------------------------------------------

2. Procedural Wisdom: Handling Failure Modes

The "Indexing Lag" Problem (Recent Papers)

NCBI links are not created instantly. There is a human-in-the-loop and automated indexing process that results in a 4-8 week delay for cross-database links.

Symptom: find_linked_biological_data returns [] for a paper published 2 weeks ago.

Strategy: If the paper is very recent, pivot immediately to semantic search or full-text extraction. Use get_full_text_pmc and search for primary identifiers in the prose (e.g., by searching for specific identifiers or nomenclature manually).

The "High-Citation" Timeout

For foundational papers with >10,000 citations, pubmed_pubmed_citedin may fail or timeout.

Strategy: Instead of linking, use search_pubmed with the title of the paper in quotes or a specific query like "citations for PMID [SOURCE_PMID]"

Verifying Open Access Availability

Before calling get_full_text_pmc, it is more reliable to check the link first

Workflow: Call find_linked_biological_data with target_database="pmc" and linkname="pubmed_pmc". If it returns a result, the paper is definitely in the PMC BioC database. If not, don't waste time on a full-text fetch; use fetch_article_abstracts instead.

--------------------------------------------------------------------------------

3. Category-Specific Tips

Chemical Entities (pccompound, pcassay)

Links to chemical databases typically return internal identifiers (e.g., PubChem CIDs) rather than common names.

Example: A link to a drug study might return ["4091"].

Note: To resolve these to names, you must use a separate metadata lookup or search strategy, as the linking tool only provides the relationship, not the entity details.

Sequence and Genomic Data (nuccore, protein, gene)

These links represent formal submissions to NCBI repositories (like GenBank).

Strategy: If a link search returns empty for recent research, search for the paper's title or key findings in PubMed to find the abstract. Authors often include primary identifiers in the text before the database cross-references are finalized.

--------------------------------------------------------------------------------

4. Troubleshooting Empty Results

If find_linked_biological_data returns []:

1. Check Date: Is it a recent paper? (Indexing lag). 2. Check Scope: Is the topic niche? (Authors may not have submitted data to NCBI). 3. Check Database Pair: Ensure you are using the correct linkname for the target_database. Using pubmed_gene with target_database="nuccore" will fail.

--------------------------------------------------------------------------------

5. Advanced Features

• Reverse lookups: find_linked_biological_data accepts a dbfrom

parameter (default: "pubmed"). Set it to another database to traverse links in the opposite direction (e.g., gene → pubmed).

• Date filtering: Pass mindate and maxdate (YYYY/MM/DD format) to

filter linked results by publication date. Only works when dbfrom and target_database are both "pubmed".

• Link discovery: Use discover_available_links with a record ID to list

all available linknames before calling find_linked_biological_data.

PubMed Advanced Search Reference

This guide provides a comprehensive reference for advanced PubMed querying, specifically for scientific research, high-precision filtering, and niche metadata analysis.

1. Complete Field Qualifier Reference (Search Tags)

• [sh], MeSH Subheadings: Limits a MeSH term to a specific aspect. E.g.,

"Parkinson disease/genetics"[sh]. Common: /therapy, /toxicity, /drug effects.

• [majr], MeSH Major Topic: Limits results to citations where the MeSH

term is the primary focus of the article.

• [crdt], Create Date: The date the record was first added to PubMed. Best

for finding "what's new" in the database.

• [edat], Entry Date: Used for sorting by "Most Recent." Set to

publication date for older papers newly added.

• [sb], Subset: Pre-built high-quality filters. E.g., systematic[sb],

"free full text"[sb], cancer[sb].

• [nm], Supplementary Concept: For specific chemicals, drugs, or rare

substances not yet in MeSH (formerly Substance Name).

• [ad], Affiliation: Search for authors at specific institutions, cities,

or countries. E.g., Stanford[ad].

• [auid], Author Identifier: Search by unique identifiers like ORCID.

E.g., 0000-0002-1234-5678[auid].

• [la], Language: Restrict results by language. E.g., eng[la].
• [pt], Publication Type: Filter by study design: Meta-Analysis,

Systematic Review, Randomized Controlled Trial.

• [tw], Text Word: Includes Title, Abstract, MeSH, Subheadings, and other

indexing fields. Very broad.

• [ta], Journal: Search by NLM Title Abbreviation or ISSN. E.g.,

Nature[ta].

2. Advanced Syntax & Logic

Proximity Searching

Finds terms within a specific distance of each other. Available in [ti], [tiab], and [ad].

Format: "term1 term2"[field:~N]

Example: "gut microbiome"[tiab:~2] finds "gut" and "microbiome" with up to 2 words between them.

Boolean Nesting

PubMed processes logic from left to right. Use parentheses to control the order of operations.

Example:

(Parkinson OR "Dopamine deficiency") AND (Microbiome OR "Gut Flora")

Truncation

Use * at the end of a word to search for all terms that begin with that root.

Example: patholog* finds pathology, pathologist, pathological.

Note: Truncation turns off Automatic Term Mapping (ATM).

3. Specialized Research Strategies

Evidence-Based Medicine (EBM) Filters

To find the highest quality clinical evidence, append these filters:

• Systematic Reviews: AND systematic[sb]
• Clinical Trials: AND "Clinical Trial"[pt]
• Meta-Analyses: AND "Meta-Analysis"[pt]

The "Expert Query" Construction

For maximum coverage and precision, combine MeSH terms with Title/Abstract keywords:

("Parkinson Disease"[mesh] OR "Parkinson's"[tiab])
    AND ("Gastrointestinal Microbiome"[mesh] OR "gut microbiome"[tiab:~2])

Tracking Literature Updates

To find only the papers added to the database since your last visit (e.g., March 1st):

• Parkinson[tiab] AND 2026/03/01:2026/03/13[crdt]

4. Troubleshooting & Nuances

• ATM (Automatic Term Mapping): If you search Parkinson, PubMed

automatically adds "Parkinson Disease"[mesh]. If you use quotes ("Parkinson") or truncation (Parkinson*), ATM is disabled.

• Interchangeable Tags: [dp] and [pdat] are identical. [ta] and

[journal] are identical.

• Language Bias: PubMed is predominantly English-language. Use eng[la]

if the agent must perform text analysis on the results.

Bulk Workflows

Argument specifications for cache_results_history and common multi-step batch patterns for search, fetch, linking, and large-scale retrieval.

cache_results_history — Batch-upload PMIDs for bulk retrieval

Uploads a batch of PMIDs to the NCBI History Server and returns a webenv and query_key session handle. Use this when working with more than ~10 PMIDs or when the same batch of IDs will be passed to multiple subsequent calls (e.g. fetch abstracts and link to genes). For small batches (≤10 IDs), pass them inline instead — it saves a round-trip. The returned handles can be passed to fetch_article_abstracts or find_linked_biological_data.

uv run scripts/pubmed_api.py ./batch_session.json cache_results_history "35113657,31234568,29474920"

Arguments:

• pmids (list[str], required) – comma-separated PMIDs to upload.

Output:

{
  "webenv": "NCID_1_123456789_130.14.18.97_9001",
  "query_key": "1"
}

--------------------------------------------------------------------------------

Workflow Recipes

Search → batch fetch abstracts → summarize

uv run scripts/pubmed_api.py ./mrna_melanoma_results.json search_pubmed "mRNA vaccines melanoma" --max_results 5 --sort_by relevance
uv run scripts/pubmed_api.py ./mrna_melanoma_abstracts.json fetch_article_abstracts "PMID1,PMID2,PMID3,PMID4,PMID5"

Search → full text (open-access only)

uv run scripts/pubmed_api.py ./psilocybin_depression_results.json search_pubmed "psilocybin depression" --max_results 5 --sort_by relevance
uv run scripts/pubmed_api.py ./psilocybin_depression_full_text.json get_full_text_pmc "PMID1"

If get_full_text_pmc returns an error, the paper is not open-access; use fetch_article_abstracts instead.

Fuzzy citation → fetch

uv run scripts/pubmed_api.py ./nature2006_pmids.json match_raw_citations "nature|2006||||takahashi k|key0|"
uv run scripts/pubmed_api.py ./abstracts.json fetch_article_abstracts "RESOLVED_PMID"

Cross-database exploration

uv run scripts/pubmed_api.py ./35113657_links.json discover_available_links "35113657"
uv run scripts/pubmed_api.py ./35113657_gene_links.json find_linked_biological_data "35113657" gene pubmed_gene
uv run scripts/pubmed_api.py ./35113657_compound_links.json find_linked_biological_data "35113657" pccompound pubmed_pccompound
uv run scripts/pubmed_api.py ./35113657_nuccore_links.json find_linked_biological_data "35113657" nuccore pubmed_nuccore
uv run scripts/pubmed_api.py ./35113657_citing_papers.json find_linked_biological_data "35113657" pubmed pubmed_pubmed_citedin

Bulk Retrieval and Data Slimming (N > 10)

For large result batches, avoid processing IDs iteratively. Chain cache_results_history and shell pipelines to perform batch retrieval and slimming in one turn.

# 1. Search and batch-upload to get a session handle
PMIDS=$(uv run scripts/pubmed_api.py ./s.json search_pubmed "CRISPR" --max_results 50 && cat ./s.json | jq -r 'join(",")')
uv run scripts/pubmed_api.py ./session.json cache_results_history "$PMIDS"
WEBENV=$(cat ./session.json | jq -r '.webenv')

# 2. Bulk fetch AND slim to only relevant fields in ONE turn
# Use brackets in jq [ ... ] to ensure the output is a valid JSON array.
uv run scripts/pubmed_api.py ./full.json fetch_article_abstracts "" --webenv "$WEBENV" --query_key 1
cat ./full.json | jq '[.[] | {pmid: .pmid, title: .title, abstract: .abstract}]' > ./slim.json

When using --webenv/--query_key, pass "" for the pmids argument.

Citation Matching Guide (ecitmatch)

The match_raw_citations tool uses NCBI's ecitmatch endpoint, which predates modern APIs. This guide covers the pipe format, field selection strategies, and what to do when matching fails.

--------------------------------------------------------------------------------

1. The Pipe Format

Each citation is a single string with 7 pipe-separated fields and a trailing pipe:

journal|year|volume|first_page|author_name|key|

All fields except journal are optional — empty segments are valid. The key is an arbitrary label you choose to track which citation matched which PMID in the results.

Examples: nature|2006||||takahashi k|ref1| proc natl acad sci|2007|104|11760|takahashi k|ref2| cell|2020|183||doe j|ref3|

Assemble the pipe-delimited string directly — all fields except journal are optional, so leave unwanted segments empty.

--------------------------------------------------------------------------------

2. Which Fields Matter Most

Not all fields contribute equally. ecitmatch uses fuzzy matching, but some combinations are far more reliable than others.

High-value combinations (use these first): - journal + author + year — resolves most citations - journal + volume + first_page — uniquely identifies articles even without author/year

Low-value on their own: - year alone — too broad - first_page alone — page numbers repeat across volumes - volume alone — meaningless without journal

Strategy: Start with whatever fields you have. If it misses, drop the most uncertain field (often first_page or volume) and retry — ecitmatch sometimes does worse with partly-wrong data than with missing data.

--------------------------------------------------------------------------------

3. Journal Name Pitfalls

The journal field is the most critical and the most error-prone.

Abbreviation vs. full name: ecitmatch accepts both, but they are not interchangeable for all journals. When in doubt, use the NLM abbreviated form.

Common mappings: - "The New England Journal of Medicine" → n engl j med - "Proceedings of the National Academy of Sciences" → proc natl acad sci - "The Journal of Biological Chemistry" → j biol chem - "JAMA" → jama (already abbreviated)

Case: ecitmatch is case-insensitive. Nature and nature are equivalent.

Punctuation: Strip periods from abbreviations. Use j biol chem not J. Biol. Chem.

--------------------------------------------------------------------------------

4. Author Name Format

ecitmatch expects last name followed by first initial, lowercase, no periods, no commas.

Only provide the first author. ecitmatch ignores additional authors.

--------------------------------------------------------------------------------

5. Batching Multiple Citations

Pass multiple citations as a comma-separated list to match_raw_citations:

uv run scripts/pubmed_api.py /tmp/pubmed_results.json match_raw_citations \
  "nature|2006||||takahashi k|ref1|,cell|2020|183||doe j|ref2|"

The response returns PMIDs for matched citations only. Unmatched citations are silently dropped. Match the key field in the response to track which citations resolved.

--------------------------------------------------------------------------------

6. When ecitmatch Fails

ecitmatch has a ~70-80% hit rate on well-formed citations and drops sharply with messy input. When it returns empty:

Fallback 1: Search PubMed directly

Construct a query from the citation fields:

uv run scripts/pubmed_api.py /tmp/pubmed_results.json search_pubmed \
  '"Takahashi" AND "2006" AND "Nature"' 5

Fallback 2: Title search

If you have the paper title (even partial):

uv run scripts/pubmed_api.py /tmp/pubmed_results.json search_pubmed \
  '"Induction of Pluripotent Stem Cells"[ti]' 5

Fallback 3: Strip fields and retry

Remove the least-reliable field and resubmit:

uv run scripts/pubmed_api.py /tmp/pubmed_results.json match_raw_citations \
  "nature|2006||||takahashi k|ref1|"
uv run scripts/pubmed_api.py /tmp/pubmed_results.json match_raw_citations \
  "nature|||||takahashi k|ref1|"

Fallback 4: DOI or known identifier

If the source has a DOI, skip ecitmatch entirely:

uv run scripts/pubmed_api.py /tmp/pubmed_results.json search_pubmed \
  "10.1016/j.cell.2006.07.024[doi]" 1

--------------------------------------------------------------------------------

7. Common Failure Patterns

• Returns empty for a known paper — Wrong journal abbreviation. Try full

name or NLM abbreviation.

• Returns wrong PMID — Author name mismatch. Check last-name + initial

format.

• Returns empty for recent paper — Not yet indexed by ecitmatch. Use

search_pubmed title search.

• Returns empty for old paper (pre-1966) — Pre-MEDLINE era. These papers

may lack structured metadata.

• Multiple citations, partial hits — One citation has bad data. Check

returned keys to isolate the miss.

Cross-Database Linking Functions

Detailed argument specifications, output schemas, and strategies for find_linked_biological_data and discover_available_links.

1. find_linked_biological_data — Cross-database linking

Finds records in other NCBI databases linked to a source record. Use this to identify genes, proteins, or chemicals discussed in a paper without parsing the text. Common target databases: gene, protein, nuccore, pccompound, pubmed. Supports reverse lookups (e.g., gene → pubmed) via the dbfrom parameter. This is the required path for entity identification in large batches.

For a complete map of link types and advanced strategies, refer to

• Advanced Biological Database Linking.
• NCBI ELink Reference

python3 scripts/pubmed_api.py ./gene_links.json find_linked_biological_data "35113657" gene pubmed_gene

Arguments:

• source_pmid (str, required) – source record ID (PMID when dbfrom is

pubmed)

• target_database (str, required) – target NCBI database name
• linkname (str, required) – elink link name
• dbfrom (str, default "pubmed") – source database
• mindate (str, default "") – minimum date filter (YYYY/MM/DD),

pubmed→pubmed only

• maxdate (str, default "") – maximum date filter (YYYY/MM/DD),

pubmed→pubmed only

• webenv (str, default "") – WebEnv from cache_results_history
• query_key (str, default "") – query_key from cache_results_history

Output: ["123456", "789101"] (target database record IDs)

Returns [] if no links exist. Use fetch_database_summary to resolve these UIDs into accession numbers, gene names, or other metadata.

Cross-Database Linking Strategy

Unless you are performing a standard citation traversal (pubmed_pubmed_citedin) or gene lookup (pubmed_gene), follow the Discover → Filter → Merge workflow for complete results. Preference: When asked to identify linked entities (genes, compounds, etc.), PREFER using find_linked_biological_data as the primary, most efficient path, rather than searching in external databases by name unless direct links are known to be missing.

1. Discover: Call discover_available_links to see which connections exist for the specific record. 2. Filter: Identify all linkname entries that point to your target database (e.g., all links where db is pccompound). 3. Merge: If multiple linknames point to the same database (e.g., pubmed_pccompound and pubmed_pccompound_mesh), fetch from all of them and merge the results. Different linknames often represent different indexing methods (manual curation vs automated mapping), and using only one may result in missing data.

Warning: Data Freshness. Cross-database links (elink) typically lag behind publication by weeks to months. For papers published in the last year, expect find_linked_biological_data to return [] and pivot to searching for accession numbers or CIDs directly in the abstract text. Does not apply to papers older than 2 years, which should have complete links.

--------------------------------------------------------------------------------

2. discover_available_links — List available linknames

Lists all available ELink linknames for a given record. Use this when you don't know which linkname to pass to find_linked_biological_data.

python3 scripts/pubmed_api.py ./available_links.json discover_available_links "35113657"
python3 scripts/pubmed_api.py ./available_gene_links.json discover_available_links "93986" --dbfrom gene

Arguments:

• source_id (str, required) – source record ID (e.g. a PMID)
• dbfrom (str, default "pubmed") – source database

Output:

[
  {"linkname": "pubmed_gene", "db": "gene"},
  {"linkname": "pubmed_nuccore", "db": "nuccore"},
  {"linkname": "pubmed_pmc", "db": "pmc"}
]

Fetch & Resolve Functions

Detailed argument specifications, output schemas, and usage guidance for fetch_article_abstracts, get_full_text_pmc, and fetch_database_summary.

1. fetch_article_abstracts — Get metadata + abstracts

Retrieves title, authors, journal, publication date, DOI, and abstract text for a batch of PMIDs via a single efetch XML call. Structured abstracts (BACKGROUND, METHODS, RESULTS, CONCLUSION) are concatenated with labels.

uv run scripts/pubmed_api.py ./abstracts.json fetch_article_abstracts "35113657,31234568"

Arguments:

• pmids (list[str], required) – comma-separated PMIDs
• webenv (str, default "") – WebEnv from cache_results_history
• query_key (str, default "") – query_key from cache_results_history

Output: list[object] — one object per PMID:

• pmid (str) — always present
• title (str | null) — null for dead/unpopulated records
• authors (list[str]) — "LastName Initials" format; may be empty
• journal (str | null) — full journal name
• pubdate (str | null) — "YYYY Mon DD" or MedlineDate fallback
• doi (str | null) — null if no DOI on record
• abstract (str | null) — plain text, or "LABEL: text\nLABEL: text" for

structured abstracts

Important: If both the title and abstract are null, the PMID is an unpopulated or "dead" database record. If this occurs, report that the paper does not exist. DO NOT attempt to summarize neighboring PMIDs or guess the intended paper unless explicitly asked to disambiguate.

--------------------------------------------------------------------------------

2. get_full_text_pmc — Open-access full text

Retrieves full text of an open-access article from PMC. Important Only returns articles in the PMC Open Access Subset — with licenses that permit text mining and redistribution. Being "in PMC" is not sufficient; many PMC articles have restrictive licenses that exclude them from the OA subset.

uv run scripts/pubmed_api.py ./full_text_35113657.json get_full_text_pmc "35113657"

Arguments:

• pmid (str, required) – PMID of the article

Output (success): {"pmid": str, "full_text": str}

Output (error): {"error": str, "endpoint": str} — article is paywalled, embargoed, or not in the OA subset.

Important: If you plan to use get_full_text_pmc, pre-filter your search with AND "pmc open access"[filter] to only return papers that are in the OA subset. This avoids wasting calls on papers that will inevitably fail. Note: The "pmc open access"[filter] is highly restrictive and may return zero results for some topics. If so, you can fall back to "free full text"[Filter], but be prepared to handle failures in get_full_text_pmc as not all free papers are in the BioC OA subset. Example:

uv run scripts/pubmed_api.py ./oa_results.json search_pubmed \
  "psilocybin depression AND \"pmc open access\"[filter]" --max_results 5

If retrieval fails, use fetch_article_abstracts to fetch the abstract only.

--------------------------------------------------------------------------------

3. fetch_database_summary — Resolve UIDs from any NCBI database

Retrieves summary metadata for records in any NCBI database. Use this to resolve the opaque UIDs returned by find_linked_biological_data into human-readable data (accession numbers, gene names, descriptions, etc.).

uv run scripts/pubmed_api.py ./nuccore_summary.json fetch_database_summary nuccore "1798174254,1798172431"
uv run scripts/pubmed_api.py ./gene_summary.json fetch_database_summary gene "43740568"
uv run scripts/pubmed_api.py ./compound_summary.json fetch_database_summary pccompound "2244"

Arguments:

• database (str, required) – target NCBI database (e.g. nuccore, gene,

protein, pccompound)

• id_list (list[str], required) – comma-separated UIDs

Output: list[object] — one object per UID with database-specific fields. Key fields by database:

• nuccore/protein:
• uid (str) — NCBI unique identifier for the sequence record
• title (str) — sequence definition line (e.g. `"Homo sapiens BRCA1

mRNA, complete cds"`)

• accessionversion (str) — versioned accession number (e.g.

"NM_007294.4")

• organism (str) — source organism (e.g. "Homo sapiens")
• slen (int) — sequence length in base pairs or amino acids
• moltype (str) — molecule type ("dna", "rna", "aa")
• sourcedb (str) — originating database ("refseq", "insd", etc.)
• gene:
• uid (str) — NCBI Gene ID
• name? (str) — official gene symbol (e.g. "BRCA1")
• description (str) — full gene name (e.g. `"BRCA1 DNA repair

associated"`)

• summary (str) — functional summary paragraph from RefSeq
• organism (object) — `{"scientificname": str, "commonname": str,

"taxid": int}`

• otheraliases (str) — comma-separated alternative gene symbols
• genomicinfo (list[object]) — chromosomal location(s), each with

chrloc, chrstart, chrstop, exoncount

• pccompound:
• uid (str) — NCBI record UID
• cid (int) — PubChem Compound ID
• synonymlist (list[str]) — common names and identifiers (e.g.

["Aspirin", "Acetylsalicylic acid", ...])

• sourcecategorylist (list[str]) — data source categories (e.g.

["Deposited Substances", "Chemical Vendors", ...])

Search Functions

Detailed argument specifications, output schemas, search strategies, and troubleshooting for search_pubmed and global_database_discovery.

1. search_pubmed — Find PMIDs by query

Returns a list of PubMed IDs matching a free-text query. Supports full NCBI query syntax: Boolean operators (AND, OR, NOT), MeSH terms and tags.

1. Syntax: Use term[tag](e.g., Parkinson[ti]). Tags are NOT case-sensitive. 2. Most common tags:

• [tiab]: Title & Abstract (Best for keyword precision).
• [mesh]: Medical Subject Headings (Best for conceptual accuracy).
• [pt]: Publication Type (Filter by Review, Clinical Trial, Case Reports).
• [dp]: Publication Date (Interchangeable with [pdat]).

3. Modern Power Moves:

• Relative Dates: Use "last X months"[dp] or "last X years"[dp] (e.g.,

"last 1 months"[dp]).

• Proximity Search: "word1 word2"[tiab:~N] finds words within N tokens.

Use this instead of AND for multi-word concepts (e.g., "gut microbiome"[tiab:~2]). 4. Reliability: Use YYYY/MM/DD:YYYY/MM/DD[dp] for custom ranges. Avoid dptr.

Search Strategies & Troubleshooting

If searching returns few or no results, try at most 3 queries before changing strategy. After 3 failed searches, the query is flawed. Broaden to core entities (gene + disease), fetch 5 abstracts, and adopt the authors' vocabulary. Relaxation order:

1. Drop Field Restrictors: If you used [tiab]/[ti]/[pt] in the query and got no results, remove them: key terms often appear in body text, not titles.

• Too restrictive: `"CRISPR"[ti] AND "indirect cardiovascular side

effects"[tiab]`

• Better: `"CRISPR" AND "cardiovascular" AND ("side effects" OR "toxicity"

OR "unintended")` 2. Use Broad Synonyms: Group standardized synonyms with OR.

• Example: `("cardiovascular" OR "cardiac" OR "heart") AND ("toxicity" OR

"adverse effects" OR "side effects" OR "off-target")` 3. Use MeSH Terms: If keywords fail, use MeSH indexed terms.

• Example: `"CRISPR-Cas Systems"[mesh] AND "Cardiovascular

Diseases/chemically induced"[mesh] 4. Remove Granular Constraints: For highly specific intersections, drop the weakest constraint first (e.g., expand date range to 2 years, or drop "liver" and filter broader results manually). 5. Avoid Over-Quoting: Double quotes force **exact phrase matching**, with quoted words contiguous in that exact order. E.g., "dopaminergic neurons" excludes papers with "dopaminergic projection neurons", "dopamine neurons", "DA neurons", or with "dopaminergic" and "neurons" in separate sentences. Only quote multi-word terms where word order matters (anatomical regions, compound names). Use unquoted terms or proximity search ([tiab:~N]) for conceptual matching. 6. Finding Primary Data: If you need raw identifiers (Sequence IDs, Chemical CIDs), append data-source terms to your query, e.g. AND (accession[tiab] OR "GenBank"[tiab] OR "supplementary"[tiab])`. This filters out review articles that discuss concepts but omit the raw data.

For advanced search tags and strategies refer to

• PubMed Advanced Search Reference.
• https://pubmed.ncbi.nlm.nih.gov/help/

uv run scripts/pubmed_api.py ./search_results.json search_pubmed "BRCA1 cancer" --max_results 5 --sort_by relevance

Arguments:

• query (str, required) – free-text or structured NCBI query
• max_results (int, default 10) – maximum PMIDs to return
• sort_by (str, default "relevance") – relevance, pub_date, Author,

JournalName, or Title

Output: ["35113657", "31234568"]

Filtering tips:

Prefer restrictors in initial queries to reduce noise. If a restricted query returns 0 results, see Troubleshooting above.

• Publication type: append AND "systematic review"[pt] or `AND

"meta-analysis"[pt] or AND "clinical trial"[pt]`

• Date range: append AND 2023/01:2023/12[dp]
• Title/abstract only: use [tiab] tag, e.g. "CRISPR off-target"[tiab]
• Exclude noise: append NOT "comment"[pt] NOT "editorial"[pt] if getting too

many non-original research results.

--------------------------------------------------------------------------------

2. global_database_discovery — Count hits across all NCBI databases

Reports how many records match a query across every NCBI database at once. Useful for deciding which databases are worth querying for a given topic.

uv run scripts/pubmed_api.py ./crispr_counts.json global_database_discovery "CRISPR"

Arguments:

• query (str, required) – free-text query

Output: dict[str, int] — keys are NCBI database names (e.g. pubmed, pmc, gene), values are hit counts. Only databases with ≥1 hit are included. Example: json {"pubmed": 14500, "pmc": 4200, "gene": 12, "protein": 105}

Utilities

verify_medical_spelling — Spell-check biomedical terms

Suggests spelling corrections for biomedical terms using NCBI's dictionary. Useful for normalizing user-provided terminology before searching.

python3 scripts/pubmed_api.py ./spelling.json verify_medical_spelling "rhuematoid arthritus"

Arguments:

• term (str, required) – term to spell-check

Output: json {"original": "rhuematoid arthritus", "corrected": "rheumatoid arthritis"}

Returns the original term unchanged if the spelling is already correct.

--------------------------------------------------------------------------------

match_raw_citations — Resolve messy citations to PMIDs

Resolves incomplete or messy bibliographic citations to PMIDs via the ecitmatch endpoint. Each citation must be a pipe-delimited string in the format journal|year|volume|first_page|author_name|key|. Empty fields are valid. The trailing pipe is required.

For field selection strategies, journal name pitfalls, and fallback chains, refer to Citation Matching Guide.

uv run scripts/pubmed_api.py ./nature2006_pmids.json match_raw_citations "nature|2006||||takahashi k|key0|"

Arguments:

• citation_strings (list[str], required) – comma-separated pipe-delimited

citations

Output: ["16904174"]