Skip to main content
Glama
deenesjakoruzh
Neuro-Mechatronics-Interfaces

SemanticScholar_MCP

by Neuro-Mechatronics-Interfaces
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

SemanticScholar_MCP

Deterministic Model Context Protocol interfaces for the three Semantic Scholar API families:

  • S2AG — Academic Graph search, metadata, authors, citations, and references.

  • Recommendations — Semantic Scholar's paper recommendation service.

  • Datasets — release discovery, dataset manifests, and incremental dataset updates.

The project intentionally provides thin API wrappers rather than an agentic literature-research system.

Design

The central rule is:

One MCP tool invocation represents one documented Semantic Scholar operation.

The servers perform transport-level work such as validation, authentication, rate limiting, retries, and response normalization.

They do not decide what literature is scientifically important.

For example:

Agent
  │
  ├── "Search for paired-pulse TMS papers"
  │         │
  │         ▼
  │       S2AG MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  ├── "Recommend papers from these three seed papers"
  │         │
  │         ▼
  │  Recommendations MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  └── "Describe the latest S2ORC dataset release"
            │
            ▼
       Datasets MCP
            │
            ▼
       Semantic Scholar

Search expansion, scientific interpretation, summarization, citation-graph exploration strategy, and research synthesis remain responsibilities of the consuming agent.

Related MCP server: Semantic Scholar MCP Server

Repository Structure

SemanticScholar_MCP/
├── src/
│   └── semantic_scholar_mcp/
│       ├── common/
│       │   ├── client.py
│       │   ├── errors.py
│       │   ├── models.py
│       │   ├── rate_limit.py
│       │   └── __init__.py
│       ├── datasets/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── recommendations/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── s2ag/
│       │   ├── server.py
│       │   └── __init__.py
│       └── __init__.py
├── tests/
├── AGENTS.md
├── CLAUDE.md
├── pyproject.toml
└── README.md

Requirements

  • Python 3.11 or newer

  • Internet access to Semantic Scholar

  • Optional Semantic Scholar API key

The implementation uses the current v2 line of the official Python MCP SDK.

Installation

Create a virtual environment:

py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1

Install the package in editable mode with development dependencies:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Alternatively, with uv:

uv venv --python 3.14
uv pip install -e ".[dev]"

Python 3.14 is not required; the project supports Python 3.11 and later.

After configuring the Python package environment, optionally run tests: 

pytest
ruff check .
ruff format --check .

If you have already configured SEMANTIC_SCHOLAR_API_KEY as a system environment variable (see next section, Authentication), you can also test live integration: 

pytest --run-integration

Note: If you set the system environment variable to your API key after starting any VSCode window, you need to close all VSCode windows to completely restart VSCode before the system environment will be captured by tools run through VSCode Extensions!

Authentication

Semantic Scholar supports unauthenticated access to many API operations.

When an API key is available, expose it to the MCP processes through:

$env:SEMANTIC_SCHOLAR_API_KEY = "..."

Do not place the key in:

  • .mcp.json;

  • .codex/config.toml;

  • source code;

  • committed .env files;

  • test fixtures.

The MCP servers automatically use the key when it is present.

Operations that require authentication should return an explicit error when no key is configured.

Note (again): If you set the system environment variable to your API key after starting any VSCode window, you need to close all VSCode windows to completely restart VSCode before the system environment will be captured by tools run through VSCode Extensions!

Build Updates

The scripts .\rebuild.ps1 and .\version.ps1 are provided as utilities to facilitate version updates when rebuilding:

rebuild.ps1

To rebuild without auto-incrementing the patch number, explicitly specify the switch: 

.\rebuild.ps1 -SkipVersionIncrement

Otherwise, .\rebuild.ps1 auto-increments the patch number in pyproject.toml directly.

version.ps1

To increment <major> | <minor> | <patch> without rebuilding: 

.\version.ps1 patch -NoRebuild

To increment minor version, resetting patch to 0, and rebuild: 

.\version.ps1 minor

To increment major version, resetting both minor and patch to 0, and rebuild: 

.\version.ps1 major

MCP Client Configuration

The three Semantic Scholar MCP servers can be configured either:

  • project-locally, so they are available only within a particular repository; or

  • user-globally, so they are available across repositories.

The servers are:

  • s2ag — Semantic Scholar Academic Graph

  • s2_recommendations — Semantic Scholar Recommendations API

  • s2_datasets — Semantic Scholar Datasets API

The examples below assume this repository is installed at:

C:\MyRepos\Python\SemanticScholar_MCP

Adjust the path as needed.

The examples deliberately invoke the virtual environment's Python interpreter with python -m ... rather than invoking the generated semantic-scholar-*.exe console launchers directly. This is recommended during local development on Windows because running console launchers can prevent pip from replacing them during an editable reinstall.

Automated user-global registration

An optional installer can write the user-global Codex and Claude Code configuration for you, so you do not have to edit ~/.codex/config.toml and ~/.claude.json by hand.

Install it with the install extra (included in dev):

python -m pip install -e ".[install]"

Then run:

semantic-scholar-install

This upserts the three Semantic Scholar servers into:

  • ~/.codex/config.toml (Codex, [mcp_servers.*] tables), and

  • ~/.claude.json (Claude Code, mcpServers entries).

The interpreter path is derived from the environment the installer runs in (sys.executable), so the written configuration points at that virtual environment's python.exe and invokes each server as python -m <module>. Only the three Semantic Scholar entries are inserted or overwritten; all other content is preserved, and for Codex the file's comments and formatting are kept intact. A .bak copy of each edited file is written before changes.

API key prompt

After writing the configuration, the installer checks for SEMANTIC_SCHOLAR_API_KEY:

  • If the variable is already set in the current environment, it is left unchanged.

  • If it is not set and the installer is running in an interactive terminal, you are prompted to paste your key. The input is hidden, and pressing Enter without typing anything skips this step and continues without an API key.

When you provide a key on Windows, the installer persists it as a user environment variable (writing HKEY_CURRENT_USER\Environment and broadcasting the environment change, matching [Environment]::SetEnvironmentVariable(..., "User")). The key is stored only in the environment — it is never written into any MCP configuration file. Restart terminals and MCP hosts afterward so newly launched processes inherit it.

On non-Windows systems the installer does not persist the variable and instead prints how to set it yourself.

Useful flags:

semantic-scholar-install --dry-run     # Print the resulting config without writing
semantic-scholar-install --codex-only  # Update only ~/.codex/config.toml
semantic-scholar-install --claude-only # Update only ~/.claude.json
semantic-scholar-install --no-api-key  # Skip the SEMANTIC_SCHOLAR_API_KEY check/prompt

After running the installer, verify the registrations with codex mcp list and claude mcp list.

Because Claude Code owns additional state in ~/.claude.json, the manual claude mcp add --scope user flow documented below remains available if you prefer to let Claude Code manage its own file.

Codex

Codex supports both user-global and project-local config.toml files.

Project-local Codex configuration

Create or edit:

<project>/.codex/config.toml

For example:

[mcp_servers.s2ag]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.s2ag.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_recommendations]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.recommendations.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_datasets]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.datasets.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

Project-scoped Codex configuration is loaded only for projects that Codex considers trusted.

User-global Codex configuration

To make the servers available to Codex across projects, place the same configuration in:

~/.codex/config.toml

On Windows this is normally:

%USERPROFILE%\.codex\config.toml

For example:

C:\Users\<username>\.codex\config.toml

The MCP server blocks themselves are identical to the project-local example above.

Verify Codex configuration

From a terminal:

codex mcp list

Individual registrations can also be inspected with:

codex mcp get s2ag
codex mcp get s2_recommendations
codex mcp get s2_datasets

Claude Code

Claude Code distinguishes between project-shared and user-scoped MCP servers.

Project-local / project-shared Claude configuration

Create:

<project>/.mcp.json

with:

{
  "mcpServers": {
    "s2ag": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.s2ag.server"
      ]
    },
    "s2_recommendations": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.recommendations.server"
      ]
    },
    "s2_datasets": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.datasets.server"
      ]
    }
  }
}

This file can be committed to the consuming repository when the MCP configuration is intended to be shared with other users of that repository.

User-global Claude configuration

For global Claude Code configuration, the preferred approach is to let Claude Code manage the user-scoped MCP registrations.

Run:

claude mcp add --scope user s2ag -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.s2ag.server

claude mcp add --scope user s2_recommendations -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.recommendations.server

claude mcp add --scope user s2_datasets -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.datasets.server

Claude Code currently stores user-scoped MCP configuration in:

~/.claude.json

On Windows:

%USERPROFILE%\.claude.json

Using claude mcp add --scope user is preferred over manually editing this file because Claude Code owns additional state in .claude.json.

Verify the registrations with:

claude mcp list

If a particular Claude Code version has trouble loading user-scoped MCP servers, the project .mcp.json configuration is the simplest fallback.

Semantic Scholar API Key

Many Semantic Scholar operations can work without authentication. Operations requiring an API key use:

SEMANTIC_SCHOLAR_API_KEY

Do not commit the key to an MCP configuration file.

On Windows, it may be persisted as a user environment variable:

[Environment]::SetEnvironmentVariable(
    "SEMANTIC_SCHOLAR_API_KEY",
    "YOUR_API_KEY",
    "User"
)

Restart VS Code, Codex, Claude Code, or other MCP hosts after setting the variable so newly launched MCP processes inherit it.

The MCP servers automatically use the key when it is present and otherwise remain unauthenticated where Semantic Scholar permits anonymous access.

Project-local vs. user-global

A useful rule is:

Scope

Codex

Claude Code

Recommended when

Project

.codex/config.toml

.mcp.json

The repository explicitly depends on these research tools

User

~/.codex/config.toml

claude mcp add --scope user

You want Semantic Scholar available in many unrelated repositories

For a research repository whose agents are explicitly expected to perform literature discovery, project-local configuration is usually preferable because the available research tooling travels with the repository.

For general personal access to Semantic Scholar from arbitrary projects, user-global configuration is more convenient.

Shared Rate Limiting

Semantic Scholar's introductory authenticated rate limit applies across API endpoints rather than independently to each MCP server.

This repository therefore uses a shared interprocess limiter:

S2AG MCP ────────────────┐
                         │
Recommendations MCP ─────┼── shared limiter ──> Semantic Scholar
                         │
Datasets MCP ────────────┘

The default implementation should allow no more than approximately one upstream request per second across all three local servers.

This matters when multiple hosts are running simultaneously, for example:

VS Code / Codex
Claude Code
MCP Inspector
tests

The limiter should coordinate these processes rather than maintaining an independent clock in each one.

Retry Behavior

Transient upstream failures may be retried using bounded exponential backoff.

Examples include:

  • HTTP 429;

  • transient 5xx responses;

  • temporary network failures.

Retry-After is honored when provided.

Ordinary client errors such as invalid requests, rejected authentication, and missing resources are not repeatedly retried.

Retries are bounded; the MCP never retries indefinitely.

S2AG MCP

Run:

semantic-scholar-s2ag

or:

python -m semantic_scholar_mcp.s2ag.server

The initial API surface is intended to include:

Tool

Purpose

get_paper

Retrieve one known paper

get_papers

Batch-retrieve known papers

search_papers

Structured/bulk paper search

search_papers_relevance

Relevance-ranked paper search

get_citations

Retrieve one page of papers citing a paper

get_references

Retrieve one page of a paper's references

get_author

Retrieve one author

get_authors

Batch-retrieve known authors

search_authors

Search authors

get_author_papers

Retrieve one page of an author's papers

Pagination remains explicit.

A citation request does not recursively traverse the citation graph.

A search does not automatically issue follow-up searches.

Recommendations MCP

Run:

semantic-scholar-recommendations

or:

python -m semantic_scholar_mcp.recommendations.server

The initial surface is intentionally small:

Tool

Purpose

recommend_for_paper

Request recommendations using one seed paper

recommend_from_examples

Request recommendations using supplied positive and negative paper IDs

The server passes caller-selected seeds to Semantic Scholar.

It does not choose its own seeds or apply a second LLM-generated ranking to the results.

Example conceptual workflow:

positive:
  paper A
  paper B
  paper C

negative:
  paper D

        │
        ▼

recommend_from_examples

        │
        ▼

Semantic Scholar recommendation ranking

Datasets MCP

Run:

semantic-scholar-datasets

or:

python -m semantic_scholar_mcp.datasets.server

The initial tools are:

Tool

Purpose

list_releases

List available dataset releases

get_release

Inspect a particular release

get_dataset

Obtain metadata/manifest information for a dataset

get_diffs

Obtain update/delete manifests between releases

The Datasets MCP deliberately does not automatically download entire Semantic Scholar datasets.

Some Semantic Scholar datasets are very large. Retrieving a manifest is an appropriate MCP operation; initiating a multi-gigabyte corpus download requires explicit user-controlled tooling.

A future dedicated CLI may provide commands such as:

s2-dataset download ...
s2-dataset update ...
s2-dataset verify ...

without making those operations implicit MCP behavior.

Determinism

For this project, deterministic means that tool semantics are explicit and inspectable.

A tool may:

validate input
    ↓
wait for rate limiter
    ↓
make one documented API request
    ↓
retry transient transport failures if necessary
    ↓
normalize response
    ↓
return structured data

A tool must not silently become:

search
   ↓
search again with different terms
   ↓
fetch every page
   ↓
walk citations
   ↓
request recommendations
   ↓
rank with an LLM
   ↓
summarize papers

Higher-level orchestration belongs outside this repository.

Pagination

Pagination is caller-controlled.

When Semantic Scholar returns a continuation token, offset, or equivalent cursor, the MCP returns that value.

The caller can explicitly request another page.

The MCP does not automatically fetch all available pages.

This protects both determinism and API usage.

Fields

Where Semantic Scholar supports explicit response fields, tools should request only the fields needed by the caller.

A small default field set may be provided for usability.

Large fields such as abstracts or citation contexts should not be requested automatically unless part of the documented tool default.

Errors

Upstream conditions should be translated into stable, understandable MCP errors.

Examples:

authentication_required
rate_limited
not_found
invalid_request
upstream_error
transport_error

Where useful, the structured error may retain:

  • HTTP status;

  • retryability;

  • number of attempts;

  • Semantic Scholar error message.

Secrets must never be included.

Development

Run unit tests:

pytest

Run linting:

ruff check .

Check formatting:

ruff format --check .

Apply formatting:

ruff format .

Live Semantic Scholar tests are marked separately:

pytest --run-integration

Ordinary unit tests should mock HTTP interactions and must not consume Semantic Scholar API quota.

Testing Philosophy

The most important tests verify API fidelity.

For every MCP tool, tests should confirm:

input
  ↓
exact expected HTTP operation
  ↓
expected response normalization

Tests should also verify the absence of hidden behavior.

For example, a single citation request should generate one citation API operation—not automatically request subsequent pages or references.

Relationship to Research Tools

This repository should remain domain-neutral.

For example, it can expose:

paper A cites paper B

or:

Semantic Scholar recommends paper C from seeds A and B

but it should not conclude:

paper C is the strongest evidence for a particular neuroscience hypothesis

A separate research repository, Research MCP, or human researcher can make that interpretation.

This separation allows the Semantic Scholar layer to remain:

  • deterministic;

  • reusable;

  • easy to test;

  • independent of any specific scientific field;

  • usable by different MCP hosts and agents.

Semantic Scholar Usage

This project is intended for legitimate research use and must comply with the current Semantic Scholar API license and documentation.

API usage should:

  • respect active rate limits;

  • use batch/bulk operations where appropriate;

  • request only needed fields;

  • use bounded exponential backoff;

  • protect API credentials;

  • avoid unrestricted API crawling;

  • prefer the Datasets API when truly corpus-scale access is required.

Public products or displays using Semantic Scholar response data may have additional attribution requirements. Review the current Semantic Scholar license before adding public-facing data presentation.

See AGENTS.md for the normative development and API-use rules for this repository.

Available Tools

10 tools
get_authorC

Get one Semantic Scholar author by author ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldsNo
author_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Get one author' and does not mention what happens on missing IDs, what fields are returned, rate limits, or any side effects. The behavior is minimally implied but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, terse sentence with no wasted words. It is appropriately concise for the scope, though it sacrifices detail for brevity. The structure is clean and front-loaded with the key action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two parameters, no annotations, and an output schema (not shown), the description is too sparse. It fails to explain the fields parameter, usage context, or any behavioral nuances, leaving an agent with incomplete information to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

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 clarifies that author_id is used to identify the author, but completely omits any explanation of the 'fields' parameter—its purpose, allowed values, or format. With two parameters, this is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'Semantic Scholar author', and the identifier 'author ID'. It distinguishes this from siblings like get_authors (plural) and search_authors (search-based), so an agent can easily tell it apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives like search_authors or get_authors. There is no mention of conditions such as 'when you have a known author ID' or exclusions, leaving usage to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_author_papersC

Get one page of papers associated with a Semantic Scholar author.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
fieldsNo
offsetNo
author_idYes
publication_date_or_yearNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral disclosure burden. It usefully reveals pagination behavior ('one page'), but it leaves the meaning of 'associated' ambiguous (authored, co-authored, or cited?) and says nothing about ordering, rate limits, authentication, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single 10-word sentence that front-loads the verb and resource. It is efficiently sized for a straightforward tool, though its brevity comes at the cost of the semantic gaps noted in other dimensions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 parameters at 0% schema coverage, overlapping siblings, and no annotations, the description is too thin to fully support correct invocation. An output schema exists, which spares it from documenting return values, but parameter semantics and tool-selection context remain unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% with 5 parameters, yet the description explains none of them. While names like author_id, limit, and offset are somewhat self-explanatory, the meaning and format of fields and publication_date_or_year are completely unexplained, and the description adds no value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

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 one page of papers associated with a Semantic Scholar author') that clearly distinguishes it from author-lookup siblings like get_author and search_authors. However, it does not explicitly differentiate from paper-lookup siblings like get_papers or search_papers, which could also be selected for fetching papers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives such as get_papers, search_papers, or search_papers_relevance. With a sibling list full of overlapping paper-fetching tools, the absence of any selection criteria or exclusions leaves the agent to guess.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_authorsB

Batch-get up to 1000 Semantic Scholar author IDs.

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldsNo
author_idsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It does disclose two useful traits: the operation is batched and capped at 1000 IDs. However, it says nothing about handling of missing or invalid IDs, result ordering, rate limits, or authentication, leaving significant behavior unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the batch limit is placed prominently and every word contributes. It is concise without being empty.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Insufficient for a tool with no annotations and no per-parameter documentation. The output schema may cover return shape, but the agent still lacks when-to-use guidance, understanding of the fields parameter, and failure behavior expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

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 does not: 'author IDs' only restates the author_ids property, and the optional fields parameter is completely unexplained even though it likely controls which author attributes are returned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description supplies a specific verb ('Batch-get'), a resource (Semantic Scholar authors), and a batch-size limit (1000), so the core operation is clear. It does not explicitly differentiate from the sibling get_author or search_authors, and 'author IDs' is slightly ambiguous as to whether IDs are the input or the returned objects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance about when to use this tool versus get_author (single author) or search_authors (find authors by query). 'Batch' hints at multiple IDs, but no explicit conditions, preconditions, or alternatives are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_citationsC

Get one page of papers that cite the requested paper.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
fieldsNo
offsetNo
paper_idYes
publication_date_or_yearNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

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 mentions pagination ('one page') but does not disclose behavior such as default limit, offset semantics, field filtering, or whether results are sorted. For a read tool, this is a moderate gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that is front-loaded with the core action. It earns its place but could add a bit more context without becoming bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 parameters, 0% schema coverage, no annotations, and an output schema present, the description is too thin. It does not explain pagination parameters, field selection, or the output structure, making it incomplete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

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, but it only explains paper_id implicitly. The limit, offset, fields, and publication_date_or_year parameters are not described at all, leaving the agent to guess their semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and resource ('papers that cite the requested paper'), which clearly identifies the tool's function. It does not explicitly distinguish it from siblings like get_references, but the resource is specific enough that an agent can infer the difference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as get_references or search_papers. The description implies a use case (fetching citing papers) but does not state exclusions or conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_paperB

Get one paper by Semantic Scholar ID or supported external identifier.

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldsNo
paper_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden for behavioral disclosure. It only says 'get' and gives no information about read-only behavior, external identifier resolution, authentication/rate limits, or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with no filler, and the key scoping information—one paper, by identifier—is front-loaded. Every word contributes to the agent's understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since an output schema exists, the return shape does not need to be explained, and the description is adequate for a simple lookup. Still, the fields parameter is left unexplained and there is no guidance on which sibling tools to use for search or batch retrieval, leaving gaps in the full calling context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds useful meaning to paper_id by explaining that it accepts either a Semantic Scholar ID or a supported external identifier, which the schema alone does not convey. However, the optional fields parameter is not mentioned at all, and with 0% schema description coverage the description should compensate more fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a direct fetch of a single paper, keyed by Semantic Scholar ID or supported external identifier. The singular 'one paper' and identifier-based lookup distinguish it from search_papers, but it never explicitly names sibling tools such as get_papers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used when an identifier is already known, but it gives no explicit guidance about when not to use it or when to prefer search_papers/get_papers. This is usable guidance but left mostly to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_papersA

Batch-get up to 500 caller-supplied paper identifiers.

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldsNo
paper_idsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral disclosure burden. It adds a useful constraint ('up to 500') and makes the retrieval semantics inferable from 'batch-get', but it does not mention handling of invalid IDs, over-limit requests, error behavior, or the effect of the optional fields parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence that conveys the verb, object, and key constraint with no filler. Every word earns its place and the structure makes the main behavior immediately clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema covers returned values, and paper_ids is clearly described enough for a straightforward batch fetch. However, the optional fields parameter is entirely unexplained and there is no explicit guidance distinguishing this tool from get_paper, so an agent may under-specify the request or choose the wrong sibling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

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 clarifies that paper_ids are caller-supplied paper identifiers and that the batch is capped at 500, but it says nothing about the fields parameter—its meaning, allowed values, or effect—leaving one of two parameters effectively undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('batch-get'), resource ('papers'), and defining constraints ('up to 500 caller-supplied paper identifiers'). This clearly distinguishes it from the search_* siblings, which do not take caller-supplied paper_ids, and from get_paper, which is the singular variant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'caller-supplied paper identifiers' signals that this tool is for known IDs rather than search queries, and 'batch' positions it for fetching multiple papers at once. It does not explicitly name get_paper for single lookups or state when not to use this tool, so it stops short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_referencesC

Get one page of references cited by the requested paper.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
fieldsNo
offsetNo
paper_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'one page' which hints at pagination, but does not explain default page size, how offset/limit interact, whether results are sorted, or what happens if the paper has no references. It also does not disclose any rate limits, authentication needs, or side effects (though this is likely a read operation).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. It front-loads the core action and resource. However, it is so brief that it misses important parameter and usage details, so it is concise but under-specified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, 0% schema coverage, no annotations, and an output schema exists, the description is incomplete. It does not explain pagination parameters, field selection, or how the output is structured. The output schema may help, but the description should at least clarify the meaning of limit, offset, and fields to allow correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

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 for the four parameters. It only clarifies that paper_id identifies the paper whose references are returned. It does not explain limit, offset, or fields. The term 'one page' implies limit/offset but does not define their semantics or defaults. The fields parameter is completely unexplained, leaving the agent to guess what field names are valid.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and resource ('references cited by the requested paper'), and the phrase 'one page' signals pagination. It is clear enough to distinguish from siblings like get_citations, which likely returns citing papers rather than cited references. However, it does not explicitly differentiate from get_paper or get_papers, which could also return reference lists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 like get_citations or search_papers. It does not mention pagination behavior, how to request more pages, or any context about typical use cases. The only implied usage is that it returns references for a paper, but no exclusions or alternatives are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_authorsC

Search authors by name using one offset-paginated request.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes
fieldsNo
offsetNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only reveals that this is 'one offset-paginated request' and says nothing about matching semantics, ordering, rate limits, or read-only safety. This is minimal added context beyond the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. Every word contributes to the core action, making it structurally clean and appropriately sized for such a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations, four parameters, and a sibling set that includes get_authors and get_author, this description is insufficiently complete. An agent still needs to understand pagination behavior, fields semantics, and how this tool differs from the retrieval siblings. The output schema covers return values, but the calling context remains vague.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description needed to explain query, limit, offset, and fields. It only hints that the query is a name and gives no details about field projections, pagination bounds, or how the parameters interact. The description fails to compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'search', the resource 'authors', and the filter 'by name', and it mentions offset pagination. It is distinguishable from siblings such as get_authors, though it does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use search_authors versus get_authors or get_author. There are no conditions, exclusions, or alternative recommendations, leaving the agent to infer the appropriate context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_papersC

Run one token-paginated /paper/search/bulk request.

This endpoint returns up to 1000 papers per upstream call and does not accept a limit argument. Pass the returned token explicitly for the next page.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNo
yearNo
queryYes
tokenNo
venueNo
fieldsNo
fields_of_studyNo
open_access_pdfNo
publication_typesNo
min_citation_countNo
publication_date_or_yearNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry behavioral disclosure. It does disclose the key pagination behavior: returns up to 1000 papers per call, no limit argument, and requires the token for the next page. However, it does not mention other behaviors like filtering semantics, output format, or any potential side effects. The disclosure is useful but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no redundancy. It front-loads the core action and states the pagination constraint efficiently. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 11 parameters and zero schema descriptions, the description is severely under-specified. An agent cannot correctly construct a query without understanding parameters like fields_of_study, publication_types, min_citation_count, and publication_date_or_year. The output schema exists, but the input semantics are nearly absent, making this inadequate for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

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 explains the token parameter via pagination, but the other 10 parameters (query, sort, year, venue, fields, etc.) are left entirely to schema titles, which provide no semantic meaning. The description adds value only for the token, failing to clarify the rest.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: running a bulk paper search request with pagination. It mentions the specific endpoint and the pagination behavior. However, it does not differentiate from the sibling search_papers_relevance, which likely orders by relevance, leaving ambiguity about when to choose one over the other.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives like search_papers_relevance or get_papers. It only implies bulk retrieval via the word 'bulk', but does not state conditions for selection or exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_papers_relevanceB

Run one relevance-ranked /paper/search request.

Relevance search is limited by Semantic Scholar to 100 results per call and 1000 relevance-ranked results total.

ParametersJSON Schema
NameRequiredDescriptionDefault
yearNo
limitNo
queryYes
venueNo
fieldsNo
offsetNo
fields_of_studyNo
open_access_pdfNo
publication_typesNo
min_citation_countNo
publication_date_or_yearNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry behavioral disclosure. It does disclose important limits (100 per call, 1000 total), which is useful. However, it omits other behavioral traits such as authentication requirements, side effects, or that it's a read operation, leaving gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no fluff, purpose front-loaded, and the limit context stated efficiently. Excellent structure for the information provided.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 11 parameters with no schema descriptions and no output schema details in the description. The only contextual info is the result limits. Given the complexity, this is incomplete for correct usage; an agent would struggle with valid values for fields like publication_types or fields_of_study.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

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 for parameter meaning. It provides no information about any of the 11 parameters, leaving agents to guess from names alone. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs a relevance-ranked /paper/search request, specifying the verb and resource. It distinguishes from siblings through the 'relevance-ranked' qualifier, though it does not explicitly name the alternative search tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives like search_papers. The description only mentions limits, not the selection criteria based on relevance needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 10 tool updatesv0.2.3
    • First observedget_author
    • First observedget_author_papers
    • First observedget_authors
    • First observedget_citations
    • First observedget_paper
    • First observedget_papers
    • First observedget_references
    • First observedsearch_authors
    • First observedsearch_papers
    • First observedsearch_papers_relevance
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 10 tools

Disambiguation4/5

Tools are mostly distinct: get_authors/get_author differ by batch vs single ID, and search_papers vs search_papers_relevance are differentiated by bulk vs relevance-ranked semantics. The only slight confusion is the two search variants, but descriptions clarify their differing endpoints.

Naming Consistency4/5

Naming follows a consistent verb_noun pattern with get_ for retrieval and search_ for querying. search_papers_relevance is a minor deviation from the simple object naming, but it remains readable and predictable.

Tool Count5/5

10 tools is well-scoped for a scholarly search and retrieval API, covering authors, papers, citations, references, and author-paper relationships without unnecessary redundancy.

Completeness5/5

The surface covers the core academic search workflows: author lookup, single/batch paper retrieval, external ID support, bulk and relevance search, citations, references, and author-associated papers. For a read-only domain, no major gaps are apparent.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-semanticscholar

    pipeworx-io
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to query the Semantic Scholar Academic Graph for scholarly paper data, supporting tools for search, retrieval, and analysis.
    5 npm
    MIT

  • scholar-memory

    byBasiliosP
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables scientific literature research through multi-agent search, analysis, and semantic memory, exposing 9 MCP tools for querying, storing, and retrieving research findings.
    1
    MIT

  • semanticscholar-mcp-server

    XWang20
    A
    license
    B
    quality
    A
    maintenance
    An MCP server that provides access to Semantic Scholar's academic graph, recommendations, and datasets APIs, enabling paper search, citation analysis, author lookups, and dataset discovery through 20+ tools.
    22
    3
    MIT