Semantic Scholar Search Workflow

Search academic papers via the Semantic Scholar API using a structured 4-phase workflow.

Critical rule: NEVER make multiple sequential Bash calls for API requests. Always write ONE Python script that runs all searches, then execute it once. All rate limiting is handled inside s2.py automatically.

Phase 1: Understand & Plan

Parse the user's intent and choose a search strategy:

Decision Tree

User wants...	Strategy	Function
Broad topic exploration	Relevance search	INLINECODE1
Precise technical terms, exact phrases

Bulk search with boolean operators | search_bulk() with build_bool_query() | | Specific passages or methods | Snippet search | search_snippets() | | Known paper by title | Title match | match_title() | | Known paper by DOI/PMID/ArXiv | Direct lookup | get_paper() | | Papers citing a known work | Citation traversal | get_citations() | | Related to one paper | Single-seed recommendations | find_similar() | | Related to multiple papers | Multi-seed recommendations | recommend() | | Find a researcher | Author search | search_authors() | | Researcher's profile | Author details | get_author() | | Researcher's publications | Author papers | get_author_papers() |

Query Construction Rules

• - Ambiguous terms (e.g., "stem cells" could mean mesenchymal or stem-like T cells): Use build_bool_query() with exact phrases and exclusions

- Example: build_bool_query(phrases=["stem-like T cells"], required=["CD4", "TCF7"], excluded=["mesenchymal", "hematopoietic stem cell"])

• - Multi-context queries (e.g., "topic X in cancer AND autoimmunity"): Plan separate searches, deduplicate with INLINECODE15
• Broad topics: Use search_relevance() with filters (year, venue, fieldsOfStudy, minCitationCount)

Plan Filters

Filter	Use when
INLINECODE17	Recent work only
INLINECODE18

Precise date range (YYYY-MM-DD) | | fields_of_study="Medicine" | Restrict to domain | | min_citations=10 | Only established papers | | pub_types="Review" | Find reviews/meta-analyses | | pub_types="ClinicalTrial" | Clinical trials only | | open_access=True | Only open access papers |

Checkpoint: Before proceeding, verify: (1) search strategy matches user intent, (2) filters are appropriate, (3) query is specific enough to avoid irrelevant results.

Phase 2: Execute Search

Write ONE Python script. Example:

CODEBLOCK0

Execute with: INLINECODE24

Rules:

• - Import everything from s2: INLINECODE25
• Write script to /tmp/s2_search.py (or similar temp path)
• One Bash call to execute. Never chain multiple API calls via separate Bash invocations.
• Rate limiting, retries, and backoff are automatic inside s2.py

Checkpoint: Verify the script ran successfully (no exceptions) and returned results. If 0 results, broaden the query or relax filters before presenting.

Worked Examples

Example 1: Author workflow — "Find papers by Yann LeCun on self-supervised learning"

CODEBLOCK1

Example 2: Citation chain — "Who cited the Transformer paper and what did they build on?"

CODEBLOCK2

Example 3: Multi-seed recommendations with BibTeX export — "Find papers like these two but not about NLP"

CODEBLOCK3

Phase 3: Summarize & Present

• - Use format_results() for consistent output (summary table + top-10 details)
• If user's language is Chinese, present summaries in Chinese
• Always note total results count and search strategy used
• Highlight most relevant papers based on the user's specific question

Phase 4: User Interaction Loop

After presenting results, always offer these options:

1. 1. Translate — titles/summaries to Chinese (or other language)
2. Details — full abstract for specific paper numbers
3. Refine — narrow or expand search with different terms/filters
4. Similar — find papers similar to a specific result (find_similar())
5. Citations — who cited a specific paper (get_citations())
6. Export — save results via export_bibtex(), export_markdown(), or INLINECODE32
7. Done — end search session

Loop until user says done. Each follow-up uses the same single-script pattern.

---

API Quick Reference

Helper Module (s2.py)

CODEBLOCK4

Paper Search Functions

Function	Purpose	Max Results
INLINECODE34	Simple broad search	1,000
INLINECODE35

Boolean precise search | 10,000,000 | | search_snippets(query, **filters) | Full-text passage search | 1,000 | | match_title(title) | Exact title match | 1 | | get_paper(paper_id) | Single paper details | — | | get_citations(paper_id, max_results) | Who cited this | 10,000 | | get_references(paper_id, max_results) | What this cites | 10,000 | | find_similar(paper_id, limit, pool) | Single-seed recommendations | 500 | | recommend(positive_ids, negative_ids, limit) | Multi-seed recommendations | 500 | | batch_papers(ids, fields) | Batch lookup (≤500) | — |

Author Functions

Function	Purpose	Max Results
INLINECODE44	Find researchers by name	1,000
INLINECODE45

Author profile (affiliations, h-index) | — | | get_author_papers(author_id, max_results) | Author's publications | 10,000 | | get_paper_authors(paper_id, max_results) | Paper's author list | 1,000 | | batch_authors(ids, fields) | Batch author lookup (≤1000) | — |

Filter Parameters (kwargs)

INLINECODE49, publication_date, venue, fields_of_study, min_citations, pub_types, INLINECODE55

• - year: "2020-", "-2019", INLINECODE59
• INLINECODE60: "2024-01-01:2024-06-30" (YYYY-MM-DD range, open-ended OK)
• INLINECODE62: Review, JournalArticle, Conference, ClinicalTrial, MetaAnalysis, Dataset, Book, CaseReport, Editorial, LettersAndComments, News, Study, INLINECODE75

Boolean Query Syntax (bulk search only)

Syntax	Example	Meaning
INLINECODE76	INLINECODE77	Exact phrase
INLINECODE78

+transformer | Must include | | - | -survey | Exclude | | \| | CNN \| RNN | OR | | * | neuro* | Prefix wildcard | | () | (CNN \| RNN) +attention | Grouping |

Use build_bool_query(phrases, required, excluded, or_terms) to construct safely.

Output Functions

Function	Purpose
INLINECODE89	Markdown summary table
INLINECODE90

Detailed entries with TLDR/abstract | | format_results(papers, query_desc) | Combined: summary + table + details | | format_authors(authors, max_rows=20) | Author table (name, affiliations, h-index) | | export_bibtex(papers) | BibTeX entries (requires citationStyles field) | | export_markdown(papers, query_desc) | Full markdown report saved to file | | export_json(papers, path) | JSON export saved to file | | deduplicate(papers) | Remove duplicates by paperId |

Supported ID Formats

INLINECODE98, ARXIV:2106.15928, PMID:19872477, PMCID:PMC2323569, CorpusId:215416146, ACL:2020.acl-main.447, DBLP:conf/acl/..., MAG:3015453090, INLINECODE106

Paper Fields

Default: INLINECODE107

Additional: abstract, references, citations, openAccessPdf, publicationDate, publicationVenue, fieldsOfStudy, s2FieldsOfStudy, journal, isOpenAccess, referenceCount, influentialCitationCount, citationStyles, embedding, INLINECODE122

Author fields: name, affiliations, paperCount, citationCount, hIndex, homepage, externalIds, INLINECODE130

Rate Limiting

Handled automatically by s2.py: 1.1s gap between requests, exponential backoff (2s→4s→8s→16s→32s, max 60s) on 429/504 errors, up to 5 retries.

Troubleshooting

Error	Cause	Fix
INLINECODE132	Missing or invalid API key	Verify S2_API_KEY is set: INLINECODE134
INLINECODE135 after 5 retries

Sustained rate limit exceeded | Wait 60s, reduce max_results, or split into smaller batches | | ModuleNotFoundError: s2 | Skill directory not on path | Verify skill is installed at ~/.claude/skills/ or ~/.openclaw/skills/ | | ModuleNotFoundError: requests | requests not installed | pip install requests or uv pip install requests | | 0 results returned | Query too specific or filters too narrow | Broaden query, remove filters, try search_relevance() instead of search_bulk() | | KeyError: 'data' | Endpoint returned error object | Check r.get("message") for API error details | | tldr field is empty | Not all papers have TLDR | Fall back to abstract field; bulk search never returns tldr |