Skip to main content
Glama

openalex-mcp-server

by io.github.cyanheads

Openalex Analyze Trends

openalex_analyze_trends
Read-onlyIdempotent

Aggregate OpenAlex entities into groups and count them. Use for trend analysis (group works by publication_year), distribution analysis (group by oa_status, type, country), and comparative analysis (group by institution or topic). Combine with filters to scope the analysis. Returns up to 200 groups per page — use cursor pagination for fields with many distinct values.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
orderNoSort order for groups. Omit or pass "count" (default) to return the top-N groups by count descending — no further pages. Pass "key" to enumerate all distinct values in key-ascending order with cursor pagination. Use "key" only when you need a full traversal; most analysis calls want "count".
cursorNoPagination cursor from a previous response. Only relevant when order is "key" — count-descending results have no next page. Pass the next_cursor from the previous response to advance.
filtersNoFilter criteria (same syntax as openalex_search_entities filters). Narrows the population before aggregation. For full-text within filters, use abstract.search, title.search, or default.search — there is no bare 'search' filter key. Example: group works by year filtered to a specific topic.
group_byYesField to group by. Works examples: "publication_year", "type", "oa_status", "primary_topic.field.id", "authorships.institutions.country_code", "is_retracted". Authors: "last_known_institutions.country_code", "has_orcid". Sources: "type", "is_oa", "country_code". Not all fields support group_by — check entity docs if unsure.
per_pageNoMaximum groups per page (1-200). Default 200 (the upstream cap). A real top-N knob when order is count (the default) — reduce to return only the highest-count groups.
entity_typeYesEntity type to aggregate.
include_unknownNoInclude a group for entities with no value for the grouped field. Hidden by default.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
echoNoCompact echo of the input criteria (entity_type, group_by, filters) — surfaces what was actually requested when no groups are returned.
metaNoAggregation metadata.
errorNoPresent when the call failed. Absent on success.
budgetNoWhat this call cost against the OpenAlex daily budget and what is left of it — weigh `remainingUsd` against `costUsd` before enumerating every group with `order: "key"`. Absent when OpenAlex omitted the accounting headers.
groupsNoAggregation groups with counts.
noticeNoGuidance notice. Set when no groups are returned (recovery suggestions) or when the page is full and more groups likely exist (truncation signal with narrowing advice). Absent otherwise.
totalCountNoTotal entities matching the filters before grouping (across all pages).

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering the safety and idempotency profile. The description adds behavioral context beyond annotations: the pagination limit (200 groups per page), the difference between 'count' and 'key' ordering (count returns top-N with no pagination, key returns full traversal with cursor), and the note that 'key' is only for full traversals. Slight deduction because it doesn't explicitly state what 'upstream cap' means, but the disclosures are solid.

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 description is concise and front-loaded: it leads with the core action and use cases, then the filter combination hint, then a one-line note about pagination. The schema descriptions are also well-structured, with parameter descriptions that flow from use to exceptions. Minor redundancy: 'key-ascending order with cursor pagination' appears twice (in description and schema), but it's not wasteful.

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 that the output schema is provided (not shown here but noted as present), and the annotations cover safety and idempotency, the description covers all essential aspects: what it does, when to use it, how to paginate, how to filter, and what to expect. The explanation of 'order' helps avoid misuse. For a complex aggregation tool with 7 parameters, this is thorough and self-sufficient.

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% (all 7 parameters have descriptions). The description adds value by explaining the grouping context (e.g., 'group works by publication_year') and highlighting the missing 'search' filter key (clarifying there's no bare 'search' key, only abstract.search etc.). The 'order' parameter description is particularly rich, explaining the behavioral consequences of each value. This goes beyond what a typical schema description provides.

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 clearly states the tool's purpose: 'Aggregate OpenAlex entities into groups and count them.' It uses a specific verb ('aggregate') and resource ('OpenAlex entities'), and immediately signals the key use case — trend, distribution, and comparative analysis. It also names sibling tools indirectly by mentioning 'Combine with filters' and referencing openalex_search_entities filters in the schema, distinguishing this aggregation tool from the search tool.

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?

The description explicitly says when to use this tool: 'Use for trend analysis... distribution analysis... comparative analysis.' It mentions combining with filters, and the schema adds a detailed explanation of the 'order' parameter, including when to use 'count' vs 'key' and the implications for pagination. This provides a clear decision path for the agent.

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