/search-lit

name: search-lit
description: Use when finding papers or building a reference list. Searches PubMed, Semantic Scholar and bioRxiv/medRxiv, includes only references verified through an API, and generates BibTeX. Auditing an existing reference list is /verify-refs.
metadata:
  triggers: "literature search, find papers, citation, references, bibliography, PubMed search, related work"

Literature Search Skill

Every reference you produce must come from a live database result — never generate a citation from memory alone, because a recalled citation can look real and not exist.

Search Tools: MCP (Primary) + E-utilities (Fallback)

Primary: MCP Tools (Claude.ai Remote)

| Database | MCP Tool | Purpose | |----------|----------|---------| | PubMed | `mcp__claude_ai_PubMed__search_articles` | Search by query, MeSH terms | | PubMed | `mcp__claude_ai_PubMed__get_article_metadata` | Full metadata for a PMID | | PubMed | `mcp__claude_ai_PubMed__find_related_articles` | Related articles for a PMID | | PubMed | `mcp__claude_ai_PubMed__lookup_article_by_citation` | Verify a citation | | PubMed | `mcp__claude_ai_PubMed__convert_article_ids` | Convert between PMID/DOI/PMCID | | Semantic Scholar | `mcp__claude_ai_Scholar_Gateway__semanticSearch` | Semantic search across all fields | | bioRxiv/medRxiv | `mcp__claude_ai_bioRxiv__search_preprints` | Search preprint servers | | bioRxiv/medRxiv | `mcp__claude_ai_bioRxiv__get_preprint` | Full preprint metadata | | CrossRef | WebFetch with `https://api.crossref.org/works/{DOI}` | DOI verification |

Fallback: NCBI E-utilities (Direct API via Bash)

If any `mcp__claude_ai_PubMed__*` call returns an error containing "terminated", "not found", "not available", or "not connected", switch ALL subsequent PubMed calls in this session to the bundled E-utilities scripts. Do not retry MCP after a disconnect — it will not recover within the same conversation.

EUTILS="${CLAUDE_SKILL_DIR}/references/pubmed_eutils.sh"
PARSER="${CLAUDE_SKILL_DIR}/references/parse_pubmed.py"

# Search PubMed (returns PMIDs)
bash "$EUTILS" search "diagnostic test accuracy meta-analysis radiology" 20 \
  | python3 "$PARSER" esearch

# Get article summaries as markdown table
bash "$EUTILS" fetch_json "16168343,16085191,31462531" \
  | python3 "$PARSER" esummary

# Get detailed metadata
bash "$EUTILS" fetch "16168343" \
  | python3 "$PARSER" efetch

# Generate BibTeX entries
bash "$EUTILS" fetch "16168343,16085191" \
  | python3 "$PARSER" bibtex

# Verify a citation by exact title
bash "$EUTILS" cite_lookup "Bivariate analysis of sensitivity and specificity" \
  | python3 "$PARSER" esearch

# Find related articles for a PMID
bash "$EUTILS" related "16168343" 10 \
  | python3 "$PARSER" esummary

The script sleeps 350 ms between calls (NCBI allows 3 requests/s without an API key, 10/s with `NCBI_API_KEY`); keep batch calls sequential.

| MCP Tool | E-utilities Command | Parser Mode | |----------|-------------------|-------------| | `search_articles` | `search <query> [retmax]` | `esearch` | | `get_article_metadata` | `fetch <pmids>` | `efetch` or `bibtex` | | `find_related_articles` | `related <pmid> [retmax]` | `esummary` | | `lookup_article_by_citation` | `cite_lookup <title>` | `esearch` → `fetch` | | `convert_article_ids` | Not available (use CrossRef DOI lookup) | — |

---

Workflow

Phase 1: Search Strategy

1. Get the research topic, question, or manuscript section that needs references. 2. Build the query from the key concepts (Population, Intervention/Exposure, Comparison, Outcome), with MeSH terms for PubMed: `(concept1 OR synonym1) AND (concept2 OR synonym2)`. 3. Set scope: date range (default: last 10 years unless the user specifies), article types, and language (default: English). 4. Present the Boolean query, databases, and filters to the user.

**Gate:** Wait for user approval before running searches.

Phase 2: Execute Search

1. Search PubMed (`search_articles`, Boolean query), Semantic Scholar (`semanticSearch`, natural language query), and bioRxiv/medRxiv (`search_preprints`) when preprints are relevant. 2. Deduplicate across databases by DOI or title similarity. 3. Present the results in this table, and write the same rows to `references/search_results.tsv`:

| # | Title | Authors (first + last) | Year | Journal | PMID/DOI | Relevance |
|---|-------|----------------------|------|---------|----------|-----------|
| 1 | ...   | Kim J, ... Lee S     | 2024 | Radiology | 12345678 | High      |

4. Ask the user to select which papers to include.

Record what the source said existed, not only what you downloaded

A wrong haul raises no error, and a PRISMA flow built on a wrong number is fiction that nothing downstream contradicts. Check both of these:

• **A count that equals a page cap exactly.** Every source reports a total:

`esearchresult.count`, `opensearch:totalResults`, `meta.count`. **Record `api_total` beside `downloaded`, and fail loudly when `downloaded < api_total`, or when `downloaded` equals a page or loop cap exactly** (e.g. a loop's own `if start >= 2000: break` reporting 2,000 records). Print `TRUNCATED` and refuse to write the search record.

• **A boolean that was never applied.** OpenAlex's `search=` is a relevance-ranked free-text

parameter that **silently ignores AND/OR**; `filter=title_and_abstract.search:` honours them. Run the query once more with one mandatory clause negated. **If the hit count does not drop, the boolean is being ignored** — the engine is ranking, not filtering.

PubMed via E-utilities is the one place where the naive pattern is safe. Everywhere else, do both.

A DOI in a screening row is not necessarily that row's DOI

When the pipeline **filled** a `doi` column (matched against Crossref by title similarity) rather than receiving it with the record, a wrong match is a valid, resolvable DOI for a different paper. Resolve it and read the title back before any deci