scholar-mcp

Search Papers

search_papers

Read-only

Search Semantic Scholar for papers by query and filter by venue, year, citations, or field of study; sort results and paginate through up to 100 papers per call.

Instructions

Search Semantic Scholar for papers matching a query.

Usually completes in a few seconds. Returns at most 100 papers per call; a larger limit is capped at 100, so page further with offset.

Answers directly in normal use. Should the call run long it continues in the background and returns a job handle to poll with get_job_result.

Input Schema

Name	Required	Description	Default
`sort`	No	Sort order: ``relevance``, ``citations`` or ``year``.	relevance
`limit`	No	Maximum results to return (max 100).
`query`	Yes	Keyword or semantic search query.
`venue`	No	Filter by venue name.
`fields`	No	Field set preset: ``compact``, ``standard`` or ``full``.	compact
`offset`	No	Pagination offset.
`year_end`	No	Latest publication year (inclusive).
`year_start`	No	Earliest publication year (inclusive).
`min_citations`	No	Minimum citation count.
`fields_of_study`	No	Filter by fields, such as ``["Computer Science"]``.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv3.1.1Nov 5, 2026

changedInput schema / properties / fields / description

Previous value: -"Field set preset — compact, standard, or full."New value: +"Field set preset: ``compact``, ``standard`` or ``full``."

changedInput schema / properties / fields_of_study / description

Previous value: -"Filter by fields, e.g. [\"Computer Science\"]."New value: +"Filter by fields, such as ``[\"Computer Science\"]``."

changedInput schema / properties / sort / description

Previous value: -"Sort order — relevance, citations, or year."New value: +"Sort order: ``relevance``, ``citations`` or ``year``."

Changed4 schema fields changedv1.10.0Sep 8, 2026
- addedOutput schema / additionalProperties
```
Added value: +true
```
- removedOutput schema / properties
```
Removed value: -{
-  "result": {
-    "type": "string"
-  }
-}
```
- removedOutput schema / required
```
Removed value: -[
-  "result"
-]
```
- removedOutput schema / x-fastmcp-wrap-result
```
Removed value: -true
```
First observedv1.9.0Aug 10, 2026

TDQS

A3.9/5.0

Behavior5/5

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

Annotations cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuinely new behavior beyond them: typical latency of a few seconds, a hard 100-result cap, the recommendation to paginate with offset, and a background-job degradation path with the specific polling tool named. An output schema exists, so return format need not be restated. This is exactly the kind of operational context annotations cannot carry.

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?

Three short paragraphs, front-loaded with purpose, then operational limits, then the async fallback — each paragraph serves a distinct need. Minor waste in 'a larger limit is capped at 100' duplicating the schema's max-100 note, and the blank-line-heavy formatting is slightly loose, but nothing is bloated.

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

Completeness4/5

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

For a 10-parameter read tool with full schema coverage, an output schema, and safety annotations, the description supplies what structured fields cannot: latency, the result cap, pagination strategy, and the job-handle fallback. The filtering parameters (venue, years, min_citations, fields_of_study) are left entirely to the schema, which is acceptable given 100% coverage. Nothing critical to invoking it correctly is missing.

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?

Schema description coverage is 100%, so every one of the ten parameters is already documented, including enums for sort and fields. The description's only added parameter meaning is that limit values above 100 are silently capped and that offset is the pagination lever, which largely restates the schema's 'max 100' and 'Pagination offset'. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a specific verb and resource plus the backing service: 'Search Semantic Scholar for papers matching a query.' An agent can distinguish it from resource-specific siblings like search_books, search_standards or get_paper by the noun. It stops short of naming a nearest alternative such as recommend_papers, so the differentiation is implicit rather than explicit.

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 gives clear operational guidance for the async case ('Should the call run long it continues in the background and returns a job handle to poll with get_job_result'), which tells the agent what to do with the result. However, it never says when to prefer this tool over recommend_papers, get_paper or other siblings, and offers no exclusions or prerequisites. Usage context is implied, not stated.

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