scholar-mcp

Get Citation Graph

get_citation_graph

Read-only

Traverse citation graphs from seed papers to map references, citations, or both up to a set depth, returning nodes and edges with filtering by year and citations.

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 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 went unfetched. 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

TableJSON 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

TableJSON 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.5/5.0

Behavior5/5

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

Adds substantial context beyond the annotations: one rate-limited request per node, async job-handle return semantics, and a precise failure model where a failed upstream request yields stats.partial, stats.failed_requests, and a warning rather than aborting. It also disambiguates stats.partial from stats.truncated, which is exactly the kind of edge-case behavior an agent needs.

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-loads purpose and scope, then layers on cost, async behavior, and the partial-vs-truncated distinction in distinct, purposeful paragraphs. Every sentence carries operational meaning with 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?

For an 8-parameter, open-world traversal tool with an output schema, the description covers cost, async return, and the full failure-mode semantics. Combined with the output schema covering return shape, an agent has everything needed to call and interpret it.

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 parameter is already documented in the schema. The description reinforces depth ('up to *depth* hops') and max_nodes ('hard cap') behaviorally, but adds no syntax or format detail beyond what the schema already supplies, so the baseline of 3 applies.

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 and resource: 'Traverse the citation graph from one or more seed papers', and immediately scopes it as BFS with depth hops returning nodes and directed edges. This distinguishes it from single-hop siblings like get_citations and get_references by making the multi-hop traversal explicit.

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?

Clearly frames when the tool is heavy ('anything past a shallow, narrow graph runs long') and routes the agent to get_job_result for polling. However, it never explicitly contrasts with the closest siblings (get_citations, get_references, find_bridge_papers), leaving the choice between single-hop and graph traversal to inference.

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