Allows searching and retrieving paper details using arXiv IDs.
Allows resolving papers by DOI and retrieving metadata.
Generates citations in IEEE format.
Provides PubMed IDs in paper metadata for cross-referencing.
Primary service for advanced paper search, citation graph exploration, recommendations, and metadata retrieval.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Research Buddy MCP Server find recent papers on LLM hallucinations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A powerful literature review assistant for AI agents, powered by the Semantic Scholar Graph API. Gives your AI agent the ability to search, explore, and cite academic papers through 15 specialized tools.
Advanced Search: Find papers by keyword with filters for discipline, venue, document type, citation count, date range, and open access availability. Includes pagination.
Bulk Search: Boolean query syntax (+"LLM" +hallucination -survey) with sorting by citation count or recency, and token-based pagination through up to 10 million results.
Full-Text Snippet Search: Search inside paper content, not just metadata. Returns ~500-word excerpts with section labels (Introduction, Methods, etc.).
Title Matching: Resolve plain-text references like "Attention Is All You Need" to a paper ID with a confidence score.
Smart Recommendations: AI-driven paper discovery using multiple seed papers and negative examples to steer results.
Rich Paper Details: Full metadata including external IDs (DOI, arXiv, PubMed), fields of study, publication venue, open access status, and more.
Citation Graph with Context: Explore who cited a paper and what it references, with the actual citation sentence, intent classification (methodology, background, result comparison), and influence scoring.
Author Discovery: Search for authors by name, view h-index, paper count, citation count, affiliations, and publication list.
Multi-Format Citations: Generate citations in APA, MLA, Chicago, IEEE, and BibTeX formats.
Citation Intersection: Find papers that appear in the citation graph of multiple papers, revealing bridging work between research threads.
PDF Extraction: Extract plain text from Open Access PDFs for immediate reading.
Batch Processing: Efficiently fetch metadata for multiple papers at once.
Related MCP server: PapersFlow
pip install git+https://github.com/Usama1002/research-buddy-mcp.gitgit clone https://github.com/Usama1002/research-buddy-mcp.git
cd research-buddy-mcp
pip install -e .Create a .env file or set the environment variable:
SEMANTIC_SCHOLAR_API_KEY=your_api_key_hereThe server works without an API key but with lower rate limits. Get a free key at semanticscholar.org/product/api.
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"research-buddy": {
"command": "research-buddy-mcp",
"env": {
"SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
}
}
}
}Add this to your .claude/settings.json or project's .mcp.json:
{
"mcpServers": {
"research-buddy": {
"command": "research-buddy-mcp",
"env": {
"SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
}
}
}
}Add the following to ~/.gemini/antigravity/mcp_config.json:
{
"mcpServers": {
"research-buddy": {
"command": "research-buddy-mcp",
"args": [],
"env": {
"SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
}
}
}
}Create a .vscode/mcp.json in your project root:
{
"servers": {
"research-buddy": {
"command": "research-buddy-mcp",
"env": {
"SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
}
}
}
}Alternatively, add it globally in your VS Code settings.json:
{
"mcp": {
"servers": {
"research-buddy": {
"command": "research-buddy-mcp",
"env": {
"SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
}
}
}
}
}VS Code's extension host runs in the Windows process space and cannot directly resolve WSL binaries. You must explicitly delegate the command to WSL using the full path to the installed binary.
First, find the binary path inside WSL:
which research-buddy-mcp
# Example output: /home/<your-username>/.local/bin/research-buddy-mcpThen add the following to your VS Code settings.json (or .vscode/mcp.json):
{
"mcp": {
"servers": {
"research-buddy": {
"command": "wsl",
"args": [
"--",
"/home/<your-username>/.local/bin/research-buddy-mcp"
],
"env": {
"SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
}
}
}
}
}Replace /home/<your-username> with your actual WSL username.
Tool | Description |
| Search for papers by keyword with advanced filters: fields of study, publication type, venue, citation count, date range, open access, and pagination. |
| Boolean query search ( |
| Full-text search inside papers. Returns ~500-word text excerpts with the section where the match was found (e.g. Introduction, Methods). |
| Resolve a plain-text title (e.g. "Attention Is All You Need") to a paper ID with a confidence score. |
| Find researchers by name. Returns author profiles with h-index, paper count, citation count, and affiliations. |
Tool | Description |
| Full metadata for a paper: abstract, TLDR, external IDs (DOI, arXiv, PubMed), fields of study, publication venue, open access status, citation/reference counts, and more. Accepts Semantic Scholar IDs, DOIs ( |
| Retrieve details for multiple papers in a single request. |
| Download and extract plain text from an open-access PDF URL. |
Tool | Description |
| Papers that cited a given work, with citation context (the actual sentence), intent classification (methodology, background, result comparison), influence flag, and pagination. Filter to influential citations only. |
| Papers referenced by a given work, with the same context, intent, and influence data. |
| Find papers at the intersection of multiple citation graphs. Given 2+ papers, discover which papers cite all of them (or are referenced by all of them). |
Tool | Description |
| AI-driven recommendations from Semantic Scholar's recommendation engine. Accepts multiple seed papers and optional negative examples to steer results away from unwanted directions. |
Tool | Description |
| Author profile: name, affiliations, h-index, paper count, citation count, and publication list. |
Tool | Description |
| Ready-to-use BibTeX citation string. |
| Formatted citation in APA, MLA, Chicago, IEEE, or BibTeX style. |
1. bulk_search_papers('"large language model" +hallucination', sort='citationCount:desc')
2. Filter to top-cited results, then get_paper_details for each
3. get_references with influential_only=True to find foundational work
4. get_paper_citation for each in your preferred format1. match_paper_by_title('Attention Is All You Need') -> get paper ID
2. get_related_papers(paper_ids=[attention_id], negative_paper_ids=[bert_id])1. find_common_citations([paper_A_id, paper_B_id], direction='citations')
-> papers that cite BOTH A and B
2. find_common_citations([paper_A_id, paper_B_id], direction='references')
-> papers referenced BY BOTH A and B1. search_paper_snippets('chain-of-thought prompting improves reasoning on math')
-> returns exact text excerpts with section labelsspawn research-buddy-mcp ENOENT in VS CodeThis error means VS Code cannot find the research-buddy-mcp executable. This is common when using WSL on Windows, because VS Code's extension host runs in Windows and does not have access to WSL's PATH.
Fix: Use the WSL-specific configuration above, pointing to the full binary path returned by which research-buddy-mcp inside your WSL terminal.
Without an API key, requests share a global rate limit across all unauthenticated users. If you see 429 Too Many Requests errors, get a free API key and set it in your configuration. The server retries rate-limited requests automatically with exponential backoff.
MIT
Retrieve details for multiple papers at once.
paper_ids: List of paper IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| paper_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic retrieval action and does not disclose return format, pagination, error handling, rate limits, or whether partial results are possible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two lines, front-loaded with purpose. The bullet restating paper_ids is redundant with the schema, so not every sentence earns its place, but the description is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch retrieval tool with no annotations and no output schema, the description is too sparse. It omits batch limits, error behavior, and return structure that an agent would need to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description merely restates the parameter name as 'List of paper IDs', adding no format, constraints, or batch size limits beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'Retrieve' and resource 'details for multiple papers', with 'at once' indicating batch scope. It distinguishes itself from single-paper siblings like get_paper_details, but does not name alternatives explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when multiple paper IDs are available, but gives no explicit when-not or alternative routing (e.g., use get_paper_details for a single paper). No prerequisites or context about when batch retrieval is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comprehensive paper search with boolean queries, sorting, and pagination through up to 10 million results. Use for systematic literature reviews.
query: Boolean query string. Supports: + (AND), | (OR), - (NOT), "exact phrase",
(wildcard), ~N (fuzzy match), parentheses for grouping. Example: '+"large language model" +hallucination -survey'
limit: Results per page (default 100, max 1000).
sort: Sort order. Options: 'citationCount:desc', 'citationCount:asc', 'publicationDate:desc', 'publicationDate:asc', 'paperId' (for stable pagination).
year: Year or range (e.g. '2023' or '2020-2024').
fields_of_study: Comma-separated (e.g. 'Computer Science').
publication_types: Comma-separated (e.g. 'JournalArticle,Conference').
open_access_pdf: If True, only papers with a public PDF.
min_citation_count: Minimum citations.
venue: Comma-separated venue names.
publication_date_or_year: Date range (e.g. '2023-01-01:2024-06-30').
token: Continuation token from previous result for pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| year | No | ||
| limit | No | ||
| query | Yes | ||
| token | No | ||
| venue | No | ||
| fields_of_study | No | ||
| open_access_pdf | No | ||
| publication_types | No | ||
| min_citation_count | No | ||
| publication_date_or_year | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so reasonably: it discloses pagination via continuation token, the limit default/max, and the boolean query grammar. It omits auth requirements, rate limits, and what the returned records contain, but the core behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, followed by a compact bulleted parameter reference. It is somewhat long but nearly every line carries unique parameter semantics, so little is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no annotations and no output schema, the description covers all inputs and pagination mechanics well. It does not describe the shape of returned results, which is a minor gap since no output schema exists to cover it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage across 11 parameters, the description fully compensates: it defines the query syntax with an example, enumerates the exact sort options, documents year/date formats, comma-separated lists, and explains the token as a continuation token. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Comprehensive paper search') plus scope capabilities (boolean, sorting, pagination up to 10M results). It is clear, but does not differentiate from the sibling search_papers, leaving the agent to guess which search tool fits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Offers one usage context ('Use for systematic literature reviews'), which implies when to reach for it, but gives no explicit when-not guidance and never mentions the sibling search_papers or other alternatives. Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find papers that appear in the citation graph of ALL given papers. Reveals the 'intersection' of two or more research threads — papers that bridge multiple topics or are foundational to both.
paper_ids: List of 2+ paper IDs to intersect (e.g. ['id1', 'id2']).
direction: 'citations' to find papers that cite ALL given papers, 'references' to find papers referenced BY ALL given papers.
| Name | Required | Description | Default |
|---|---|---|---|
| direction | No | citations | |
| paper_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does explain the set-intersection behavior and the direction semantics. However, it omits return format, result limits, and error behavior for cases where fewer than two valid IDs are supplied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, followed by compact per-parameter notes. The middle sentence is slightly verbose but earns its place by clarifying the intersection use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description could say more about what a returned paper record looks like and how many results to expect. It conveys the core concept adequately but leaves return-structure gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it explains paper_ids as a list of 2+ IDs to intersect with an example, and enumerates the direction values ('citations' vs 'references') even though the schema declares no enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Find') and resource ('common citations') with clear scope ('in the citation graph of ALL given papers'), and its intersection semantics distinguish it from the single-paper siblings get_citations/get_references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied through the conceptual framing ('intersection of two or more research threads', 'bridges multiple topics'), but no explicit when-to-use conditions, prerequisites, or named alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get author profile and their papers.
author_id: Semantic Scholar Author ID.
| Name | Required | Description | Default |
|---|---|---|---|
| author_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it only names the return contents. It says nothing about pagination of the papers list, rate limits, auth requirements, or whether a missing author_id errors versus returns empty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short lines, purpose front-loaded, no wasted prose. The bulleted parameter line is slightly awkward formatting for a single-sentence description but costs nothing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A one-parameter lookup tool is simple enough that a short description can suffice, but with no annotations and no output schema the definition should still say what the profile contains and how the papers list behaves. As written it is adequate but thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (the property is bare 'type: string'), but the description compensates by specifying this is a 'Semantic Scholar Author ID', which is genuinely more informative than the schema alone. It does not, however, give an ID format or example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get author profile and their papers'), so the agent knows this retrieves an author record plus associated papers. However, it does not distinguish itself from the sibling search_authors, leaving the lookup-by-ID vs search-by-name split implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance and no mention of the sibling search_authors, which is the natural way to obtain an author_id in the first place. Usage is only inferable from the required parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve papers that cited the given paper, with citation context. Returns citation context (the sentence where the paper was cited), intent (methodology, background, result comparison), and whether it's influential.
paper_id: The paper ID.
limit: Max results (default 20).
offset: Pagination offset (default 0).
influential_only: If True, only return influential citations.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| paper_id | Yes | ||
| influential_only | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the returned content (citation sentence, intent categories, influential flag), which is useful behavioral context. However, it says nothing about side-effect-free read behavior, rate limits, or pagination semantics beyond the offset name, leaving gaps for an annotation-free tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose in the first sentence, then briefly describes the returned fields and parameter list. No filler or repetition, though the bullet list of parameters is somewhat mechanical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description appropriately describes the return payload, and all four parameters are covered despite 0% schema coverage. It is nearly complete for a read-only paginated retrieval tool, though it could mention error conditions or null behavior for invalid IDs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it documents all four parameters including paper_id, limit, offset, and the influential_only filter with its effect. It clarifies the boolean's meaning (only influential citations) and the pagination defaults, adding real value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Retrieve) and resource (papers that cited the given paper), and the direction of the citation relationship is unambiguous, distinguishing it from a references tool. It does not name a sibling explicitly, but the scope is clear enough for an agent to tell it apart from get_references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrasing 'papers that cited the given paper,' which contrasts with the inverse reference direction, but the description never states when to prefer this tool or names an alternative to route to. An agent can infer the context but gets no explicit guidance or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the BibTeX citation for a paper.
paper_id: The paper ID.
| Name | Required | Description | Default |
|---|---|---|---|
| paper_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden, but for a single-parameter read operation the burden is light. It names the return artifact (BibTeX citation), which is useful. It does not say how a missing or invalid paper_id is handled or whether the result is cached/formatted, so it stays at a minimum-viable level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short lines with the purpose front-loaded and the parameter listed compactly. There is no padding, though the parameter line is so terse it borders on contributing nothing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value detail is not required, and a one-parameter read tool is inherently simple. Still, given 13 siblings, the absence of any routing guidance or parameter sourcing leaves the definition adequate but with a clear gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only offers 'paper_id: The paper ID', which merely restates the parameter name. No format, example, or source for the ID (e.g., from search_papers results) is given, so it fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get the BibTeX citation for a paper.' An agent immediately knows the operation and artifact. It does not, however, differentiate itself from the sibling get_paper_citation, which likely sounds similar to a caller.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance at all. With siblings named get_paper_citation and get_paper_details in the list, the description should say when BibTeX is the right format to request versus those alternatives, but it offers nothing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a formatted citation for a paper in a specific style.
paper_id: The paper ID.
style: Citation style. Options: 'apa' (default), 'mla', 'chicago', 'ieee', 'bibtex'.
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | apa | |
| paper_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It doesn't state whether the citation is generated from stored metadata or requires external lookup, whether it's a read-only operation, or whether the output schema provides the full citation structure. The mention of default style 'apa' is a minor behavioral detail but insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: one sentence stating purpose, followed by a bulleted list of parameters. Every sentence is informative and there's no waste. The structure aids quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description needn't explain return values. However, it lacks usage guidance relative to siblings and behavioral context (e.g., read-only nature, source of citation data). For a 2-parameter tool with no annotations, this is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents both parameters: paper_id as 'The paper ID' and style with valid options ('apa', 'mla', 'chicago', 'ieee', 'bibtex') and the default 'apa'. This adds substantial value beyond the bare schema, though it doesn't clarify what format the paper ID should take.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: get a formatted citation for a paper. It clearly conveys the tool's function, but it does not distinguish itself from the closely named siblings get_citations and get_paper_bibtex, which likely overlap in purpose. That missing differentiation keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It doesn't mention get_citations (which might return raw citations) or get_paper_bibtex (which likely returns BibTeX), despite bibtex being listed as a style option here. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full metadata for a specific paper.
paper_id: Semantic Scholar ID, DOI, arXiv ID, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| paper_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses nothing about auth requirements, rate limits, error behavior for invalid IDs, or what 'full metadata' actually includes, which for an unannotated tool is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short lines, purpose front-loaded, with the identifier note as a supporting bullet. Nothing redundant, though the bullet could be folded into a single sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should ideally hint at what the returned metadata contains. It says 'full metadata' without enumerating fields, so it is minimally adequate for a single-param lookup but leaves the return shape entirely opaque.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the schema types paper_id only as a string, but the description explicitly enumerates accepted identifier forms (Semantic Scholar ID, DOI, arXiv ID). That is genuine meaning the schema does not convey, and it is the single most useful thing an agent needs to form a valid call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Get') and resource ('full metadata for a specific paper'), which an agent can distinguish from search_papers or match_paper_by_title by operation type. It stops short of explicitly naming an alternative, but the retrieval-by-identifier intent is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or when-not guidance. The description never states that this requires an already-known identifier or that batch_get_papers should be used for multiple IDs, leaving the agent to infer the selection context from sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve papers that this paper references, with citation context. Returns citation context (how the reference was used), intent (methodology, background, result comparison), and whether it's influential.
paper_id: The paper ID.
limit: Max results (default 20).
offset: Pagination offset (default 0).
influential_only: If True, only return influential references.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| paper_id | Yes | ||
| influential_only | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose the shape of the payload (citation context, intent categories, influential flag), which is genuinely useful since there is no output schema, but it says nothing about permissions, rate limits, failure modes, or what a sparse result means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first clause, followed by return-value detail and then a compact parameter list. The parameter list partially restates the schema, but since the schema has zero descriptions that repetition is earning its place rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description does the necessary work by explaining what comes back and how to control it. Remaining gaps are minor: no total-count or pagination-termination guidance, and no indication of what an empty reference list implies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it documents all four parameters including their defaults and the meaning of influential_only. It does not explain the expected format or provenance of paper_id, which is the one required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with an explicit direction: 'papers that this paper references,' which distinguishes it from the reverse-direction sibling get_citations. It does not, however, name or differentiate itself from get_citations, get_related_papers, or find_common_citations, so an agent must still infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use, when-not-to-use, or alternative-tool guidance. The closest sibling, get_citations (papers citing this one), is the exact inverse operation and is never mentioned, leaving the agent to guess between them from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the best-matching paper for a given title string. Useful for resolving plain-text references like 'Attention Is All You Need' to a Semantic Scholar paper ID. Returns the top match with a confidence score.
query: The paper title to match (e.g. 'Attention Is All You Need').
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the return shape well ('Returns the top match with a confidence score'), but says nothing about what happens when no confident match exists, matching tolerance, authentication, or rate limits. Adequate but incomplete for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded one-line purpose followed by a concrete example and a compact parameter bullet. Minor redundancy between 'for a given title string' and the query bullet, but nothing wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-annotation tool with no output schema, the description covers purpose, usage example, and the essential return value (top match + confidence). Missing only edge-case behavior (e.g., no-match handling), which keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it names the parameter and gives a concrete example value. It could add more on format constraints (whitespace, truncation, casing), but the meaning of the single parameter is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Find the best-matching paper for a given title string') and clarifies the resolution use case, which distinguishes it from title-agnostic siblings like search_papers. It does not explicitly name a sibling, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete usage context ('resolving plain-text references like Attention Is All You Need to a Semantic Scholar paper ID'), which tells the agent when this tool is appropriate. It stops short of naming alternatives (e.g., search_papers) or stating when-not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download and extract text from an open-access PDF.
url: Direct URL to the PDF.
max_chars: Max characters to extract (default 10000).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| max_chars | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose two real behavioral traits: the open-access access restriction and the max_chars truncation cap, which tells the agent output may be cut off. It does not say what happens on failure (non-open-access URL, unreachable host) or whether truncation is signaled, leaving meaningful gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One purpose sentence followed by two tight parameter bullets, with the core action front-loaded. No filler, though the parameter bullets are somewhat redundant with the schema field names.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-format explanation is unnecessary, and the description covers the essentials an agent needs: the open-access prerequisite, the URL requirement, and the truncation cap. Only the failure behavior for non-open-access URLs is left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it defines url as a direct PDF URL (not a DOI or landing page) and explains max_chars as a character cap with its default. That is meaningful clarification beyond the bare schema types, though it omits units/behavior at the boundary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific compound verb ('Download and extract text') with a clear resource ('an open-access PDF'), so the agent knows exactly what the tool produces. It is implicitly distinct from all siblings, which are search/metadata tools rather than full-text readers, but the description never names an alternative to sharpen that contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'open-access' qualifier implies a usage boundary (don't expect paywalled PDFs to work), which is useful implied guidance. However, there is no explicit when-to-use rule and no routing to siblings like get_paper_details for metadata or search_paper_snippets for quick excerpts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for authors by name.
query: Author name to search for (e.g. 'Yoshua Bengio').
limit: Number of results (default 10).
offset: Pagination offset (default 0).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden, and it discloses almost nothing behavioral: it does not state that this is a read-only lookup, how results are ranked or returned, whether matching is exact or fuzzy, or what happens when there are no matches. The presence of offset/limit implies pagination but the return format is never described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose statement followed by a compact parameter list; no filler sentences. The example for 'query' adds value at negligible length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter search with no output schema, documenting every parameter is close to sufficient, but the description is silent on result shape, ordering, and total-count behavior, which an agent needs to page correctly. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it names all three parameters with meaning, an example value for 'query', and defaults for limit (10) and offset (0). Only the shape/semantics of the result page remains unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Search for authors by name.' This clearly separates it from the paper-oriented siblings (search_papers, bulk_search_papers, get_paper_details). It does not, however, distinguish itself from get_author_details, which an agent could easily confuse with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, no exclusions, and never mentions get_author_details as the alternative for looking up a known author. The agent must infer that this is a discovery tool for when an author identifier is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for academic papers by query with advanced filters.
query: Keyword or natural language query.
limit: Number of results (default 10, max 100).
year: Year range (e.g. '2020-2024') or specific year.
fields_of_study: Comma-separated fields (e.g. 'Computer Science,Medicine'). Options: Computer Science, Medicine, Chemistry, Biology, Materials Science, Physics, Geology, Psychology, Art, History, Geography, Sociology, Business, Political Science, Economics, Philosophy, Mathematics, Engineering, Environmental Science, Agricultural and Food Sciences, Education, Law, Linguistics.
publication_types: Comma-separated types (e.g. 'JournalArticle,Conference'). Options: Review, JournalArticle, CaseReport, ClinicalTrial, Conference, Dataset, Editorial, LettersAndComments, MetaAnalysis, News, Study, Book, BookSection.
open_access_pdf: If True, only return papers with a public PDF.
min_citation_count: Minimum number of citations (e.g. 50).
venue: Comma-separated venue names or ISO4 abbreviations (e.g. 'Nature,Science').
publication_date_or_year: Date range in YYYY-MM-DD:YYYY-MM-DD format (e.g. '2023-01-01:2024-06-30').
offset: Pagination offset (default 0).
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| limit | No | ||
| query | Yes | ||
| venue | No | ||
| offset | No | ||
| fields_of_study | No | ||
| open_access_pdf | No | ||
| publication_types | No | ||
| min_citation_count | No | ||
| publication_date_or_year | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose concrete operating constraints (limit default 10 / max 100, offset default 0, open_access_pdf boolean semantics) which is useful, but it says nothing about result ordering, return payload shape, or rate/pagination behavior. A read-only search tool's safety profile is left implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The capability statement is front-loaded in one sentence, followed by a scannable parameter list where each line is terse and earns its place. The long enum enumerations add bulk but are genuinely needed given 0% schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with no annotations, no output schema, and no schema descriptions, the parameter surface is well covered, but the description never explains what a result contains or how results are ordered/ranked. The agent gets enough to invoke it, but not enough to interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and there are no enums in the schema, yet the description documents every one of the 10 parameters with format examples and expected syntax (year ranges, ISO4 venue abbreviations, date format YYYY-MM-DD:YYYY-MM-DD). It also enumerates the full allowed value sets for fields_of_study and publication_types, which the schema does not. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource ('Search for academic papers') plus the key enabler ('by query with advanced filters'), so the agent knows immediately what the tool does. It does not, however, differentiate itself from close siblings like bulk_search_papers or search_paper_snippets, leaving that inference to the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool over bulk_search_papers, search_paper_snippets, or match_paper_by_title, and no stated prerequisites or exclusions. Usage is only implied by the parameter list rather than explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search within the full text of papers, not just titles/abstracts. Returns ~500-word text excerpts from papers matching the query, with the section where the match was found (e.g. Introduction, Methods).
query: Text to search for within papers (e.g. 'chain-of-thought prompting improves reasoning').
limit: Number of results (default 10).
fields_of_study: Filter by discipline (e.g. 'Computer Science').
min_citation_count: Minimum citations for matched papers.
year: Year or range (e.g. '2023' or '2020-2024').
venue: Filter by venue (e.g. 'NeurIPS').
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| limit | No | ||
| query | Yes | ||
| venue | No | ||
| fields_of_study | No | ||
| min_citation_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses the return format (~500-word excerpts, section names) which is valuable, but doesn't cover rate limits, permissions, result ordering, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the key differentiator (full-text search) then lists parameters efficiently. Slightly list-heavy but each line earns its place with an example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the core behavior and parameters well for a search tool but leaves gaps in result ordering, pagination, and explicit guidance vs siblings. With no annotations and no output schema, a bit more behavioral context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents all six parameters with examples ('2020-2024', 'NeurIPS', 'Computer Science'), adding meaningful semantic context beyond bare types, though it doesn't state that year accepts ranges explicitly beyond the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (search full text of papers) and explicitly distinguishes scope from title/abstract searching, which separates it from siblings like search_papers. Description of returning ~500-word excerpts with section names is concrete and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage via 'within the full text of papers, not just titles/abstracts' but doesn't explicitly say when to prefer this over search_papers or bulk_search_papers. The contrast hints at selection criteria without a clear directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0batch_get_papersbulk_search_papersfind_common_citationsget_author_detailsget_citationsget_paper_bibtexget_paper_citationget_paper_detailsget_referencesget_related_papersmatch_paper_by_titleread_pdf_textsearch_authorssearch_paper_snippetssearch_papersScored across 15 tools
Most tools have clearly distinct purposes, but there is some overlap: get_paper_bibtex and get_paper_citation (which supports a bibtex style) both retrieve BibTeX output, and search_papers vs bulk_search_papers both perform paper search although bulk supports boolean/systematic queries. These are mostly differentiated in descriptions, but the duplication can still cause hesitation.
Names mostly follow a snake_case verb_noun pattern (search_papers, get_paper_details, get_citations). Minor deviations include batch_get_papers (verb position) and match_paper_by_title (prepositional phrase), plus get_paper_bibtex vs get_paper_citation being format-specific rather than action-consistent, but the set remains readable.
15 tools is at the high end of the typical 3-15 range but each tool earns its place for a research-paper assistant: search, bulk search, snippets, metadata, citations, references, authors, formatting, and PDF extraction. The scope is broad but coherent and not padded with redundant operations.
The surface covers the full research lifecycle: paper search (basic, bulk, full-text snippets), paper identification and metadata, citation graph traversal (citations, references, common citations), author lookup, related-paper recommendation, BibTeX/formatted citation output, batch retrieval, and open-access PDF text extraction. No obvious dead ends for academic literature exploration and citation management.
Academic paper search, scientific literature, citation analysis, arXiv & semantic related-work.
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Search 340M+ academic papers — citation graphs, semantic similarity, and AI literature reviews.
Search arXiv and ACL Anthology, retrieve citations and references, and browse web sources to accel…
