Swiftscholar Skill

SwiftScholar Skill (swiftscholar-skill)

This skill enables the agent to use the SwiftScholar HTTP API to search, submit, analyze, and manage academic papers.
Prefer the JSON-first /api/tools/* endpoints instead of deprecated /api/mcp/tools/* endpoints.

Basic information:

• Base URL: https://www.swiftscholar.net
• Auth: Authorization: Bearer <API_KEY>
• Spec version: OpenAPI 3.1.0 (SwiftScholar HTTP API 1.0.0)

Never expose the API key in natural language responses; only include it in actual HTTP headers.

1. When to use this skill

Use the SwiftScholar API in these situations:

• The user wants to:
  • search academic papers (keyword or semantic/vector search)
  • submit paper URLs / PDFs for parsing
  • retrieve structured markdown analysis or raw markdown
  • manage / inspect favorites and favorite folders
  • inspect parse quotas, usage, and available analysis models

Typical trigger phrases (examples):

• “literature search”, “keyword search paper”, “semantic search paper”
• “parse this paper PDF/URL”, “analyze this paper”
• “get detailed analysis / markdown for this paper”
• “SwiftScholar favorites / favorite folders”
• “SwiftScholar account usage / quota / parse history”

2. Authentication and calling conventions

2.1 Authentication

• All /api/tools/* endpoints use Bearer tokens:
  • Header: Authorization: Bearer <SWIFTSCHOLAR_API_KEY>
• The agent must not reveal or infer the key in natural language responses.

2.2 General request conventions

• HTTP method: all tool endpoints are POST.
• Content-Type:
  • JSON requests: application/json
  • PDF upload: multipart/form-data with file as binary PDF
• Error handling:
  • JSON responses follow the ToolApiResponse structure:
    • ok: boolean (always present)
    • data: object (present on success)
    • error: string (may be present on failure)
  • After a call:
    • If ok == false or error is present, briefly explain the failure to the user and suggest next steps (e.g., adjust parameters, narrow filters).

3. Core capabilities and endpoints

This section is organized by capability, not by URL, to help the agent choose appropriate tools.
All listed endpoints live under paths./api/tools/....

3.1 Paper tags and basic browsing

1. List all paper tags (with IDs and usage counts)

   • Endpoint: POST /api/tools/paper_tags_list
   • Body: {} (no parameters)
   • Purpose:
     • When recommending tag filters or constructing complex queries, first list available tags and their IDs.

2. Paginate accessible papers

   • Endpoint: POST /api/tools/papers_paginate
   • Body fields (partial):
     • page: integer >= 1 (default 1)
     • pageSize: integer 1–50 (default 10)
     • licenses: string[] (may include 'none')
     • publishedFrom: string (YYYY-MM-DD)
     • publishedTo: string (YYYY-MM-DD)
   • Purpose:
     • Browse paper lists by time or license as a base for search results or user-library browsing.

3.2 Search: keyword search vs vector (semantic) search

1. Keyword search (literal string matching)

   • Endpoint: POST /api/tools/papers_search_keyword
   • Key body fields:
     • query: string (required; search string)
     • page, pageSize (same semantics as papers_paginate)
     • tags: string[] / tagNames: string[] (tag filters)
     • tagMode: "and" | "or" (default "or")
     • licenses, publishedFrom, publishedTo (same as above)
   • Usage guidance:
     • Prefer this when the user provides explicit keywords, title fragments, or phrases.
     • Explain that this is literal matching, ideal for precise lookup.

2. Vector search (semantic search)

   • Endpoint: POST /api/tools/papers_search_vector
   • Key body fields:
     • query: string (required; natural-language query)
     • limit: integer 1–30 (default 10)
     • Other filters as in papers_search_keyword
   • Usage guidance:
     • Use when the user describes fuzzy concepts, research themes, or questions (e.g., “recent progress of LLMs in medical imaging”).
     • Clarify that this is semantic search, better for “finding related papers” without exact title matches.

3.3 Submitting papers: URL / PDF / batch URLs

1. Submit a paper by URL

   • Endpoint: POST /api/tools/paper_submit_url
   • Body fields:
     • url: string (required; paper source page or PDF URL)
     • modelId: string (optional; PDF analysis model)
     • force: boolean (force re-parse)
     • favoriteFolderId: string | null (favorites folder, null for root)
     • favoriteNote: string (favorites note)
   • Usage guidance:
     • Use when the user provides a paper page URL or direct PDF URL and wants parsing, analysis, or saving to favorites.
     • Mention that parsing may take time and suggest how to check results later if needed.

2. Submit or link a PDF file

   There are two main modes:

   • JSON API:

     • Endpoint: POST /api/tools/paper_submit_pdf
     • JSON body:
       • pdfUrl: string OR pdfBase64: string (one of them is required)
       • fileName: string (optional)
       • Other fields as in paper_submit_url (modelId, force, favoriteFolderId, favoriteNote)
     • Note: the spec explicitly says “provide either pdfUrl or pdfBase64.”

   • Multipart upload:

     • Same endpoint with multipart/form-data:
       • file: binary (required; PDF file content)
       • Optional: modelId, force, favoriteFolderId, favoriteNote

   • Usage guidance:

     • Use this when the user has a local PDF or remote PDF URL and wants it parsed.

3. Batch submit URLs

   • Endpoint: POST /api/tools/papers_submit_urls
   • Body fields:
     • urls: string[] | string (array or newline-separated string)
     • modelId: string (optional; applied to all URLs)
     • notifyOnComplete: boolean (default false)
     • force: boolean (default false)
     • favoriteFolderId: string | null
     • favoriteNote: string
   • Usage guidance:
     • Use when the user provides many paper URLs and wants them parsed, saved, or both in batch.

3.4 Reading and analysis: markdown analysis / raw markdown / PDF link

1. Get markdown-formatted paper analysis

   • Endpoint: POST /api/tools/paper_analysis_markdown
   • Body fields:
     • paperId: string (required)
     • language: "auto" | "zh" | "en" | "both" (default "auto")
     • scope: "public" | "me" | "auto" (default "public")
   • Usage guidance:
     • Use when the user wants structured, readable analysis (summary, structure, key points).
     • Set language according to the user’s preference:
       • For Chinese users, prefer "zh" or "both";
       • If unsure, use "auto".

2. Get the raw markdown source for a paper

   • Endpoint: POST /api/tools/paper_markdown_raw
   • Body fields:
     • paperId: string (required)
     • maxChars: integer (500–120000) (optional; truncation)
   • Usage guidance:
     • Prefer this when the user wants to do custom processing, re-summarization, or extraction of formulas/tables.
     • For very long papers, set a reasonable maxChars and inform the user if the content was truncated.

3. Get a guarded PDF download link

   • Endpoint: POST /api/tools/paper_pdf_link
   • Body fields:
     • paperId: string (required)
   • Usage guidance:
     • Use when the user wants to download or locally open the PDF.
     • Respect copyright and visibility rules; only guide the user to links the API has authorized.

3.5 Favorite folders and favorite papers

1. List favorite folders

   • Endpoint: POST /api/tools/paper_favorite_folders
   • Body: {}
   • Purpose:
     • Get folder IDs, parent/child relationships, and paths to help the user organize and target save locations.

2. List favorite papers

   • Endpoint: POST /api/tools/paper_favorites_list
   • Body fields:
     • page, pageSize (pagination; 1–50)
     • folderId: string | null (null for root; omit for all folders)
     • includeDescendants: boolean (default false)
     • search: string (search in notes and titles)
   • Purpose:
     • Browse the user’s personal library or filter by notes and titles.

3. Save or update a favorite entry

   • Endpoint: POST /api/tools/paper_favorite_save
   • Body fields:
     • paperId: string (required)
     • folderId: string | null (target folder; null for root; omit to reuse existing folder if present)
     • note: string (optional note)
   • Usage guidance:
     • After identifying important papers, suggest saving them to an appropriate folder with a short descriptive note.

3.6 Analysis models and account usage

1. List available PDF analysis models

   • Endpoint: POST /api/tools/paper_analysis_models
   • Body: {}
   • Purpose:
     • Show available models under the current plan (including consumeUnits and per-parse extra price) to help choose modelId.
     • Use when the user is concerned about cost or model quality; list models and give recommendations.

2. Summarize account quota and points

   • Endpoint: POST /api/tools/account_usage_summary
   • Body: {}
   • Purpose:
     • Summarize current parse quota and points so the user knows how many more papers can be parsed.

3. List parse history

   • Endpoint: POST /api/tools/parse_history_list
   • Body fields:
     • page, pageSize (1–100)
     • chargeMode: string (optional, e.g., FREE or BALANCE)
   • Purpose:
     • Show parse usage records for the last 30 days (which papers, when parsed, potential charges).

4. Recommended workflows

4.1 From research question to paper recommendations (search workflow)

1. Clarify the user’s research question or topic in natural language.
2. If the description is conceptual or fuzzy:
   • First call vector search /api/tools/papers_search_vector to focus on conceptual relevance.
3. If the user provides concrete keywords or title fragments:
   • Use keyword search /api/tools/papers_search_keyword.
4. Organize results by relevance or recency:
   • Present titles, years, and short descriptions of main contributions, plus paperId for follow-up.
5. For selected papers:
   • Call /api/tools/paper_analysis_markdown for detailed analysis; or
   • Call /api/tools/paper_markdown_raw for fine-grained custom processing.

4.2 Submit a new paper and obtain analysis (submission + analysis workflow)

1. When the user provides a URL or PDF:
   • URL: use /api/tools/paper_submit_url
   • Local or remote PDF: use /api/tools/paper_submit_pdf
2. If the user specifies a folder or note:
   • Include favoriteFolderId and favoriteNote in the request.
3. Wait for parsing to complete (if the API is asynchronous, rely on history or documented IDs):
   • Once a paperId is available, call /api/tools/paper_analysis_markdown.
4. Summarize the analysis in terms of:
   • Core contributions, methods, datasets, conclusions, and how they relate to the user’s research question.

4.3 Manage personal literature library (favorites workflow)

1. When the user needs an overview of their favorites structure:
   • Call /api/tools/paper_favorite_folders to list all folders.
2. To view favorites by folder or search string:
   • Call /api/tools/paper_favorites_list with appropriate folderId and search.
3. When important long-term papers are identified:
   • Call /api/tools/paper_favorite_save to create or update favorite records.
4. In summaries:
   • Suggest organizing folders by topic or project to simplify future retrieval.

5. Practical tips

• Prefer /api/tools/*:
  /api/mcp/tools/* endpoints are marked deprecated in the OpenAPI spec; avoid relying on them for new integrations.
• Validate parameters:
  Respect OpenAPI constraints (pagination limits, required fields) to avoid unnecessary retries.
• Post-process responses:
  After each call, convert raw JSON into user-friendly output:
  • Concise paper lists (title + year + short description);
  • Clear bullet-point summaries (methods, results, limitations);
  • Direct conclusions and recommendations relevant to the user’s question (not just raw data dumps).