Tools Reference

PRIMA Scholar

PRIMA Scholar’s two MCP servers give Claude seventeen tools. The search server, prima-scholar-search, has five tools that reach the ten academic databases. The library server, prima-scholar-library, has twelve tools that manage your research library on your own computer. This page lists every tool at version 2.2.1 with its parameters, defaults and what it returns.

You do not call these tools yourself. Claude calls them when you ask a research question or run a command such as /scholar or /library. This page helps you phrase a request precisely and read what comes back.

Every tool returns its result as JSON text. A required parameter that is missing stops the tool with a message such as query is required.

Search Server

Tool	What it does
`scholar_wizard`	Reads a query and suggests disciplines, databases and refinement questions
`scholar_search`	Searches up to ten databases at once and merges the results
`scholar_get_paper`	Fetches one paper by its identifier
`scholar_citations`	Lists the papers that cite a paper, or the papers it cites
`scholar_full_text`	Returns the full text of an open access paper, or a download link

scholar_wizard

Reads your research query and suggests how to search before any database is contacted. The wizard works on your computer from a fixed list of discipline keywords and sends nothing to any database.

Parameter	Type	Required	What it does
`query`	Text	Yes	Your research query or topic

The result has three parts.

Part	Contents
`analysis`	The disciplines detected, the databases suggested for them and a confidence of `high`, `medium` or `low`
`questions`	Questions to put to you, each with an ID, options and a default. See the next table
`suggestedSearch`	A ready search with the query, the suggested databases, open access only set to true, the last ten years, preprints included and 10 results per database

Question ID	Asks	Default	When it appears
`discipline`	Which discipline to focus on	The first detected discipline, or `both` when two are detected	When confidence is low, the query is multidisciplinary, or more than one discipline is detected
`access`	Open access only, or gated papers too	`open_access_only`	Always
`date_range`	Last 5, 10 or 20 years, or any date	`last_10_years`	Always
`type`	Peer-reviewed only, or preprints too	`include_preprints`	When a detected discipline commonly uses preprints, or the query is multidisciplinary
`authors`	Authors to prioritise	None	Always, and optional

scholar_search

Searches the databases you choose at the same time, removes duplicates by DOI, applies your filters and sorts the results.

Parameter	Type	Required	Default	What it does
`query`	Text	Yes		Keywords, phrases or a boolean expression
`max_results`	Number	No	`10`	Results to request from each database. The total before duplicates are removed can be higher
`sources`	List	No	All ten	Any of `pubmed`, `arxiv`, `semantic_scholar`, `crossref`, `openalex`, `core`, `europe_pmc`, `eric`, `biorxiv` and `dblp`. CORE is skipped when `CORE_API_KEY` is not set
`open_access_only`	True or false	No	`false`	When true, gated papers are removed. When false, both are returned and counted separately
`year_from`	Number	No		Earliest publication year
`year_to`	Number	No		Latest publication year
`published_after`	Date	No		Papers published on or after this date, as `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. Finer than `year_from` and preferred over it
`published_before`	Date	No	Today, when `sort_by` is `date`	Papers published on or before this date, in the same formats
`sort_by`	Text	No	`open_access`	`open_access` puts open access papers first, then orders by citation count. `citations` orders by citation count. `date` puts the newest first. `relevance` keeps each database’s own ranking and takes one result from each database in turn
`venues`	List	No		Journal or publisher names to keep, matched on any part of the name and ignoring case. Applied after the search, so raise `max_results` with it
`exclude_dois`	List	No		DOIs to remove from the results, such as papers already in your library. Prefixes such as `https://doi.org/` and `doi:` are ignored when matching
`citation_style`	Text	No	All six	One of `apa7`, `harvard`, `chicago`, `vancouver`, `ieee` and `mla`

The server applies the filters in a fixed order. It removes duplicates by DOI, then gated papers if you asked for open access only, then papers outside the date window, then papers outside your venues, then the DOIs you excluded. It sorts what remains last. A paper with no date at all is kept by the date filter, so it is never dropped silently.

A date in the wrong format stops the search with a message such as published_after must be an ISO date: YYYY-MM-DD, YYYY-MM or YYYY. An unknown sort order stops it with a message listing the four allowed values.

Result field	Contents
`papers`	The papers found. See the paper fields below
`totalResults`	The number of papers after filtering
`openAccessCount` and `gatedCount`	How many papers are open access and how many are gated
`query`	The query searched
`sources`	The databases that answered
`sortBy`	The sort order used
`filtersApplied`	The date window, venues, number of DOIs excluded, year range and open access setting, where any were used
`errors`	One line for each database that failed, with its message
`missingApiKeys`	A line for CORE when it was requested without a key, with where to get one

Each paper carries these fields where the database supplies them.

Paper field	Contents
`title`, `authors`, `abstract`, `year`	The basic record. Each author has a `name` and may have `affiliations`
`publishedDate`	The publication date as `YYYY-MM-DD`, or `YYYY-MM` or `YYYY` when only part is known
`journal`, `volume`, `issue`, `pages`, `publisher`	Publication details
`doi`, `url`	The DOI and a link to the record
`source`, `sourceId`	The database the record came from and its ID there
`citationCount`, `keywords`	Citation count and keywords
`citations`	Ready-made citations, keyed by style
`openAccess`, `openAccessUrl`, `fullTextAvailable`	Whether the paper is open access, a link to the open copy and whether `scholar_full_text` can reach it

If one database fails, the search still returns the others and lists the failure under errors. If every database fails, or CORE is the only one requested and has no key, the search stops with an error. The Data Sources page describes how each database behaves.

scholar_get_paper

Fetches the full record for one paper. The server chooses the database from the form of the identifier.

Parameter	Type	Required	Default	What it does
`id`	Text	Yes		The paper’s identifier, in one of the forms below
`citation_style`	Text	No	All six	One of `apa7`, `harvard`, `chicago`, `vancouver`, `ieee` and `mla`

Identifier form	Example	Looked up in
`PMID:` and a number	`PMID:38123456`	PubMed
`ARXIV:` and an arXiv ID	`ARXIV:2301.12345`	arXiv
An OpenAlex work ID or URL	`W1234567890`	OpenAlex
An ERIC number	`EJ1234567` or `ED1234567`	ERIC
A PMC ID	`PMC1234567`	Europe PMC
A DOI, plain or with `DOI:`	`10.1207/S15327965PLI1104_01`	Semantic Scholar, then CrossRef if Semantic Scholar fails
Anything else	A Semantic Scholar paper ID	Semantic Scholar

There is no route to CORE or DBLP, so for a paper found there, use its DOI. The result is one paper with the fields listed under scholar_search.

scholar_citations

Lists the papers that cite a given paper, or the papers it cites. This tool uses the Semantic Scholar citation graph only.

Parameter	Type	Required	Default	What it does
`paper_id`	Text	Yes		A Semantic Scholar ID, `DOI:` and a DOI, `ARXIV:` and an arXiv ID, or `PMID:` and a number
`direction`	Text	No	`citations`	`citations` for later papers that cite this one, `references` for the papers this one cites
`max_results`	Number	No	`10`	The number of papers to return

The result holds papers, totalResults, the direction used and source, which is always semantic_scholar. Any direction other than references returns citing papers.

scholar_full_text

Returns the text of an open access paper, or a link to download it. The server tries four routes in order and stops at the first that works.

Parameter	Type	Required	What it does
`id`	Text	Yes	A CORE work ID, with or without `CORE:`, a PMC ID, `PMID:` and a number, a DOI, or `ARXIV:` and an arXiv ID

Order	Route	Returns
1	CORE, only when `CORE_API_KEY` is set	The full text itself, if CORE holds it. This is the only route that returns text
2	Europe PMC, for PMC IDs, PMIDs and DOIs	A `downloadUrl` when Europe PMC lists the paper as open access with full text
3	arXiv, for arXiv IDs	The arXiv PDF address, built from the ID without checking that the paper exists
4	bioRxiv and medRxiv, for DOIs that start `10.1101/`	The `doi.org` link

The result holds fullText or downloadUrl, the source that answered and a message. When no route works, source is none and the message says the paper may be behind a paywall.

Library Server

Tool	What it does
`library_import`	Imports a PDF, Word, Markdown or text file
`library_import_from_search`	Adds a record from search results, with no file
`library_search`	Searches the full text of the library
`library_get_document`	Shows one record in full
`library_list`	Lists records, with filters
`library_update`	Changes the details of a record
`library_delete`	Deletes a record
`library_create_collection`	Creates a collection
`library_list_collections`	Lists collections with their record counts
`library_add_to_collection`	Adds a record to a collection
`library_tag`	Adds or removes a tag
`library_stats`	Summarises the library

Records are identified by a whole number, the document ID, which the import tools return. Authors are stored as a list written as text, for example ["Smith, J.", "Doe, A."].

library_import

Reads a file on your computer, extracts its text and adds it to the library for full-text search.

Parameter	Type	Required	What it does
`file_path`	Text	Yes	The absolute path to the file
`title`	Text	No	A title to use in place of the one detected from the file
`authors`	Text	No	Authors as a list written as text
`year`	Number	No	Publication year
`doi`	Text	No	The DOI
`notes`	Text	No	Your notes about the document

The file types accepted are .pdf, .docx, .md and .txt, and any other extension stops the import with Unsupported file type. The result holds the new id, the title, the fileType and extractedLength, the number of characters of text extracted. A very low extractedLength for a PDF means it holds images of pages with no text layer, which the library cannot read.

library_import_from_search

Adds a record from bibliographic details, such as a paper from a search, without a file.

Parameter	Type	Required	What it does
`title`	Text	Yes	The title
`authors`	Text	Yes	Authors as a list written as text
`abstract`	Text	No	The abstract
`year`	Number	No	Publication year
`doi`	Text	No	The DOI
`source_url`	Text	No	A link to the paper
`source`	Text	No	The database or platform it came from
`citations`	Object	No	Citation strings keyed by style, as `scholar_search` returns them

The record is stored with the file type reference. The result holds the new id, the title and the status added. Neither import tool checks for an existing record with the same DOI, so importing a paper twice creates two records.

library_search

Searches the title, authors, abstract, full text and notes of every record.

Parameter	Type	Required	Default	What it does
`query`	Text	Yes		Words to find. You can use `AND`, `OR`, `NOT`, quoted phrases and a `*` at the end of a word to match its beginning
`max_results`	Number	No	`10`	The number of records to return

Each result holds the id, title, authors, year, a snippet of matching text with the matched words marked, and a rank. Best matches come first. Put a hyphenated word or a word with an apostrophe in double quotes, as in "self-efficacy", because the search treats those characters as part of its query language.

library_get_document

Shows one record in full, including its extracted text and its tags.

Parameter	Type	Required	What it does
`id`	Number	Yes	The document ID

The result holds every stored field, including content, filePath, dateAdded, metadata and citations, plus a tags list. An unknown ID returns Document N not found, with the number in place of N.

library_list

Lists records, newest first, with optional filters, and leaves out each record’s full text.

Parameter	Type	Required	Default	What it does
`collection`	Text	No		Only records in this collection, matched exactly
`tag`	Text	No		Only records with this tag, matched exactly
`year`	Number	No		Only records from this year
`file_type`	Text	No		Only records of this type, such as `pdf`, `docx`, `markdown`, `text` or `reference`
`max_results`	Number	No	`20`	The number of records to return
`offset`	Number	No	`0`	The number of records to skip, for paging through a long list

library_update

Changes the details of a record, and only the fields you give are changed.

Parameter	Type	Required	What it does
`id`	Number	Yes	The document ID
`title`	Text	No	A new title
`authors`	Text	No	New authors, as a list written as text
`notes`	Text	No	New notes, which replace the old ones
`year`	Number	No	A new year
`doi`	Text	No	A new DOI
`abstract`	Text	No	A new abstract

The result holds the id and a status of updated or no changes. The tool cannot change the source link, the file path or the extracted text.

library_delete

Deletes a record permanently, with its search entry, tags and collection memberships.

Parameter	Type	Required	What it does
`id`	Number	Yes	The document ID

The original file on your computer is not touched. The result has the status deleted, or not found for an unknown ID.

library_create_collection

Creates a named collection for grouping records.

Parameter	Type	Required	What it does
`name`	Text	Yes	The collection name, which must be unique
`description`	Text	No	What the collection is for

The result holds the new collection’s id, its name and the status created. A name that already exists stops the tool with UNIQUE constraint failed: collections.name.

library_list_collections

Lists every collection in name order and takes no parameters. Each entry holds the id, name, description, dateCreated and documentCount.

library_add_to_collection

Adds a record to an existing collection.

Parameter	Type	Required	What it does
`document_id`	Number	Yes	The document ID
`collection_name`	Text	Yes	The collection’s name, matched exactly

The result has the status added, or already in collection. A name that matches no collection returns Collection "name" not found, and the tool does not create it. There is no tool to remove a record from a collection.

library_tag

Adds a tag to a record, or removes one. A tag that does not exist yet is created when you first add it.

Parameter	Type	Required	What it does
`document_id`	Number	Yes	The document ID
`tag_name`	Text	Yes	The tag. Tags are case-sensitive, so `Burnout` and `burnout` are two tags
`action`	Text	Yes	`add` or `remove`

The result holds the document ID, the tag, the action and success, which is false when the tag was already on the record or was not there to remove.

library_stats

Summarises the library and takes no parameters. The result holds the total number of records, counts by file type and by year, the twenty most used tags with their counts, and the number of collections.