Provides tools for searching academic papers, retrieving paper metadata, citations, references, related papers, and recommendations using the Semantic Scholar API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@sophotron search for papers on the nature of consciousness"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sopho- (σοφία, wisdom) + -tron (instrument) — a wisdom-instrument for philosophy research.
Sophotron is a tool for searching and retrieving philosophy papers, built for AI research assistants that need to ground themselves in the actual philosophical literature rather than the shallow, mis-classified philosophy slice of general academic databases. It is exposed today as an MCP server; a CLI and other frontends can sit on the same interface-agnostic core.
It combines four open sources, each doing what it does best:
Source | Role |
Semantic Scholar | Search, metadata, citations, references, SPECTER-based related papers (the backbone) |
OpenAlex | Open-access discovery — agent-fetchable PDFs, ~11.5M OA philosophy works |
Unpaywall | DOI → best open-access PDF location |
CrossRef | Authoritative DOI metadata fallback ( |
PhilArchive | Philosophy-specific open-access cache (metadata + best-effort PDF links) |
PhilPapers taxonomy | Browse 6,134 expert-curated philosophy categories (cached snapshot) |
Runs fully keyless. An optional Semantic Scholar API key raises rate limits; optional contact emails opt into the OpenAlex/Unpaywall "polite pool." No source requires registration.
Why four sources? Philosophy is under-served by general infrastructure: low open-access (~15%) and DOI-assignment (~60%) rates, canonical works predating DOIs, and systematic mis-classification (Rawls's A Theory of Justice tagged "Sociology" in Semantic Scholar; Heidegger's Being and Time with a null field). And as of 2026, the PhilPapers/PhilArchive web APIs sit behind Cloudflare bot-protection. OpenAlex + Unpaywall therefore supply the open-access PDFs an automated client can actually fetch, while a cached PhilArchive harvest adds philosophy-specific coverage.
npm install
npm run build
npm run smoke # optional: MCP stdio smoke testRequires Node.js ≥ 22.
Related MCP server: CogniResearch
All configuration is optional — copy .env.example to .env and fill in what you want:
# Optional: raises Semantic Scholar rate limits (request at
# https://www.semanticscholar.org/product/api). Without it, S2 still works but
# rate-limits aggressively (HTTP 429) on its shared unauthenticated pool.
SEMANTIC_SCHOLAR_API_KEY=
# Optional: OpenAlex/Unpaywall "polite pool" contact (a courtesy id, not a key).
# OPENALEX_EMAIL=you@example.com
# UNPAYWALL_EMAIL=you@example.comAdvanced overrides (SOPHOTRON_OAI_ENDPOINT, SOPHOTRON_DATA_DIR, SOPHOTRON_LIBRARY_PATH) are documented in .env.example.
Claude Code / any stdio MCP client (~/.claude/settings.json):
{
"mcpServers": {
"sophotron": {
"command": "node",
"args": ["/absolute/path/to/sophotron/dist/index.js"],
"env": { "SEMANTIC_SCHOLAR_API_KEY": "optional" }
}
}
}Claude Desktop / Cowork (MCPB bundle): a manifest.json is included. Pack it with the MCPB CLI and install the resulting .mcpb:
npx @anthropic-ai/mcpb packTool | Description |
| Search via Semantic Scholar (auto-falls back to OpenAlex when S2 is rate-limited); PhilArchive PDF enrichment. Optional |
| Search via OpenAlex with open-access PDF discovery ( |
| Paper details by S2 ID, DOI, arXiv ID, or PhilArchive code |
| Papers citing a paper |
| A paper's bibliography |
| SPECTER-based related papers. Optional |
| Resolve an open-access PDF via the fallback chain (below) |
| Search the local PhilArchive open-access cache |
| Incrementally harvest the PhilPapers/PhilArchive OAI-PMH feed into the cache |
| PhilArchive cache + cross-reference statistics |
| Browse the expert-curated PhilPapers category taxonomy (6,134 categories) |
| Papers near an inferred taxonomy-category region, ranked by influence — a semantic lens over an inferred mapping, not an authoritative index |
| Resolve an open-access PDF, extract its text, and store it as markdown (arxiv-mcp-server-compatible path) |
| Read back the stored text of a downloaded paper, paginated |
| A personal paper library (JSON-on-disk) with tags and notes |
| "More like these," seeded by your library, via Semantic Scholar's hosted Recommendations API (SPECTER2) |
The PhilPapers taxonomy is more than a list to browse: each category is treated as an inferred
SPECTER2 region (a coordinate in embedding space, seeded from the category name), so you can
navigate papers relative to a category. Pass a category_id (the id browse_taxonomy returns)
to search_papers or get_related to rerank the results by proximity to that region, or call
category_papers for influence-ranked papers near it.
This is a semantic lens over an inferred mapping, not a classification claim — results are
tagged with relative proximity (nearer / farther / unplaceable), placement: "inferred", and an
honest confidence tier (distinct for semantically-clear coarse categories, low for fine,
catch-all, or thinly-seeded ones). Transient Semantic Scholar outages are reported as
unavailable, never as a confident empty region.
get_pdf)Tries sources in order of reliability and stops at the first hit, reporting where the PDF came from and whether an automated client can fetch it:
Semantic Scholar openAccessPdf → agentFetchable: true
Unpaywall by DOI → agentFetchable: true
OpenAlex by DOI (or title search) → agentFetchable: true
PhilArchive best-effort URL → agentFetchable: false (philarchive.org is Cloudflare-walled to automated clients; open these in a browser)
// get_pdf { "paper_id": "10.1007/s11019-014-9560-2" }
{ "pdfUrl": "https://…/paper.pdf", "source": "unpaywall", "agentFetchable": true, "oaStatus": "green", … }PhilArchive's OAI-PMH metadata omits DOIs, so papers are linked by fuzzy title + author matching (title 50% / author 35% / year 15%; accept > 0.85). Match results carry a confidence score so uncertain links can be reviewed.
Source | Limit | Handling |
Semantic Scholar | 429s even at slow pace without a key — the unauthenticated pool is globally shared (empirically 7/8 requests 429'd at 5s spacing) | bounded retry/backoff ( |
OpenAlex / Unpaywall | generous, no key | polite-pool email recommended |
PhilArchive OAI ( | 2 req/sec | built-in 500ms throttle |
| Cloudflare 403 to agents | PDF URLs returned as best-effort, browser-only |
src/
├── index.ts # MCP server frontend (18 tools)
├── types.ts # shared types
├── adapters/ # one module per external API; never throw to callers
│ ├── semantic-scholar.ts # S2 Graph/Recommendations API (+ SPECTER2 embeddings)
│ ├── openalex.ts # OpenAlex works + OA discovery
│ ├── unpaywall.ts # DOI → OA PDF
│ ├── crossref-api.ts # api.crossref.org DOI metadata fallback
│ ├── philarchive.ts # PhilArchive/PhilPapers OAI-PMH + cache
│ └── taxonomy.ts # PhilPapers category hierarchy (cached)
├── services/ # cross-source logic
│ ├── crossref.ts # S2 ↔ PhilArchive fuzzy cross-reference
│ ├── pdf-resolver.ts # S2 → Unpaywall → OpenAlex → PhilArchive chain
│ ├── paper-download.ts # download_paper / read_paper full-text store
│ ├── library.ts # personal library (JSON-on-disk)
│ └── taxonomy-bridge.ts # taxonomy→papers semantic bridge (inferred centroids)
└── utils/
├── fuzzy-match.ts # title/author matching
├── vector.ts # cosine / centroid / proximity ranking
├── rate-limit.ts # serial rate limiter (S2 1 req/s)
└── http.ts # shared retry/backoff fetch
data/ # philarchive-cache.json, crossref-cache.json, category-centroids.json (regenerable)
scripts/smoke-test.mjs # MCP stdio smoke test (also runs in CI)npm run build # tsc (tsconfig.build.json — excludes tests/experiments)
npm run typecheck # tsc --noEmit (full, incl. tests)
npm test # vitest (set SKIP_INTEGRATION=true to skip live tests)
npm run smoke # MCP stdio smoke testStart with CONTRIBUTING.md; the operational guide (architecture, conventions, correctness contracts) is CLAUDE.md. Tests are the verification spine — every adapter has unit tests with mocked fetch, plus a network-gated integration suite.
Browse the expert-curated PhilPapers category hierarchy (6,134 categories from a cached snapshot — the live PhilPapers API is Cloudflare-blocked). Omit category_id for the top-level areas; pass category_id to list its subcategories; pass query to find categories by name. With a category_id you can: call category_papers to list influential papers near that category region, or pass it as the category_id param to search_papers / get_related to re-rank by category proximity. (Those are an inferred semantic lens, not an authoritative classification.)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max categories to return (default 50) | |
| query | No | Find categories whose name matches this text (overrides category_id). | |
| category_id | No | Category ID to list children of. Omit for top-level areas. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behavioral traits: the hierarchy is a cached snapshot from a Cloudflare-blocked API, query overrides category_id, and category_id is optional. It also notes the semantic lens is inferred, not authoritative. It could add more detail about output structure, but the core behavior is clearly communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, with the most important information in the first sentence. Every sentence adds value: the cache caveat, parameter usage, sibling tool integration, and a clarifying note about authority. No waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema or annotations, the description does a solid job explaining the tool's operation and limitations. It covers the two browsing modes (top-level and subcategories) and search behavior. It doesn't explicitly describe the return format, but for a simple category listing tool, the description is sufficiently complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the interplay of parameters: omitting category_id yields top-level areas, passing it lists subcategories, and query overrides category_id. This provides practical usage context not present in the raw schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Browse the expert-curated PhilPapers category hierarchy.' It specifies the resource (categories) and the action (browse), and differentiates from siblings like category_papers, search_papers, and get_related by explicitly showing how category_id can be used with those tools, but this tool itself is for listing categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Omit category_id for the top-level areas; pass category_id to list its subcategories; pass query to find categories by name.' It also explains how to leverage the result with sibling tools ('call category_papers... or pass it as the category_id param to search_papers / get_related'), including a caveat about the inferred semantic lens. This clearly distinguishes when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List influential papers near an INFERRED semantic region for a PhilPapers category. This is a semantic lens over an inferred mapping (category name → SPECTER2 centroid → nearby papers), NOT an authoritative PhilPapers classification or a canonical reading list. Pass a category_id from browse_taxonomy. Coarse/distinct categories (top-level areas, subfields) are MORE reliable but still an unvalidated per-category inference; fine-grained leaves — and miscellaneous/structural buckets and thin regions — are flagged low-confidence. Papers are ranked by influential citation count, each tagged with its relative proximity to the region.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max papers (default: 20) | |
| category_id | Yes | PhilPapers category id (from browse_taxonomy) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes full responsibility for behavioral disclosure. It clearly reveals that the mapping is inferred rather than authoritative, notes varying confidence levels across category types, and describes the ranking and tagging of results. This provides essential context about the tool's limitations and behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet comprehensive, covering purpose, input source, reliability caveats, and output characteristics in a well-organized manner. Each sentence adds meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description adequately explains what is returned (papers ranked by citation count, tagged with proximity). It also provides the necessary context about the inference limitations and input requirements, making it complete for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both limit and category_id fully described in the schema. The description adds some context by referencing browse_taxonomy as the source for category_id, but this is already in the schema. No additional parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing influential papers near an inferred semantic region for a PhilPapers category, using specific language ('inferred semantic region', 'SPECTER2 centroid') that distinguishes it from sibling tools like search_papers or get_related. It also explicitly states what it is NOT, reinforcing its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It instructs to pass a category_id from browse_taxonomy, establishing the required input source. It also warns about reliability based on category granularity, implying appropriate use cases. However, it does not explicitly name alternative tools for different scenarios (e.g., search_papers for keyword search).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve the best open-access PDF for a paper, fetch it, extract its text, and store it as markdown in the shared library (default ~/.arxiv-mcp-server/papers, override with ARXIV_MCP_STORAGE_PATH). Returns a paper_id (slug) to pass to read_paper. PhilArchive PDFs are browser-only (Cloudflare) and are not fetched — the URL is returned to open manually.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Paper title, used to resolve an OA PDF when no DOI/id match is found | |
| paper_id | Yes | A DOI, Semantic Scholar id, arXiv id, or PhilArchive code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the storage path and environment variable override, the multi-step behavior, the returned paper_id for read_paper, and the significant limitation that PhilArchive PDFs are not fetched due to Cloudflare. This exceeds typical descriptions and provides actionable transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and each clause earns its place: the storage path, return value for read_paper, and PhilArchive exception all add critical context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is complete enough: it explains what it does, side effects (storage), return value (paper_id), and a key edge case (PhilArchive). It also hints at integration with read_paper. Given the complexity, this is a well-rounded description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for both parameters (paper_id and title). The description adds no additional parameter semantics beyond what the schema states, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific multi-step action: resolve an open-access PDF, fetch it, extract text, store as markdown, and return a paper_id slug. It distinguishes itself from siblings like get_pdf (just PDF retrieval) and read_paper (reads stored markdown) by describing the local storage and integration with read_paper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you want a paper downloaded, processed, and stored for later reading via read_paper. It explicitly covers the PhilArchive exception (browser-only, return URL instead of fetching), providing alternative handling. It does not fully contrast with sibling tools like get_pdf, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics about the local PhilArchive cache and cross-reference mappings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It implies a read-only operation ('get') but does not explicitly state side effects, permissions, rate limits, or what specific statistics are included. The description adds some context by naming 'local PhilArchive cache' and 'cross-reference mappings,' but fails to disclose important behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly states the purpose. There is no wasted text, and every word contributes to the meaning. It is appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description must explain what the returned statistics contain. It only says 'statistics about the local PhilArchive cache and cross-reference mappings' without specifying what those statistics are (counts, sizes, timestamps, mapping details). Given its simplicity, it is missing needed details for the agent to correctly interpret the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the schema coverage is trivially 100%. The description does not need to explain parameter semantics. Per the rubric, a zero-parameter tool only needs a baseline of 4, which is met.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to get statistics about the local PhilArchive cache and cross-reference mappings. The verb 'get' and resource are specific, and it distinguishes from sibling tools which focus on papers, citations, and searches rather than cache internals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or when not to use it (e.g., when needing paper data). The description only states what it does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get papers that cite a given paper.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 50) | |
| paper_id | Yes | Paper ID (S2 ID or DOI) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosure. It only states the basic operation without revealing any behavioral traits such as pagination, default limit, sorting, response format, or potential limitations. This falls short of what is needed for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly conveys the tool's purpose with no filler or redundancy. It is well-structured and front-loaded, achieving maximum clarity in minimal words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema), but the description lacks any mention of return value structure, default behavior, or distinctions from sibling tools. It is sufficient for basic understanding but incomplete for an agent that needs to anticipate outputs or edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both paper_id (S2 ID or DOI) and limit (max results, default 50) clearly described. The description adds no additional meaning beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves papers that cite a given paper, using a specific verb ('Get') and resource ('papers that cite'). This distinguishes it from sibling tools like get_references (which gets papers cited by a paper), get_paper (single paper), and get_related (related papers).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied by the name and title — use when you need citing papers for a specific paper. However, there is no explicit guidance on when to use this tool versus alternatives like get_references, nor any mention of prerequisites or restrictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed metadata for a paper by ID. Accepts S2 paper ID, DOI, arXiv ID, or PhilArchive ID.
| Name | Required | Description | Default |
|---|---|---|---|
| paper_id | Yes | Paper ID (S2 ID, DOI like "10.1234/...", arXiv ID, or PhilArchive 5-letter code) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It does not mention that the operation is read-only (though 'Get' implies it), nor does it explain error behavior, authentication requirements, or what 'detailed metadata' encompasses. It lacks any additional behavioral context beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence states the purpose clearly, and the second adds necessary detail about accepted ID types. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is mostly complete: it explains what the tool does and what inputs it accepts. However, it could be more specific about the return value (e.g., that it returns a single object with fields like title, authors, year) to fully compensate for the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the schema already thoroughly explains 'paper_id' with examples of accepted formats. The description's mention of accepted ID types largely duplicates the schema without adding new meaning. Thus, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get detailed metadata for a paper by ID.' It names a specific resource (paper) and the action (get metadata), and the list of accepted ID types (S2 ID, DOI, arXiv, PhilArchive) further distinguishes it from sibling tools like get_citations or search_papers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you have a paper ID and want metadata) but does not explicitly mention alternatives or exclusions. It does not say 'For searching, use search_papers' or 'For full text, use get_pdf.' The context is clear but not prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get PDF URL for a paper. Tries Semantic Scholar open access first, then falls back to PhilArchive.
| Name | Required | Description | Default |
|---|---|---|---|
| paper_id | Yes | Paper ID (S2 ID, DOI, or PhilArchive ID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the fallback order (Semantic Scholar first, then PhilArchive), which is a useful behavioral trait. However, it does not mention what happens when no PDF is found, access restrictions, or rate limits, leaving important behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the primary action and no filler. It earns its place by adding the fallback detail without unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description adequately conveys what it does and the fallback behavior. It could be more complete by explicitly distinguishing from download_paper or stating failure behavior, but the tool's simplicity keeps it largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameter details, describing paper_id as an 'S2 ID, DOI, or PhilArchive ID'. The description does not add any additional semantics beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get PDF URL for a paper' with a specific verb (get) and resource (PDF URL). It distinguishes itself from siblings like get_paper (metadata) and download_paper (actual download) by focusing on URL retrieval, and adds precision with the fallback logic between Semantic Scholar and PhilArchive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a PDF URL is needed and provides clear context about the fallback order. It does not explicitly mention when not to use it or name alternative tools, but the primary use case is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get papers that a given paper cites (its bibliography).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 50) | |
| paper_id | Yes | Paper ID (S2 ID or DOI) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It accurately states the core behavior but adds no detail about pagination, default limit, ordering, or return format. The description essentially restates the title without additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and object. Every word contributes meaning, and there is no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple, read-only lookup with a clear schema. The description adequately explains the main purpose, but lacks context about reply structure, pagination behavior, or how it relates to sibling tools. Given the absence of annotations and output schema, a complete description would need to cover these aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (paper_id, limit) are already documented. The description itself adds nothing beyond the schema, which is the baseline for full coverage. It neither enhances nor compensates further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns papers cited by a given paper (its bibliography). The verb 'get' and resource 'papers' are specific, and the phrase 'cites (its bibliography)' distinguishes it from the sibling get_citations. However, it does not explicitly name an alternative or contrast with get_citations, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as get_citations or get_related. It implies usage for fetching a paper's bibliography but provides no explicit context, exclusions, or alternative tool suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Incrementally harvest papers from PhilArchive OAI-PMH. Rate limited to 2 req/sec. Run periodically to update local cache.
| Name | Required | Description | Default |
|---|---|---|---|
| from_date | No | Start date for incremental harvest (ISO format, e.g., "2024-01-01") | |
| max_records | No | Max records to fetch in this batch (default: 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the rate limit (2 req/sec) and the side effect of updating the local cache, but it omits details about return format, error handling, or idempotency, which are important for an agent to safely invoke this tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise three sentences, front-loaded with the core action, and each sentence adds value: purpose, rate limit, and usage context. There is no unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description is responsible for explaining return values. It does not state what the agent can expect in response (e.g., harvested records, status, or count), nor does it discuss error conditions. While it covers purpose and rate limit, the lack of behavioral details makes it incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters (from_date, max_records) including defaults and bounds. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'harvest' and resource 'papers from PhilArchive OAI-PMH', with 'incrementally' indicating scope. This distinguishes it from sibling search/get tools, which focus on individual paper retrieval rather than batch cache updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Run periodically to update local cache' gives clear context for when to use this tool. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a paper to your personal library (the arxiv-sanity "library" primitive). Resolves metadata from Semantic Scholar (or CrossRef for a bare DOI) and stores it with optional tags and a note. The saved set is what recommend uses to suggest what to read next. Accepts a Semantic Scholar id, DOI, arXiv id, or PhilArchive code.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Optional free-text note | |
| tags | No | Optional tags / reading-list buckets (e.g. ["phil-mind", "to-read"]) | |
| paper_id | Yes | S2 id, DOI, arXiv id, or PhilArchive code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains metadata resolution from Semantic Scholar/CrossRef and the side effect on reviews. However, it doesn't mention idempotency, duplicate handling, authentication, or return behavior, which are relevant for an add/write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core action, and contains no filler. Each sentence carries useful information: what it does, how it stores metadata, its connection to recommendations, and accepted input formats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write tool with 3 parameters and no output schema/annotations, the description covers the main aspects: action, input types, metadata resolution, and downstream use. It doesn't describe return values or error handling, but these are minor gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described, so the baseline is 3. The description repeats the accepted ID types and adds context about metadata resolution, but doesn't provide new syntax, examples, or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Save') and resource ('a paper to your personal library'). It also distinguishes the tool from siblings like library_remove and library_list by referencing the 'arxiv-sanity library primitive' and its role in feeding `recommend`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (saving a paper to a personal library) and lists the accepted identifier formats. It doesn't explicitly name alternatives or exclusions, but the sibling list makes the distinction implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the papers in your personal library, newest first, optionally filtered to a tag. Also reports the set of tags in use.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Only list papers carrying this tag |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses ordering (newest first), optional tag filtering, and an extra output (the set of tags in use). It does not mention pagination or empty state, but for a simple list tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main verb and resource. Every word earns its place, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter list tool with no output schema, the description covers the essential behaviors: ordering, filtering, and supplementary tag reporting. The only minor gap is ambiguity about what 'newest' refers to (date added vs. publication date), but otherwise it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the tag parameter ('Only list papers carrying this tag'), and the description merely rephrases this concept. No additional examples, edge cases, or parameter nuances are added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (papers in your personal library), with specific behavioral details like newest-first ordering and optional tag filtering. It distinguishes itself from siblings such as search_papers and library_add.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is unambiguous: this is for listing the user's own library, which contrasts with sibling search/retrieval tools. However, it does not explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a saved paper from your personal library by id, S2 id, or DOI.
| Name | Required | Description | Default |
|---|---|---|---|
| paper_id | Yes | The id, S2 id, or DOI of the paper to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only states the basic action ('remove') without addressing permanence, side effects, or idempotency. It does clarify the scope ('personal library') but omits behavioral nuances expected of a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb, no filler. Direct and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter removal tool with no output schema, the description is sufficient to understand the operation. It could mention reversibility but is otherwise adequate for the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single parameter (paper_id) including acceptable identifier types, so parameter semantics are fully covered by the schema. The description adds no new information beyond the schema, hence baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Remove' and clearly identifies the resource ('a saved paper from your personal library') and the accepted identifier formats. This distinguishes it from sibling tools like library_add (adds) and library_list (lists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear use case: when the user wants to delete a paper from their personal library. It doesn't explicitly mention alternatives or exclusions, but the context is unmistakable, warranting a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read back the markdown text of a paper previously stored by download_paper. Supports pagination via start/max_chars. Reads {storageDir}/{paper_id}.md (shared with arxiv-mcp-server). If the paper is not stored, returns an error asking to download_paper first.
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Character offset to start from (default 0) | |
| paper_id | Yes | The slug returned by download_paper | |
| max_chars | No | Maximum characters to return (default 50000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses pagination, the storage path, shared access with arxiv-mcp-server, and error behavior when the paper is missing. It does not cover return format beyond 'markdown text', which is acceptable for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly worded sentences lead with the core purpose, then pagination, then storage/error context. No redundant information; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, prerequisite (download_paper), pagination mechanism, storage location, and error handling. Given no output schema and no annotations, this is complete for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100% with per-parameter descriptions, the tool description adds meaning by explaining paper_id as a slug returned by download_paper and that start/max_chars control pagination. This enriches the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool reads back the markdown text of a paper previously stored by download_paper. This is a specific verb (read) and resource (stored paper markdown), and it clearly differentiates from siblings like get_paper or get_pdf by requiring prior storage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the tool operates on papers previously stored by download_paper and that an error is returned asking to download_paper first if not stored. This gives clear context for when to use it, though it does not explicitly compare to alternatives like get_paper.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recommend papers to read next, seeded by your library — the arxiv-sanity "more like these" feature. By default it uses your whole library as positive examples; pass tag to recommend from one reading-list bucket, or paper_ids to recommend ad hoc from specific papers. Powered by Semantic Scholar SPECTER2 embeddings; papers already in your library are excluded. Without a Semantic Scholar API key this may be rate-limited (HTTP 429).
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Seed only from library papers carrying this tag | |
| limit | No | Max recommendations (default 20) | |
| paper_ids | No | Seed from these specific papers instead of the library |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well: it reveals the default behavior (whole library), the role of SPECTER2 embeddings, that library papers are excluded, and the risk of HTTP 429 rate limiting without an API key. This goes well beyond a basic statement of function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three focused sentences: purpose, configuration paths, and a caveat. It is efficiently front-loaded with the primary purpose and uses minimal words to convey multiple behaviors. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and no annotations, the description covers all essential aspects: default operation, parameter-driven alternatives, algorithmic basis, exclusion logic, and a practical rate-limit warning. For a recommendation tool with three optional parameters, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds semantic meaning by framing 'tag' as selecting 'one reading-list bucket' and 'paper_ids' as 'ad hoc from specific papers', which clarifies their intent beyond the schema's property descriptions. It also mentions the default limit indirectly, reinforcing the schema's default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb 'Recommend' and a clear resource 'papers to read next, seeded by your library'. It explicitly identifies the arxiv-sanity 'more like these' feature, distinguishing it from sibling tools like get_related which likely operate on a single paper. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the default whole-library seeding versus passing 'tag' or 'paper_ids', providing clear usage context. It does not explicitly name alternative tools or exclusion criteria, but the seeding-from-library vs. ad-hoc distinction effectively guides tool selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search papers via OpenAlex with open-access full-text discovery. Complements Semantic Scholar; OpenAlex and the OA PDFs it points to are reachable by automated clients (unlike PhilArchive, which is Cloudflare-walled). Use philosophy_only to restrict to the OpenAlex Philosophy concept, and open_access_only to return only papers with OA full text.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 10) | |
| query | Yes | Search query (title, author, keywords) | |
| year_to | No | Publication year end | |
| year_from | No | Publication year start | |
| philosophy_only | No | Restrict to the OpenAlex Philosophy concept (default: false) | |
| open_access_only | No | Only papers with open-access full text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose a key operational trait: OpenAlex and its OA PDFs are reachable by automated clients, unlike Cloudflare-walled PhilArchive. It doesn't mention rate limits or auth requirements, but for a read-only search API the accessibility note is valuable and beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main purpose, then context, then specific flag guidance. No redundant words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, differentiation, and key flags, and hints at output through 'OA PDFs it points to.' With no output schema, a bit more detail about the return shape would help, but the tool is a search and the description is sufficient for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described, so the baseline applies. The description repeats the meaning of philosophy_only and open_access_only but adds no additional syntax, defaults, or parameter interrelationships beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Search papers via OpenAlex with open-access full-text discovery.' It clearly distinguishes from siblings by contrasting with Semantic Scholar and PhilArchive, making its unique role obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to choose OpenAlex: it complements Semantic Scholar and is reachable by automated clients unlike PhilArchive. It also directs the agent to use philosophy_only and open_access_only, though it stops short of explicitly naming which sibling tool to use instead in which scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for philosophy papers using Semantic Scholar. Returns metadata, abstracts, and PDF URLs where available. Pass category_id (from browse_taxonomy) to re-rank results as a semantic lens over an inferred PhilPapers-category region — papers stay under "papers", each tagged with a relative proximity tier ("nearer"/"farther"/"unplaceable"); this is a "near category C" ordering, not an authoritative classification.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 10, max: 100) | |
| query | Yes | Search query (title, author, keywords) | |
| offset | No | Pagination offset | |
| year_to | No | Publication year end | |
| year_from | No | Publication year start | |
| category_id | No | PhilPapers category id (from browse_taxonomy). When set, re-ranks "papers" as a SEMANTIC LENS over an inferred category region — each paper gains a relative proximity tier ("nearer"/"farther"/"unplaceable") + proximityRank; NOT an authoritative classification. Coarse/distinct categories are more reliable; fine-grained leaves are flagged low-confidence. Skipped on the OpenAlex fallback (needs Semantic Scholar ids). | |
| fields_of_study | No | Filter by field (e.g., "Philosophy", "Philosophy,Computer Science") | |
| open_access_only | No | Only papers with open access PDFs |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the return format at a high level ('metadata, abstracts, and PDF URLs where available') and significantly discloses the non-obvious category_id behavior, including that it is a 'semantic lens' with relative proximity tiers and 'NOT an authoritative classification.' This goes beyond typical search tool descriptions, though it does not mention potential fallbacks or failure modes, which would have pushed it higher.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose. The second sentence, while long, is essential for explaining the complex category_id re-ranking mechanism and its caveats. Every sentence earns its place, and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a search tool of this complexity: it covers the main behavior, outputs, and the one complex parameter (category_id). It lacks an explicit mention of the OpenAlex fallback behavior (which appears only in the schema's category_id description), and there is no output schema so return details are only high-level. However, given the rich schema and the tool's purpose, the description covers the essential context well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% parameter coverage, so the baseline is 3. The description adds substantial meaning beyond the schema by explaining the category_id parameter's semantic-lens behavior, tagging tiers, and non-authoritative nature — details not present in the parameter description. This raises the score above baseline, though it does not address other parameters since the schema already covers them adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search for philosophy papers using Semantic Scholar,' which clearly states the verb (search) and resource (philosophy papers) plus the specific data source (Semantic Scholar), distinguishing it from siblings like search_philarchive and search_openalex. It further specifies outputs ('metadata, abstracts, and PDF URLs') and explains the optional category_id re-ranking behavior, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool ('Search for philosophy papers using Semantic Scholar') and gives detailed guidance for the optional category_id parameter, including how to obtain it ('from browse_taxonomy') and what it does. However, it does not explicitly exclude alternatives or state 'use this instead of search_openalex when...' — the differentiation is implicit rather than explicit, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the local PhilArchive cache directly. Useful for finding philosophy papers that may not be in Semantic Scholar.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 10) | |
| query | Yes | Search query (matches title and abstract) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry transparency. It reveals that this is a local cache search, which is useful. However, it does not specify read-only safety, pagination, or potential response behavior. For a simple search tool, the disclosure is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and resource. No filler or redundancy; every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with two well-documented parameters and no output schema, the description covers the essential purpose and a key use case. It could mention return ordering or default behavior, but it is sufficiently complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no extra parameter detail beyond what's already in the schema, such as 'matches title and abstract' or limit defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and clearly identifies the resource ('local PhilArchive cache'), which immediately distinguishes it from siblings like search_papers and search_openalex. The contrast with Semantic Scholar further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use the tool ('for finding philosophy papers that may not be in Semantic Scholar'), giving a clear context relative to alternatives. It doesn't explicitly name sibling tools, but the Semantically Scholarly context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.3.0browse_taxonomycategory_papersdownload_paperget_cache_statsget_citationsget_paperget_pdfget_referencesget_relatedharvest_philarchivelibrary_addlibrary_listlibrary_removeread_paperrecommendsearch_openalexsearch_paperssearch_philarchiveEach tool has a clearly distinct purpose: multiple search tools are differentiated by backend (Semantic Scholar, PhilArchive, OpenAlex) and use case, while citation, reference, related, PDF retrieval, library management, and taxonomy browsing are all separate actions. No two tools appear to do the same thing.
Tool names mostly follow a verb_noun pattern (get_, search_, browse_, download_, read_), with only a few deviations like 'category_papers' and 'library_add' where the noun comes first, and 'recommend' as a bare verb. Overall the convention is predictable and readable.
With 18 tools, the server is slightly on the heavy side but the breadth of functionality (multi-source search, citation graph, taxonomy, library, full-text reading, recommendations) justifies each tool. No tool feels redundant, though the count approaches the upper bound of what is ideal.
The tool surface covers the full research workflow: discovery (search, browse, related), retrieval (metadata, PDFs, full text), library management (add/remove/list), reading, and recommendation. Minor gaps exist (no bulk operations, no citation export) but none would prevent core use cases.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Academic research MCP server for paper search, citation checks, graphs, and deep research.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
arXiv MCP — preprint server search (free, no auth)
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rookslog/sophotron'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
