Tools¶

All research tools are prefixed research_ and grouped by provider (research_arxiv_*, research_europepmc_*), with identifier resolution exposed as a single grouping-level tool, research_resolve_identifier, that isn't tied to one provider. See the Software Requirements Specification — specifically Architecture and Interface specification — for the full design rationale and exact wire-level schemas; this page is a practical, per-tool reference.

Errors¶

A tool failure surfaces as an MCP ToolError — a plain error response carrying a human-readable message (Error calling tool '<name>': <detail>), not a structured field a caller can branch on programmatically; there is no {"error": "<code>", ...} envelope. The categories below name which condition produced a given failure, for reference — they aren't literal response fields. See Interface specification → Conventions for the exception type each one maps to.

arXiv tools¶

All arXiv tools share a single outbound request queue, serialised to arXiv's documented limit of one request per 3 seconds.

Europe PMC tools¶

There is no research_europepmc_list_top_n — Europe PMC has no single classification field equivalent to arXiv's subject categories.

Europe PMC publishes no numeric rate limit; the provider self-imposes the same one-request-per-3-seconds policy as arXiv, through its own separate queue.

Discovery tool¶

v3 — see Discovery. Not a per-provider tool: research_discovery sits in front of OpenAlex's /works search.semantic parameter, ranking external, not-yet-fetched candidates by embedding similarity rather than keyword overlap.

Authenticated via PRIORIS_MCP_OPENALEX_API_KEY, sent as OpenAlex's own api_key query parameter, not the deprecated mailto polite-pool parameter. OpenAlex has required this key on every request since 2026-02-13; if it isn't configured, the tool fails with configuration_error rather than making an unauthenticated call. See research://openalex/work-types in Resources for the reference vocabulary behind a hit's own work_type field — it isn't a filter research_discovery itself accepts.

Identifier resolution¶

This is the one capability exposed at the grouping level rather than per-provider — see Architecture → Identifier routing.

Local filesystem tools¶

Deliberately narrower than the arXiv/Europe PMC tool sets — no search, listing, metadata, or identifier resolution for this source (see Architecture → Local filesystem source). None of the five tools is subject to rate limiting — there's no outbound network request to throttle.

Storage management tools¶

Grouping-level, like research_resolve_identifier — not split per provider, since none of the three tools validates anything provider-specific (see Architecture → list_fetched/delete_fetched). See Vector search for the full semantic-search design and Interface specification → research_search_fetched for exact wire-level fields.

Vector index reconciliation¶

Corpus-wide vector reindexing after an embedding-model change (PRIORIS_MCP_EMBEDDING_MODEL) runs automatically at server startup — there is no tool to trigger it — see Vector search → Reconciliation runs automatically at server startup and ADR-00030. Its live progress is readable via the research://vector-index/rebuild-status resource: {"documents": {"total": <int>, "pending": <int>, "succeeded": <int>, "failed": <int>, "cancelled": <int>, "active": <bool>}, "notes": {...}}, where total/pending/succeeded/failed/cancelled count only the documents/notes the most recent reconciliation run decided needed rebuilding (a corpus already fully ready under the configured model reports all zeros; total == pending + succeeded + failed + cancelled always holds), and active (pending > 0) is a convenience field so a caller doesn't have to derive it. A nonzero failed with active=false is a terminal state — no in-process retry runs; the item stays failed until the next server restart re-derives and re-schedules it — see ADR-00031. This state is process-local and in-memory, not a durable job log — it resets to a fresh count on every server restart, the same "derived transiently, self-healing on restart" property index_status's own building value already has (see Vector search → Index status is per-document/note).

Notes tools¶

Notes are persisted separately from fetched-document storage — one user-authored note against a document, or against a bare identifier predating any fetch — see Notes storage. A note's exportable file representation is available as a resource; see Resources.

Caching and rate limiting¶

research_*_search, research_*_list_top_n, research_*_fetch_metadata, and research_discovery responses are covered by the server's response-caching middleware (PRIORIS_MCP_RESPONSE_CACHE_TTL, see Configuration). fetch_full_text and parse_full_text are backed by persistent storage instead (see Resources) — a repeat call returns the already-persisted content (served_from_storage: true) without a second network fetch or parse.

Response shapes are still evolving alongside the SRS — prefer the Interface specification as the source of truth for exact wire-level fields.

research_localfile_fetch_full_text/research_localfile_parse_full_text, research_localfile_begin_upload/research_localfile_upload_chunk/research_localfile_finalize_upload, and research_list_fetched/research_delete_fetched/research_search_fetched are excluded from the response cache entirely — the local file source re-hashes file content on every call by design, the chunked-upload tools mutate in-memory session state that must never be served stale, and list/delete/search must reflect live storage state. The five research_notes_* tools are excluded for the same reason as list/delete/search: notes are mutable (create/update/delete), so a cached tool response could return stale or deleted data. The notes://{note_id}/export resource is likewise never served from the response cache, for the same reason — see Resources.