Rivul Atlas MCP tool reference

01search_papers

Searches the Rivul Index and returns structured scholarly metadata. The tool is read-only and does not modify anything in your workspace. Each call spends 2 MCP credits regardless of how many records come back.

Only the parameters below are accepted. An unrecognized parameter is rejected rather than ignored, so a typo fails loudly instead of silently changing your search. When both are supplied, year_min must not be greater than year_max.

{
  "query": "retrieval-augmented generation",
  "limit": 5,
  "sort": "most_cited",
  "year_min": 2020,
  "open_access_only": true
}

02What a search returns

A result carries a list of works and a meta block describing the page you received. Only openalex_id, title, authors, and is_oa are always present; the rest appear when the underlying record has them, so treat any other field as optional in your own code.

A record is a discovery lead. It tells you a paper exists and where to find it, not that the paper supports a claim you are about to make.

03Why a field can be missing

Atlas normalizes every record before publishing it, and a value that does not survive normalization is left out of the record rather than returned as null or an empty string. That is why a result can carry four keys and still be correct.

Text is HTML-entity decoded and its whitespace collapsed, so a title stored as A & B is published as A & B. A string that is empty after that is dropped. A URL is dropped unless it parses and uses http or https, so a malformed oa_url disappears even though the index sent one. A number is dropped unless it is a non-negative whole number, which is why a cited_by_count of 0 is kept.

is_oa behaves differently from the rest: it is always present, and anything other than a literal true becomes false rather than being omitted.

04Truncated values and what that means for citation

Atlas publishes metadata and links. It does not host or redistribute full text, so a long value is shortened rather than returned whole. The same bounds apply on every channel: MCP, the REST API, and the console all return identical records, because one shared function normalizes them before either adapter sees them.

Two of these bounds change what the data means rather than just its length. The snippet is an abstract excerpt cut at 1,500 characters, not the abstract. The author list stops at eight names.

The response does not tell you whether either was shortened. There is no author count and no truncation flag, so eight names can mean a paper with eight authors or a paper with eight hundred. Do not build a bibliography from the authors field without confirming the author list against the DOI or landing page. Atlas is a discovery surface; the source record remains the authority for anything you cite.

05Paging through results

The meta block describes the page you received. Use offset, page_size and next_offset rather than guessing, and remember that every page costs another 2 credits.

snapshot_at and generation_id identify which index build answered you, which is what makes a search reproducible later. Record them alongside a result set you intend to cite.

06usage_status

Returns the approved workspace's current MCP allowance. It takes no parameters, is read-only and idempotent, and never spends a credit, so it is always safe to call when you are unsure whether a connection still works.

The response names the workspace, the plan, the billing period as a UTC calendar month, and the credits used, allowed, and remaining for the MCP channel.

{
  "usage": {
    "workspace_id": "...",
    "plan": "...",
    "period": "2026-09",
    "mcp": { "used": 8, "limit": 1000, "remaining": 992 }
  }
}

07Errors you can get back

Insufficient scope. The grant is missing search:read or usage:read. The error names the scope it needs. Authorize again and approve both read-only scopes.

Invalid parameters. A value fell outside the ranges above, or an unrecognized parameter was sent. No credits are spent on a rejected call.

Invalid key. A dedicated MCP key that has been revoked returns HTTP 401 Invalid Rivul Atlas key. This is distinct from running out of allowance.

Quota exhausted. The workspace has spent its MCP credits for the current period. Read usage_status to confirm, since that call costs nothing.

Search temporarily unavailable. Atlas rejects a whole page rather than returning part of it: if the index returns more rows than the requested limit, or any row without a usable identifier and title, the call fails instead of quietly returning fewer records. The credit reserved for a failed search is refunded. Retry, and treat a persistent failure as an index problem rather than a bad query.

• See what each call costs
• Start from the MCP overview
• Read the official MCP tools specification