Skip to main content
Glama

openalex-mcp-server

by io.github.cyanheads

Openalex Get Citation Graph

openalex_get_citation_graph
Read-onlyIdempotent

Walk the citation graph one hop from a seed work. Direction picks the edge: incoming citations (cites), the seed's own references (cited_by), or OpenAlex's algorithmically-related works (related_to). Note: direction follows OpenAlex's filter convention, which inverts the common English reading — cites returns works that cite the seed; cited_by returns works the seed cites. Results use the works schema; combine with filters/sort to narrow further.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sortNoSort field. Prefix with "-" for descending. Comma-separate for a multi-key sort, applied left to right, with the "-" prefix set per key ("-publication_year,cited_by_count" sorts by year descending, then citations ascending). Common: "cited_by_count", "-publication_date". Default is OpenAlex relevance.
cursorNoPagination cursor from a previous response. Pass to get the next page.
selectNoOpenAlex work field names to return. Always returned: id, display_name. Defaults to the curated works select if omitted.
filtersNoAdditional filters to narrow the graph, same syntax as openalex_search_entities. Example: publication_year=">2020", is_oa="true". Do not include cites/cited_by/related_to — those are set by the `direction` parameter.
seed_idYesSeed work identifier. Accepts OpenAlex ID ("W2741809807"), DOI ("10.1038/nature12373" or full URL), PMID, or PMCID. Use openalex_resolve_name first if you only have a title.
per_pageNoResults per page (1-100). Default 25.
directionYes"cites": works that cite seed_id (incoming citations). "cited_by": works that seed_id cites (its reference list). "related_to": OpenAlex algorithmically-related works (~8-30 typical, may be empty for less-cited seeds).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
echoNoCompact echo of seed_id, direction, filters, sort — surfaces what was actually queried when no edges are returned.
metaNoResult metadata including pagination.
errorNoPresent when the call failed. Absent on success.
budgetNoWhat this call cost against the OpenAlex daily budget and what is left of it. Price a full walk before committing to it: `totalCount` ÷ `per_page` × `costUsd` against `remainingUsd`. Absent when OpenAlex omitted the accounting headers.
noticeNoRecovery guidance when no edges are returned — suggests verifying the seed_id, broadening filters, or trying a different direction. Absent when results are present.
resultsNoWorks on the citation graph in this direction.
totalCountNoTotal edges from seed_id in this direction across all pages.

TDQS

A5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so no repetition is needed. The description adds valuable behavioral context beyond annotations: the edge-direction inversion, the typical count range for related_to (8-30, possibly empty), and the default curated select. Nothing contradicts annotations.

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?

A single paragraph, front-loaded with the core action and immediately followed by the essential edge-direction clarification. Each sentence earns its place; no fluff, no redundant restatements of the schema. It efficiently conveys the most important usage constraints.

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 the tool's complexity (7 parameters, nested objects, an output schema already present), the description covers every non-obvious aspect: direction semantics, filter exclusions, seed_id alternatives, pagination hints via cursor, and the typical size of related_to. An agent has everything needed to invoke it correctly without opening the schema or sibling tools.

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

Parameters5/5

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

Schema coverage is 100%, satisfying the baseline, but the description adds meaning beyond the schema by clarifying the inverted semantics of direction, the filter restriction (no cites/cited_by/related_to), and the seed_id resolution path (use resolve_name). This materially improves an agent's ability to call it correctly.

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?

The description opens with a precise verb-object pair ('Walk the citation graph one hop from a seed work') and immediately names the three edge directions, distinguishing this tool from search_entities, which returns general works. It leaves no ambiguity about the tool's scope.

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?

It explains when to use each direction, warns about the inverted filter convention, and explicitly instructs not to include cites/cited_by/related_to in filters because direction owns those. It also suggests calling openalex_resolve_name first when only a title is available, giving concrete routing advice.

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

All openalex-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: aggregation, schema inspection, graph traversal, ID resolution, and general search. No overlap in functionality.

Naming Consistency5/5

All tools follow the 'openalex_' prefix with a consistent verb_noun pattern (analyze_trends, describe_fields, get_citation_graph, resolve_name, search_entities).

Tool Count5/5

With 5 tools, the set is well-scoped for the OpenAlex API, covering the essential operations without redundancy or bloat.

Completeness5/5

The tools cover the full range of typical OpenAlex interactions: searching, resolving names, aggregating trends, exploring citations, and obtaining field metadata. No obvious gaps.

Resources