paper-lookup

Paper Lookup

This skill gives you 10 academic literature APIs with documented endpoints. Your job is to turn the user's intent into a reproducible retrieval: pick the authoritative database(s), make bounded and rate-limited calls, and return an answer with enough provenance (endpoints, parameters, identifiers, access date) that a human or another agent can repeat it.

A literature lookup is only as trustworthy as it is repeatable. Prefer explicit identifiers and documented endpoints over broad guessing, report what you queried, and say plainly when a result is partial or a database came back empty — a silent gap reads as "nothing exists" when it may just mean "not indexed here."

Core Workflow

Database Selection Guide

Match the user's intent to the right database(s).

By Use Case

Cross-Database Queries

A note on keyword search for preprints: bioRxiv and medRxiv have no keyword search — only date-range browsing and DOI lookup. To find bioRxiv/medRxiv preprints by topic, search Semantic Scholar or OpenAlex (both index preprints) and filter, then use the bioRxiv/medRxiv API for preprint-specific metadata like the published-version link.

When a query genuinely spans multiple needs (e.g., "find papers on CRISPR and get me the PDFs"), query the relevant databases and reconcile — find candidates in one, resolve open access per-DOI in another.

Common Identifier Formats

Different databases use different identifier systems. When a lookup fails, a wrong identifier format is the most common cause — check here first.

Cross-referencing IDs: Semantic Scholar accepts DOI, PMID, PMCID, and arXiv ID via prefixes (DOI:10.1038/nature12373, PMID:34567890, ARXIV:2103.15348). OpenAlex accepts DOI and PMID via prefixes (doi:10.1038/..., pmid:34567890). Use the PMC ID Converter to translate between PMID, PMCID, and DOI. When one database has no result for an identifier, converting it and trying another is usually faster than reformulating the query.

API Keys and Access

Most of these APIs are fully open. A few benefit from a key for higher rate limits, and two need one for their best features.

Fully open (no key): bioRxiv/medRxiv (no documented limits), arXiv (1 req / 3 s), Crossref (add mailto for the 2× "polite pool"), Unpaywall (requires a real email parameter).

Loading keys: Check the environment first ($NCBI_API_KEY, etc.), then a .env in the working directory. If a key is missing, proceed at the lower rate limit and tell the user which key would help and where to get it — don't stall.

Making API Calls

Use your environment's HTTP fetch tool to call REST endpoints. The tool name varies by platform:

Use curl (not a fetch tool) when the call needs any of these — several databases here do:

Example with a header and JSON accept:

curl -s -H "Accept: application/json" -H "x-api-key: $S2_API_KEY" \
  "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1038/nature12373?fields=title,year,citationCount,tldr"

Request guidelines

For a targeted lookup, still record the endpoint, parameters, and access date so the single result can be repeated.

Output Format

Lead with the answer, then give the provenance. Structure it like this:

## Retrieval Summary
- Query: <what the user asked>
- Scope: targeted lookup | exhaustive retrieval
- Databases queried: PubMed (esearch+esummary), Unpaywall (DOI lookup)
- Access date: <date>

## Results
### PubMed
<the papers: title, authors, year, journal, DOI/PMID — the fields the user needs>

### Unpaywall
<OA status and best PDF link>

## Provenance
- Endpoints & parameters: <enough to repeat the call>
- Identifier conversions: <if any>
- Count reconciliation: <expected vs. retrieved, for exhaustive searches>
- Warnings: <empty results, partial pagination, missing keys, stale endpoints>

Default to a readable summary of the fields that matter, not a raw JSON dump. Raw JSON is fine when the user explicitly asks for it or the payload is small — quote only the relevant slice and label it as untrusted third-party data. For large full-text pulls (PMC/CORE), save the payload to a local file and report the path rather than flooding the response.

Adding New Databases

This skill is designed to grow. Each database is a self-contained file in references/. To add one: create references/<name>.md following the format of the existing files (base URL, auth, key endpoints with parameter tables, example calls, response shape, pagination/count behavior, rate limits, identifier conventions, and any known hazards), then add a row to the selection guide and the Available Databases tables below.

Available Databases

Read the relevant reference file before making any API call.

Biomedical Literature

Preprint Servers

Multidisciplinary Indexes

Open Access & Full Text