scholar-mcp

Get Citation Graph

get_citation_graph

Read-only

Traverse citation networks from one or more seed papers via breadth-first expansion to map connected works and citation or reference links within depth and node limits.

Instructions

Traverse the citation graph from one or more seed papers.

Performs BFS up to depth hops. Returns nodes (paper records) and directed edges. Hard-caps at max_nodes to prevent runaway expansion.

Traversal makes one rate-limited request per node, so anything past a shallow, narrow graph runs long: expect a job handle to poll with get_job_result rather than the graph itself.

A Semantic Scholar throttle defers the same walk. Poll the job handle; the resumed graph does not mark the throttled request as partial.

A failed upstream request does not abort the walk. When one happens, stats.partial is true, stats.failed_requests counts them, and a warning key explains what was not fetched. Treat such a graph as incomplete: a missing node or edge is unknown, not absent. This is distinct from stats.truncated, which means max_nodes stopped an otherwise successful walk.

Input Schema

Name	Required	Description	Default
`depth`	No	Number of hops (1-3).
`seed_ids`	Yes	1-10 paper identifiers to start from.
`year_end`	No	Filter expanded papers to this year and earlier.
`direction`	No	Expand via citations, references, or both.	citations
`max_nodes`	No	Hard cap on total nodes returned.
`year_start`	No	Filter expanded papers to this year and later.
`min_citations`	No	Minimum citation count of expanded papers.
`fields_of_study`	No	Filter by field.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

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

A4.3/5.0

Behavior5/5

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

Far beyond the readOnly/openWorld annotations: it discloses one rate-limited request per node, job-handle-based returns, throttle resume behavior, and the crucial partial-vs-truncated distinction with stats.failed_requests and the warning key. It also warns that a throttled resume does not mark requests as partial, a non-obvious behavioral trait.

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?

Purpose is front-loaded, then cost, then failure modes in a sensible order, with no filler sentences. The poll-the-job-handle instruction is stated twice (throttle paragraph and cost paragraph), which is mild redundancy in an otherwise tight description.

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?

Given an output schema exists, the description need not enumerate return fields, yet it still explains the two stats flags an agent must interpret to avoid treating missing edges as absent. Every operational risk for this read-only, open-world, potentially long-running traversal is covered.

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 coverage is 100%, so baseline is 3, but the description adds real meaning to *depth* and *max_nodes* by tying them to cost and truncation semantics rather than just numeric bounds. It does not add anything for direction or the year/citation filters, which the schema already covers.

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 first sentence states a specific verb and resource ('Traverse the citation graph from one or more seed papers') and the second clarifies it is a BFS up to *depth* hops returning nodes and directed edges. That multi-hop framing implicitly separates it from single-hop siblings like get_citations and get_references, though no sibling is named explicitly.

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?

It tells the agent that any non-shallow traversal runs long and should be polled via get_job_result rather than awaited, naming the alternative tool explicitly. It lacks an explicit 'use this instead of get_citations when...' contrast, which keeps it below a 5.

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