--- title: "Tool Catalog" description: "Complete reference for all 45 ScholarXIV MCP tools with parameters and examples." canonical_url: "https://scholarxiv.com/developers/docs/mcp/tools" markdown_url: "https://scholarxiv.com/developers/docs/mcp/tools.md" --- > For the complete documentation index, see [llms.txt](/llms.txt). # Tool Catalog URL: /developers/docs/mcp/tools LLM index: /llms.txt Description: Complete reference for all 45 ScholarXIV MCP tools with parameters and examples. Related: mcp, mcp/quickstart, mcp/examples # Tool Catalog The ScholarXIV MCP server exposes **45 tools** across 7 categories. Keys without federated-search or health access see fewer tools. ## Overview | Category | Tools | Description | | ----------------------------------------- | ----- | ----------------------------------------------------------- | | [Search & Discovery](#search--discovery) | 5 | Find papers and collections | | [Paper Operations](#paper-operations) | 9 | Read, bookmark, like, and comment on papers | | [Collections](#collections) | 10 | Create, update, and manage paper collections | | [Collection Members](#collection-members) | 5 | Manage who can access collections | | [Chats](#chats) | 4 | AI research chat and conversation history | | [Account](#account) | 3 | Subscription info, plans, and reading digests | | [Health](#health) | 9 | Health chat, medication references, and trackers (Go plan+) | --- ## Search & Discovery ### `search_papers` Search the ScholarXIV database of 3M+ academic papers. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------ | | `query` | string | Yes | Search query text | | `search_filter` | enum | No | Field to search: `all`, `ti`, `au`, `abs`, `cat`, `id`, `co`, `jr`, `rn` | | `limit` | number | No | Max results (1-50, default 10) | | `page` | number | No | Page number, 0-indexed (default 0) | | `sort_by` | enum | No | `relevance`, `lastUpdatedDate`, `submittedDate` (default `relevance`) | | `sort_order` | enum | No | `ascending`, `descending` (default `descending`) | ``` search_papers(query: "protein folding", limit: 5) ``` ### `federated_search` Search multiple academic sources at once (arXiv, OpenAlex, PubMed, Europe PMC, medRxiv, bioRxiv, ChemRxiv, ClinicalTrials.gov, Semantic Scholar, Crossref, and ChinaXiv) and get a merged, deduplicated list. **Requires the Go plan or above.** | Parameter | Type | Required | Description | | ---------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | Search query text | | `sources` | string[] | No | Which sources to search: `arxiv`, `openalex`, `pubmed`, `europepmc`, `medrxiv`, `biorxiv`, `clinicaltrials`, `semantic_scholar`, `crossref`, `chinarxiv`, `chemrxiv` (default: all) | | `limit` | number | No | Max results **per source** (1-50, default 10) | | `page` | number | No | Page number, 0-indexed, applied per source (default 0) | | `fromYear` | number | No | Only include papers published in or after this year | | `toYear` | number | No | Only include papers published in or before this year | | `sort` | enum | No | `relevance`, `date`, or `citations` | Paging is per-source: each page returns up to `limit` results from every selected source, and the response footer reports per-source counts plus whether more results remain. ``` federated_search(query: "retrieval augmented generation", sources: ["arxiv", "openalex"], limit: 5) ``` ### `search_collections` Search public paper collections created by other researchers. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------- | | `query` | string | Yes | Search query for collection titles/descriptions | | `page` | number | No | Page number (default 1) | ``` search_collections(query: "machine learning") ``` ### `discover_collections` Browse random public collections from other researchers. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------- | | `page` | number | No | Page number (default 1) | ``` discover_collections(page: 1) ``` ### `get_recommended_collections` Get personalized collection recommendations based on your reading profile. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------- | | `page` | number | No | Page number (default 1) | ``` get_recommended_collections(page: 1) ``` --- ## Paper Operations ### `get_paper` Get full metadata for a specific paper by arXiv ID or DOI. | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------- | | `paper_id` | string | Yes | arXiv ID (e.g. "2301.12345") or DOI | ``` get_paper(paper_id: "2502.03725") ``` ### `get_paper_full_text` Read a paper's full text in chunks when the abstract is insufficient. Available to paid plans. | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------------------------------- | | `paper_id` | string | Yes | arXiv ID or arXiv URL | | `offset` | number | No | Character offset for the next chunk | | `max_chars` | number | No | Characters to return (1,000–60,000) | ``` get_paper_full_text(paper_id: "2502.03725", max_chars: 10000) ``` ### `bookmark_paper` Toggle bookmark state on a paper. | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ---------------------- | | `paper_id` | string | Yes | Paper ID (extractedID) | ``` bookmark_paper(paper_id: "2502.03725") ``` ### `like_paper` Toggle like state on a paper. | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ---------------------- | | `paper_id` | string | Yes | Paper ID (extractedID) | ``` like_paper(paper_id: "2502.03725") ``` ### `get_bookmarked_papers` Get all papers bookmarked by the authenticated user. ``` get_bookmarked_papers() ``` ### `get_liked_papers` Get all papers liked by the authenticated user. ``` get_liked_papers() ``` ### `get_paper_comments` Get community comments and discussion for a specific paper. | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ---------------------- | | `paper_id` | string | Yes | Paper ID (extractedID) | ``` get_paper_comments(paper_id: "2502.03725") ``` ### `comment_on_paper` Post a comment on a paper. | Parameter | Type | Required | Description | | ----------- | ------ | -------- | -------------------------------------- | | `paper_id` | string | Yes | Paper ID (extractedID) | | `comment` | string | Yes | The comment text to post | | `parent_id` | string | No | Parent comment ID for threaded replies | ``` comment_on_paper(paper_id: "2502.03725", comment: "Great paper on optimal control!") ``` ### `delete_comment` Delete a comment you own. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------------------- | | `comment_id` | string | Yes | Comment ID (MongoDB ObjectId) | | `paper_id` | string | Yes | Paper ID (extractedID) | ``` delete_comment(comment_id: "507f1f77bcf86cd799439011", paper_id: "2502.03725") ``` --- ## Collections ### `list_collections` List all collections you are a member of. ``` list_collections() ``` ### `create_collection` Create a new paper collection. | Parameter | Type | Required | Description | | ------------- | -------- | -------- | ---------------- | | `title` | string | Yes | Collection title | | `description` | string | No | Description | | `tags` | string[] | No | Tags | ``` create_collection(title: "ML Papers", tags: ["machine learning", "neural networks"]) ``` ### `update_collection` Update a collection's title, description, tags, or visibility. | Parameter | Type | Required | Description | | --------------- | -------- | -------- | --------------------- | | `collection_id` | string | Yes | Collection ID | | `title` | string | No | New title | | `description` | string | No | New description | | `tags` | string[] | No | New tags | | `visibility` | enum | No | `public` or `private` | ``` update_collection(collection_id: "6a0e05bc...", visibility: "public") ``` ### `delete_collection` Delete a collection and all its papers. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------- | | `collection_id` | string | Yes | Collection ID | ``` delete_collection(collection_id: "6a0e05bc...") ``` ### `get_collection_detail` Get full details of a collection including all papers. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------- | | `collection_id` | string | Yes | Collection ID | ``` get_collection_detail(collection_id: "6a0e05bc...") ``` ### `get_collection_papers` Get all papers in a collection. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------- | | `collection_id` | string | Yes | Collection ID | ``` get_collection_papers(collection_id: "6a0e05bc...") ``` ### `add_paper_to_collection` Add a paper to a collection. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ---------------------- | | `collection_id` | string | Yes | Collection ID | | `paper_id` | string | Yes | Paper ID (extractedID) | ``` add_paper_to_collection(collection_id: "6a0e05bc...", paper_id: "2502.03725") ``` ### `remove_paper_from_collection` Remove a paper from a collection. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ---------------------- | | `collection_id` | string | Yes | Collection ID | | `paper_id` | string | Yes | Paper ID (extractedID) | ``` remove_paper_from_collection(collection_id: "6a0e05bc...", paper_id: "2502.03725") ``` ### `join_collection` Join a public collection as a viewer. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------- | | `collection_id` | string | Yes | Collection ID | ``` join_collection(collection_id: "6a0dffe2...") ``` ### `leave_collection` Leave a collection you are a member of. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------- | | `collection_id` | string | Yes | Collection ID | ``` leave_collection(collection_id: "6a0dffe2...") ``` --- ## Collection Members ### `get_collection_members` List members of a collection (owner only). | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ----------------------------- | | `collection_id` | string | Yes | Collection ID | | `page` | number | No | Page number (default 1) | | `limit` | number | No | Results per page (default 10) | | `search` | string | No | Search by name or email | ``` get_collection_members(collection_id: "6a0e05bc...") ``` ### `update_member_role` Change a collection member's role (owner only). | Parameter | Type | Required | Description | | --------------- | ------ | -------- | --------------------- | | `collection_id` | string | Yes | Collection ID | | `user_id` | string | Yes | User ID of the member | | `role` | enum | Yes | `editor` or `viewer` | ``` update_member_role(collection_id: "6a0e05bc...", user_id: "user123", role: "editor") ``` ### `remove_member` Remove a member from a collection (owner only). | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------- | | `collection_id` | string | Yes | Collection ID | | `user_id` | string | Yes | User ID of the member to remove | ``` remove_member(collection_id: "6a0e05bc...", user_id: "user123") ``` ### `generate_share_token` Generate a share link token for a collection. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | -------------------- | | `collection_id` | string | Yes | Collection ID | | `role` | enum | Yes | `viewer` or `editor` | ``` generate_share_token(collection_id: "6a0e05bc...", role: "viewer") ``` ### `revoke_share_token` Revoke a viewer or editor share link for a collection. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | -------------------- | | `collection_id` | string | Yes | Collection ID | | `role` | enum | Yes | `viewer` or `editor` | ``` revoke_share_token(collection_id: "6a0e05bc...", role: "viewer") ``` --- ## Chats ### `list_chats` List all chat conversations. ``` list_chats() ``` ### `get_chat_history` Retrieve all messages from a specific chat. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------- | | `chat_id` | string | Yes | Chat ID (from list_chats) | ``` get_chat_history(chat_id: "6a39d86d...") ``` ### `delete_chat` Delete a chat and its history. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `chat_id` | string | Yes | Chat ID | ``` delete_chat(chat_id: "6a39d86d...") ``` ### `research_chat` Ask the ScholarXIV AI a research question. The AI can search papers, use web search, and execute Python code. | Parameter | Type | Required | Description | | ------------------ | ------- | -------- | ------------------------------------------- | | `question` | string | Yes | Your research question | | `chat_id` | string | No | Existing chat ID to continue a conversation | | `selected_papers` | string | No | Paper context the AI can reference | | `selected_texts` | string | No | Highlighted text passages to reference | | `is_deep_research` | boolean | No | Enable deep research mode (default false) | | `model` | string | No | AI model to use (default: auto) | ``` research_chat(question: "What are the latest advances in protein folding?", is_deep_research: true) ``` --- ## Account ### `get_subscription_info` Get your current subscription plan, rate limits, and API usage. ``` get_subscription_info() ``` ### `get_plans` List all available subscription plans with pricing. ``` get_plans() ``` ### `get_pulse` View AI-generated digests of your bookmarked and liked papers with insights. ``` get_pulse() ``` --- ## Health Health tools are research-grounded health features: the health assistant chat, FDA/RxNorm medication references, the health profile, and symptom trackers. **All Health tools require the Go plan or above.** ### `health_chat` Ask the ScholarXIV Health assistant a health question. Answers are grounded in real medical research (PubMed/MEDLINE, medRxiv & bioRxiv preprints, ClinicalTrials.gov, and biomedical literature) and tailored to the user's health profile (conditions, medications, allergies). Health chats are stored separately from research chats. | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------------------- | | `question` | string | Yes | Your health question | | `chat_id` | string | No | Existing health chat ID to continue a conversation | | `model` | string | No | AI model to use (default: the plan's health model — large context, reads images and PDFs) | ``` health_chat(question: "What does research say about combining ibuprofen and metformin?") ``` ### `get_medication_reference` Fetch the complete reference for one brand or generic medicine: RxNorm concept identity, active ingredients, properties and NDCs, plus openFDA product metadata and every available FDA label section. Product information only — not a diagnosis, dose recommendation, or interaction severity score. | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------- | | `name` | string | Yes | One medication name, either brand or generic | ``` get_medication_reference(name: "Advil") ``` ### `get_health_profile` Get the user's health profile (birth date, sex, conditions, medications, allergies, lifestyle, goals) and whether consent for health data processing has been given. ``` get_health_profile() ``` ### `save_health_profile` Save or update the health profile. `consent_given` must be `true` — health data is a special category under GDPR Art. 9, and the profile is only stored after explicit consent. Medication names are normalized against RxNorm on save. | Parameter | Type | Required | Description | | ------------------ | -------- | -------- | ------------------------------------------------------- | | `consent_given` | boolean | Yes | Must be `true` to save | | `birth_date` | string | No | `YYYY-MM-DD`; age is derived from it | | `age` | number | No | Years (0-120); used only when no `birth_date` | | `sex` | string | No | Free text: female, male, intersex, or self-described | | `height_cm` | number | No | Height in centimeters | | `weight_kg` | number | No | Weight in kilograms | | `unit_system` | enum | No | `metric` or `imperial` (display preference) | | `blood_type` | enum | No | `A+`, `A-`, `B+`, `B-`, `AB+`, `AB-`, `O+`, `O-` | | `pregnancy_status` | enum | No | `not_applicable`, `pregnant`, `breastfeeding`, `trying` | | `conditions` | string[] | No | Ongoing diagnoses or conditions | | `medications` | string[] | No | Current medications, brand or generic | | `supplements` | string[] | No | Vitamins, supplements, herbal remedies | | `allergies` | string[] | No | Drug, food, or other allergies | | `surgeries` | string[] | No | Past surgeries and procedures | | `family_history` | string[] | No | Conditions that run in the family | | `smoking_status` | enum | No | `never`, `former`, `occasional`, `daily` | | `alcohol_use` | enum | No | `none`, `occasional`, `weekly`, `daily` | | `activity_level` | enum | No | `sedentary`, `light`, `moderate`, `active`, `athlete` | | `sleep_hours` | number | No | Typical hours per night (0-24) | | `diet` | string | No | Dietary pattern and restrictions | | `goals` | string[] | No | What the user is working toward | | `notes` | string | No | Anything else the assistant should know | ``` save_health_profile(consent_given: true, birth_date: "1990-06-15", medications: ["lisinopril"], allergies: ["penicillin"]) ``` ### `delete_health_profile` Withdraw consent and delete the health profile and all health trackers. Everything is deleted outright — nothing is soft-deleted or retained. | Parameter | Type | Required | Description | | --------- | ------- | -------- | -------------------------------- | | `confirm` | boolean | Yes | Must be `true`; there is no undo | ``` delete_health_profile(confirm: true) ``` ### `list_health_trackers` List active health trackers (health logs) with all recorded entries — severity, symptoms, temperature, and activity impact over time. Returns `consentGiven: false` and no trackers when no health profile with consent exists. ``` list_health_trackers() ``` ### `create_health_tracker` Create a new health tracker (health log) — an acute illness, a pregnancy, or a custom log. Requires an existing health profile with consent (`save_health_profile`). | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------- | | `title` | string | Yes | Name for the log, e.g. "Flu-like illness" | | `kind` | enum | Yes | `acute`, `pregnancy`, or `custom` | ``` create_health_tracker(title: "Flu-like illness", kind: "acute") ``` ### `add_health_tracker_entry` Record one entry in a health tracker, appended with the current timestamp. | Parameter | Type | Required | Description | | ------------------ | -------- | -------- | ----------------------------------------------- | | `tracker_id` | string | Yes | Health tracker ID (from list_health_trackers) | | `severity` | number | No | 0 (none) to 10 (worst) | | `symptoms` | string[] | No | Symptoms experienced, e.g. `["fever", "cough"]` | | `temperature` | number | No | Reading in the `temperature_unit` unit | | `temperature_unit` | enum | No | `celsius` or `fahrenheit` (default `celsius`) | | `activity_impact` | enum | No | `none`, `limited`, `unable` (default `none`) | | `notes` | string | No | Optional notes | ``` add_health_tracker_entry(tracker_id: "ABc123...", severity: 6, symptoms: ["fever", "cough"], temperature: 38.2) ``` ### `delete_health_tracker` Delete a health tracker and all its entries. Requires the health tracker to belong to the user. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------------- | | `tracker_id` | string | Yes | Health tracker ID to delete | ``` delete_health_tracker(tracker_id: "ABc123...") ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages. Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md). Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).