Skip to main content
Glama
Sign In
smaniches

Semantic Scholar MCP Server

by smaniches
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

semantic_scholar_search_papers

Read-onlyIdempotent

Search academic papers by keyword, then filter results by year, field of study, publication type, open access, and citation count to find relevant research.

Instructions

Search for academic papers.

Relevance-ranked plain-text search over 200M+ papers, with year,
field-of-study, publication-type, open-access, and citation-count filters.
The query is sent unchanged; boolean and quoted-phrase syntax is
documented only for semantic_scholar_bulk_search. Page with
offset/limit (max 100 per call). For sorted or very large result sets
use semantic_scholar_bulk_search; to search inside paper full text use
semantic_scholar_snippet_search; to resolve one known title use
semantic_scholar_match_paper. Returns Markdown by default,
response_format='json' for raw JSON.

Input Schema

NameRequiredDescriptionDefault
paramsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.18
    • changedInput schema / $defs / PaperSearchInput / properties / query / description
      Previous value: -"Search query, e.g. 'protein language models'. Supports AND, OR, NOT operators and quoted phrases: '\"graph neural network\" AND drug'"New value: +"Plain-text search query, e.g. 'protein language models'. Semantic Scholar documents no special query syntax for this endpoint; the query is forwarded unchanged. For boolean/phrase syntax use semantic_scholar_bulk_search"
  2. Changed1 schema field changedv1.2.13
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "title": "Result",
-      "type": "string"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "search_papersOutput",
-  "type": "object"
-}New value: +null
  3. Changed3 schema fields changedv1.2.12
    • changedInput schema / $defs / PaperSearchInput / properties / limit / description
      Previous value: -"Max results (1-100)"New value: +"Max results per page (1-100, default 10); use semantic_scholar_bulk_search for result sets beyond 1000"
    • changedInput schema / $defs / PaperSearchInput / properties / offset / description
      Previous value: -"Pagination offset"New value: +"Pagination offset: pass the previous offset + limit to fetch the next page (default 0)"
    • changedInput schema / $defs / PaperSearchInput / properties / query / description
      Previous value: -"Search query"New value: +"Search query, e.g. 'protein language models'. Supports AND, OR, NOT operators and quoted phrases: '\"graph neural network\" AND drug'"
  4. Changed2 schema fields changedv1.2.6
    • addedInput schema / $defs / PaperSearchInput / properties / api_key / deprecated
      Added value: +true
    • changedInput schema / $defs / PaperSearchInput / properties / api_key / description
      Previous value: -"API key (overrides SEMANTIC_SCHOLAR_API_KEY env var)"New value: +"API key (overrides SEMANTIC_SCHOLAR_API_KEY env var). Deprecated: prefer the environment variable. Removal planned for v2.0.0."
  5. Changed1 schema field changedv1.0.3
    • addedInput schema / $defs / PaperSearchInput / properties / api_key
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "API key (overrides SEMANTIC_SCHOLAR_API_KEY env var)",
+  "title": "Api Key"
+}
  6. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: relevance ranking, the 200M+ corpus, per-call page cap of 100, unchanged query forwarding, and default Markdown vs output. Minor gaps remain (no rate-limit or auth notes), so a 4 rather than a 5.

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?

Front-loaded with the core action, then filters, then query-syntax caveat, then routing to siblings, then output format. Dense but every sentence carries decision-relevant information; no filler.

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

Completeness5/5

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

No output schema exists, and the description covers the return contract ('Returns Markdown by default, response_format=json for raw JSON'). Combined with annotations carrying the safety profile and the description covering pagination and routing, an agent has everything needed to call this correctly.

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

Parameters4/5

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

Reported schema description coverage is 0% at the top level, yet the description enumerates the filter surface (year, field-of-study, publication-type, open-access, citation-count) and explains offset/limit paging and response_format. It does not mention the deprecated api_key parameter, but it compensates well for the coverage gap on the parameters that matter for search behavior.

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?

States a specific verb+resource ('Search for academic papers') and immediately qualifies the mechanism ('relevance-ranked plain-text search over 200M+ papers'). It also names the sibling it is not (bulk_search, snippet_search, match_paper), so an agent can distinguish it from alternatives without opening a schema.

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

Usage Guidelines5/5

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

Explicitly routes the agent: bulk_search for sorted or very large result sets, snippet_search for full text, match_paper for a known title. It also states the query is forwarded unchanged and that boolean/phrase syntax belongs to bulk_search, which is a precise when-to-use-not constraint.

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

Deploy Server

Other Tools