Searching Scientific Literature
RC native tools — this skill's pipeline ships as four built-in RC tools. Call them directly; do not shell out to any rp.py script or write curl:
rp_search({ query, limit?, min_year? }) — Scopus relevance search enriched with OpenAlex abstracts + OA PDF links. The Elsevier key is built in.rp_abstracts({ dois }) — batch abstracts + OA links for a DOI list (OpenAlex, no key).rp_cite({ doi, direction?, limit? }) — citation traversal (direction: both / backward / forward).rp_fulltext({ doi, out? }) — OA full text (Elsevier ScienceDirect OA → OpenAlex OA fallback); pass out to also save the text to a file.
Results return inline as JSON (there is no --json <file> flag). To persist a result set, save the returned JSON with the workspace file tools.
Overview
Discovery runs on one backbone: Scopus (relevance-ranked, all-publisher coverage,
real citation counts), with OpenAlex layered on only to supply the data Scopus's
personal-key tier withholds (abstracts, OA full-text links). Both are driven by the
the rp_* tools tool — you do not hand-write curl.
Core principle: Scopus decides what and in what order; OpenAlex fills in abstracts.
Key entitlement reality (tested): a personal Scopus API key exposes the STANDARD
search view only — title, DOI, EID, citation count, year, OA flag. It does not
return abstracts, references, or forward citations. That is why abstracts come from
OpenAlex and citation traversal lives in traversing-citations (also OpenAlex). Do
not try to pull abstracts/refs from Scopus; the calls 403.
How to Search
1. Build the Scopus query
Scopus query syntax (richer than plain keywords — use it):
TITLE-ABS-KEY( ... ) — search title, abstract, keywords (the default workhorse)AND / OR / AND NOT — booleanW/n — proximity (e.g. BTK W/3 selectivity)PUBYEAR > 2018 — date constraintDOCTYPE(ar) — article type (ar=article, re=review)
Examples:
TITLE-ABS-KEY(("BTK" OR "Bruton tyrosine kinase") AND inhibitor AND (selectivity OR "off-target"))
TITLE-ABS-KEY("CRISPR" AND cardiomyocyte) AND PUBYEAR > 2019
2. Run the search
rp_search "TITLE-ABS-KEY(BTK inhibitor selectivity)" \
--limit 50 --min-year 2015
This single command:
- Pages Scopus by relevancy (citation counts included).
- Batch-fetches OpenAlex by DOI (50/call) to attach
abstract, oa_status, oa_pdf_url.
- Writes candidate records ready for scoring.
Each record:
{
"scopus_id": "85...", "eid": "2-s2.0-85...", "doi": "10.1016/...",
"title": "...", "year": "2023", "cited_by": 42, "oa": true,
"source": "Journal of Medicinal Chemistry",
"abstract": "We report ...", "openalex_id": "W...",
"oa_status": "gold", "oa_pdf_url": "https://..."
}
3. Report
Announce: 🔎 Scopus: N papers · M with abstracts (OpenAlex).
Then hand the candidate list to evaluating-paper-relevance for scoring.
Coverage Notes (honest limits)
- Abstract gaps: OpenAlex lacks abstracts for some closed papers (notably parts of
Elsevier/ACS). Expect roughly 50–80% abstract coverage. Papers with
"abstract": ""
must be scored from title + journal + citation count only, or deferred — never
silently dropped. Flag them: ⚠️ No abstract (score from title).
- Scopus quota: 20,000 search results/week on the personal key. The pipeline paginates
25/call, so a 50-result search costs 2 calls. Budget accordingly for large sweeps.
- No Scopus abstracts/refs/fulltext-search on this key — by design, see above.
Quick Reference
| Task |
Command |
| Search + enrich |
rp_search "<scopus query>" --limit N |
| Narrow |
add AND, PUBYEAR > Y, DOCTYPE(ar), more specific TITLE-ABS-KEY |
| Broaden |
use OR, drop constraints, add synonyms |
Common Mistakes
- Hand-writing curl to Scopus → use
the rp_* tools; it handles paging, rate limits, caching.
- Expecting abstracts from Scopus → they come from OpenAlex; some will be missing.
- Dropping abstract-less papers → score them from title/citations or defer, don't hide them.
- Ignoring the weekly quota → 20k Scopus results/week; don't burn it on over-broad sweeps.
Next Steps
After search: score with evaluating-paper-relevance; expand high scorers with
traversing-citations.
1---
2name: searching-literature
3description: Scopus relevance search (main) enriched with OpenAlex abstracts and OA links, via the rp_* tools pipeline
4when_to_use: When starting literature search. When user asks about papers, publications, studies. When building the initial candidate list for a research question.
5version: 2.0.0
6---
7
8# Searching Scientific Literature
9
10> **RC native tools** — this skill's pipeline ships as four built-in RC tools. Call them directly; do **not** shell out to any `rp.py` script or write curl:
11> - `rp_search({ query, limit?, min_year? })` — Scopus relevance search enriched with OpenAlex abstracts + OA PDF links. The Elsevier key is built in.
12> - `rp_abstracts({ dois })` — batch abstracts + OA links for a DOI list (OpenAlex, no key).
13> - `rp_cite({ doi, direction?, limit? })` — citation traversal (`direction`: `both` / `backward` / `forward`).
14> - `rp_fulltext({ doi, out? })` — OA full text (Elsevier ScienceDirect OA → OpenAlex OA fallback); pass `out` to also save the text to a file.
15>
16> Results return inline as JSON (there is no `--json <file>` flag). To persist a result set, save the returned JSON with the workspace file tools.
17
18
19## Overview
20
21Discovery runs on **one backbone: Scopus** (relevance-ranked, all-publisher coverage,
22real citation counts), with **OpenAlex** layered on only to supply the data Scopus's
23personal-key tier withholds (abstracts, OA full-text links). Both are driven by the
24`the rp_* tools` tool — you do not hand-write curl.
25
26**Core principle:** Scopus decides *what* and *in what order*; OpenAlex fills in *abstracts*.
27
28> **Key entitlement reality (tested):** a personal Scopus API key exposes the STANDARD
29> search view only — title, DOI, EID, citation count, year, OA flag. It does **not**
30> return abstracts, references, or forward citations. That is why abstracts come from
31> OpenAlex and citation traversal lives in `traversing-citations` (also OpenAlex). Do
32> not try to pull abstracts/refs from Scopus; the calls 403.
33
34## How to Search
35
36### 1. Build the Scopus query
37
38Scopus query syntax (richer than plain keywords — use it):
39
40- `TITLE-ABS-KEY( ... )` — search title, abstract, keywords (the default workhorse)
41- `AND` / `OR` / `AND NOT` — boolean
42- `W/n` — proximity (e.g. `BTK W/3 selectivity`)
43- `PUBYEAR > 2018` — date constraint
44- `DOCTYPE(ar)` — article type (ar=article, re=review)
45
46Examples:
47```
48TITLE-ABS-KEY(("BTK" OR "Bruton tyrosine kinase") AND inhibitor AND (selectivity OR "off-target"))
49TITLE-ABS-KEY("CRISPR" AND cardiomyocyte) AND PUBYEAR > 2019
50```
51
52### 2. Run the search
53
54```bash
55rp_search "TITLE-ABS-KEY(BTK inhibitor selectivity)" \
56 --limit 50 --min-year 2015
57```
58
59This single command:
601. Pages Scopus by relevancy (citation counts included).
612. Batch-fetches OpenAlex by DOI (50/call) to attach `abstract`, `oa_status`, `oa_pdf_url`.
623. Writes candidate records ready for scoring.
63
64Each record:
65```json
66{
67 "scopus_id": "85...", "eid": "2-s2.0-85...", "doi": "10.1016/...",
68 "title": "...", "year": "2023", "cited_by": 42, "oa": true,
69 "source": "Journal of Medicinal Chemistry",
70 "abstract": "We report ...", "openalex_id": "W...",
71 "oa_status": "gold", "oa_pdf_url": "https://..."
72}
73```
74
75### 3. Report
76
77Announce: `🔎 Scopus: N papers · M with abstracts (OpenAlex)`.
78Then hand the candidate list to `evaluating-paper-relevance` for scoring.
79
80## Coverage Notes (honest limits)
81
82- **Abstract gaps:** OpenAlex lacks abstracts for some closed papers (notably parts of
83 Elsevier/ACS). Expect roughly 50–80% abstract coverage. Papers with `"abstract": ""`
84 must be scored from **title + journal + citation count** only, or deferred — never
85 silently dropped. Flag them: `⚠️ No abstract (score from title)`.
86- **Scopus quota:** 20,000 search results/week on the personal key. The pipeline paginates
87 25/call, so a 50-result search costs 2 calls. Budget accordingly for large sweeps.
88- **No Scopus abstracts/refs/fulltext-search** on this key — by design, see above.
89
90## Quick Reference
91
92| Task | Command |
93|------|---------|
94| Search + enrich | `rp_search "<scopus query>" --limit N` |
95| Narrow | add `AND`, `PUBYEAR > Y`, `DOCTYPE(ar)`, more specific `TITLE-ABS-KEY` |
96| Broaden | use `OR`, drop constraints, add synonyms |
97
98## Common Mistakes
99
100- **Hand-writing curl to Scopus** → use `the rp_* tools`; it handles paging, rate limits, caching.
101- **Expecting abstracts from Scopus** → they come from OpenAlex; some will be missing.
102- **Dropping abstract-less papers** → score them from title/citations or defer, don't hide them.
103- **Ignoring the weekly quota** → 20k Scopus results/week; don't burn it on over-broad sweeps.
104
105## Next Steps
106
107After search: score with `evaluating-paper-relevance`; expand high scorers with
108`traversing-citations`.
wentorai