Skip to main content
Glama
Sign In
openalex-mcp

openalex-mcp

by ckgerteis
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

oa_author_works

Read-onlyIdempotent

Fetch works for a specific author by OpenAlex ID or ORCID. Apply year filters and sort by citation count or publication date.

Instructions

Works by one author, with optional year filter and sort. Returns the unified envelope. A filter on an identifier, not a term search.

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": {
      "params": "<params>"
    },
    "name": "oa_author_works"
  }
}

Input Schema

NameRequiredDescriptionDefault
paramsYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.3.0
    • addedInput schema / $defs / AuthorWorksInput / properties / per_page / description
      Added value: +"Results per page (1-200). OpenAlex charges per call, not per result, so a sweep that will page through results should set 200."
  2. First observedv1.1.0

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. Beyond that the description adds only 'Returns the unified envelope', which is unexplained jargon, and the year/sort options that the schema also carries. No pagination, cost, or result-cap behavior is mentioned despite the per-call pricing note living in the schema.

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?

Three short sentences, front-loaded with purpose and then the disambiguation rule, with no filler. 'Returns the unified envelope' is the one line that spends words without conveying meaning to a caller who lacks the internal vocabulary.

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?

With an output schema present and rich annotations, the description need not explain return shape, and it correctly focuses on scope and the identifier-vs-term distinction. The main residual gap is that an agent gets no hint about paging behavior or result volume when sweeping an author's works.

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?

The reported 0% coverage is largely a measurement artifact of the single 'params' wrapper; the nested AuthorWorksInput properties (sort_by values, year_from/year_to, per_page ceiling and cost advice, author_id accepting ID or ORCID) are documented in the schema itself. The description echoes 'year filter and sort' without adding anything the schema does not already say.

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?

'Works by one author, with optional year filter and sort' names the resource (works) and its scoping (single author), and the closing line 'A filter on an identifier, not a term search' separates it from the term-search siblings such as oa_search_works. It stops short of naming the sibling explicitly and uses a verbless fragment rather than a clear action verb.

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?

The phrase 'A filter on an identifier, not a term search' gives a genuine when-not rule that steers the agent away from oa_search_works toward this tool when a known author ID exists. It does not, however, name that alternative or state prerequisites (e.g. that an ID or ORCID must already be resolved, possibly via oa_search_authors).

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

Deploy Server

Other Tools