search-lit

Files (28)

• SKILL.md
• embase_browser.md · references/
• parse_pubmed.py · references/
• pubmed_eutils.sh · references/
• snowball.py · references/
• snowball.bib · references/snowball_challenge/expected/
• DOI_10_0_seed1.backward.json · references/snowball_challenge/fixture/
• DOI_10_0_seed1.forward.json · references/snowball_challenge/fixture/
• DOI_10_0_seed1.similar.json · references/snowball_challenge/fixture/
• DOI_10_0_seed_err.backward.json · references/snowball_challenge/fixture/
• DOI_10_0_seed_trunc.forward.json · references/snowball_challenge/fixture/
• library.bib · references/snowball_challenge/fixture/
• problem.md · references/snowball_challenge/
• verify.sh · references/snowball_challenge/
• check_doi_record_match.py · scripts/
• 10.1000%2Farticle.008.json · scripts/check_doi_record_match_challenge/fixture/cache/
• 10.1000%2Ferratum.007.json · scripts/check_doi_record_match_challenge/fixture/cache/
• 10.1000%2Fmarkup.005.json · scripts/check_doi_record_match_challenge/fixture/cache/
• 10.1000%2Fmatch.001.json · scripts/check_doi_record_match_challenge/fixture/cache/
• 10.1000%2Fother.002.json · scripts/check_doi_record_match_challenge/fixture/cache/
• 10.1000%2Fsuppl.003.json · scripts/check_doi_record_match_challenge/fixture/cache/
• 10.1000%2Fversion.009.json · scripts/check_doi_record_match_challenge/fixture/cache/
• screening.tsv · scripts/check_doi_record_match_challenge/fixture/
• update_notice.tsv · scripts/check_doi_record_match_challenge/fixture/
• verify.sh · scripts/check_doi_record_match_challenge/
• skill.yml
• test_parse_pubmed.sh · tests/
• test_pubmed_eutils.sh · tests/

SKILL.md (first lines)

# 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.

```bash
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.

From Aperivue/medsci-skills, MIT.

More from Aperivue/medsci-skills