PubMed API

Prerequisites

uv
: Read the
```
uv
```
skill and follow its Setup instructions to ensure
```
uv
```
is installed and on PATH.
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.
.env
file: Make sure the
```
.env
```
file exists in your home directory. Create one if it does not exist.
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/
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:

bash

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

bash

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

bash

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

bash

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):

bash

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

Slim abstracts to essential fields and truncate long abstracts:

bash

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

Filter by keyword (null-safe):

bash

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

Context Management & Accuracy

When processing larger result sets (>10 abstracts):

Filter Early: Use
```
jq
```
to verify keywords in abstracts before reading the full JSON into context.
Slimming: Extract only
```
title
```
and
```
abstract
```
fields unless explicitly instructed otherwise. Author lists and metadata contribute to noise.
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.
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.
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

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.

pubmed-database

NPX Install

Tags

SKILL.md Content

PubMed API

Prerequisites

Core Rules

Structure of the skill folder

CLI Usage

Example Usage

Essential Recipes

Context Management & Accuracy

Functions

Search

Fetch & Resolve

Cross-Database Linking

Bulk Workflows

Utilities