Skip to main content
Glama
google-scholar-search-mcp

google-scholar-search-mcp

by LWaetzig

search_papers

Search Google Scholar for academic papers by keyword and use year filters, sorting, or paging to narrow research results.

Instructions

Search Google Scholar for academic papers by keyword.

To page, call again with offset set to the next_offset of the previous response (None means there are no more results). Each page costs at least one slow request: only page when the user needs more.

Args: query (str): Search query (same syntax as Google Scholar search box). max_results (int): Maximum number of results to return (1-20, default 10). year_from (int | None): Filter to papers published in or after this year. year_to (int | None): Filter to papers published in or before this year. sort_by (str): Sort order — "relevance" (default) or "date". include_patents (bool): Include patents in results (default True). offset (int): Number of results to skip (default 0). Scholar serves at most the first 1000 results of a query.

Returns: SearchResponse: Matching papers, with offset and next_offset for paging.

Raises: ScholarBlockedError: If Google Scholar blocks the client. ScholarRateLimitError: If Google Scholar throttles the request after retries. ScholarInvalidArgumentError: If offset reaches past the first 1000 results.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_papers"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYes
offsetNo
sort_byNorelevance
year_toNo
year_fromNo
max_resultsNo
include_patentsNo

Output Schema

NameRequiredDescriptionDefault
queryYes
offsetNo
papersYes
messageNo
next_offsetNo
total_resultsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.4.0
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "title": "Offset",
      +  "type": "integer"
      +}
    • removedOutput schema / $defs / PaperResult / properties / author_pub_id
      Removed value: -{
      -  "anyOf": [
      -    {
      -      "type": "string"
      -    },
      -    {
      -      "type": "null"
      -    }
      -  ],
      -  "default": null,
      -  "title": "Author Pub Id"
      -}
    • addedOutput schema / properties / next_offset
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Next Offset"
      +}
    • addedOutput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "title": "Offset",
      +  "type": "integer"
      +}
  2. First observedv0.0.0

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does so well: it discloses per-page latency cost, the 1000-result ceiling on any query, the termination signal via next_offset being None, and three named failure modes (blocking, rate limiting after retries, invalid offset). It stops short of saying what a blocked client recovers to or how retries configure, keeping it from 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.

Conciseness4/5

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

The purpose is front-loaded in one sentence, followed by a short paging rule and conventional Args/Returns/Raises sections. It is slightly padded by repeating parameter types and defaults that the schema already declares, but nothing is genuinely wasted.

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 seven-parameter network-backed search tool with no annotations, the description covers paging semantics, hard result limits, error conditions, and every argument; an output schema exists so return-shape detail is rightly omitted. The only gap is the lack of routing guidance relative to sibling search/detail tools.

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?

Schema description coverage is 0%, so the description must compensate, and the Args block documents all seven parameters including the sort_by enum values ("relevance"/"date") that the schema does not expose at all, plus the query syntax convention and the 1000-result offset ceiling. Some lines merely restate type and default information already present in the schema, so it is strong rather than exhaustive.

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 opening sentence names a specific verb and resource ("Search Google Scholar for academic papers") plus the input modality (keyword), which is unambiguous. It does not explicitly contrast with siblings such as bulk_search or get_paper_details, so an agent must infer the single-query scope from the name and the Args section.

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 concrete when-to guidance for paging ("only page when the user needs more" because each page costs at least one slow request) and explains the offset/next_offset contract. However, it never states when to prefer this tool over bulk_search or get_paper_details, and no when-not conditions are given.

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