Alexandria 是一个 MCP 服务器，它让 Claude（或任何兼容 MCP 的 AI）能够通过单一统一界面访问 61 个公共数字图书馆——包括学术论文、经典书籍、法律记录、历史档案、政府数据库和软件文档。
你可以询问诸如：
“帮我查找关于 Transformer 模型中注意力机制的最新论文” “搜索关于美德本质的古希腊文本” “查找二战期间的美国军事记录” “获取 fastify Web 框架的文档”
它会自动确定要搜索的图书馆，并行运行查询，并返回统一的结果。
实话实说：
46 个来源无需任何 API 密钥即可工作。 如果你只想搜索 arXiv、古腾堡计划 (Project Gutenberg)、牛津大学存储库、剑桥大学存储库、Europe PMC、PLOS、OpenAlex、美国国家档案馆、英国立法以及其他数十个来源——你现在就可以直接使用，无需注册任何内容。
唯一能显著提升体验的密钥是你的 OpenAI API 密钥，它支持自然语言搜索 (library_ask)。没有它，你仍然可以直接搜索特定来源——只是你需要自己指定来源名称。
其他一切都是可选的。 每个额外的密钥都会解锁一个特定的来源。选择与你研究相关的那些即可，其余的可以跳过。
Related MCP server: Paper Search MCP
打开你的终端并检查：
node --version如果显示 v22.x.x 或更高版本，就可以了。如果没有，请从 nodejs.org 下载最新的 LTS 版本。
git clone https://github.com/suavecito585/alexandria-mcp.git
cd alexandria-mcp
npm install
npm run build这大约需要 30 秒。完成后，你会看到一个 dist/ 文件夹出现。这就是编译后的服务器。
记下该文件夹的完整路径——下一步中会用到。在 Mac/Linux 上，你可以运行 pwd 来打印它。在 Windows 上，单独运行 cd 即可打印当前路径。
找到你的 Claude Desktop 配置文件：
Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
用任何文本编辑器打开它。如果已经配置了其他 MCP 服务器，请将 Alexandria 添加到它们旁边。如果它是空的或新的，请以此作为起点：
{
"mcpServers": {
"alexandria": {
"command": "node",
"args": ["/full/path/to/alexandria-mcp/dist/index.js"],
"env": {
"TRANSPORT": "stdio"
}
}
}
}将 /full/path/to/alexandria-mcp 替换为第 2 步中的实际路径。
保存文件后重启 Claude Desktop。
要验证它是否有效，请询问 Claude：“使用 library_list_sources 显示所有可用来源。” 你应该能看到列出的所有 61 个来源。
没有它，你每次搜索时都必须指定来源——例如，“在 arxiv 中搜索 transformer 论文”。有了它，你只需说“帮我查找关于 transformer 模型的论文”，Alexandria 就会自动确定要检查哪些来源。
在 platform.openai.com/api-keys 获取你的密钥。每次搜索的成本仅为几分之一美分（路由调用使用 gpt-4o-mini，每次查询约 $0.0002）。
将其添加到配置中的 env 块：
"env": {
"TRANSPORT": "stdio",
"OPENAI_API_KEY": "sk-..."
}再次重启 Claude Desktop。
library_ingest 允许你对全文内容进行分块、嵌入并存储在向量数据库中，以便日后检索。这仅在你构建研究 RAG 管道时有用。如果你只是想搜索和阅读，请完全跳过此步骤。
如果你确实需要它：
在 supabase.com 创建一个免费项目
进入 SQL 编辑器并运行此代码：
create extension if not exists vector;
create table if not exists source_docs (
id text primary key,
mcp_name text not null,
ingested_at timestamptz default now()
);
create table if not exists knowledge_chunks (
id uuid primary key default gen_random_uuid(),
mcp_name text not null,
source_id text not null,
title text,
authors text[],
year int,
language text,
section text,
chunk_index int,
total_chunks int,
quality_score float,
content text not null,
embedding vector(1536),
created_at timestamptz default now()
);
create index if not exists knowledge_chunks_embedding_idx
on knowledge_chunks
using ivfflat (embedding vector_cosine_ops)
with (lists = 100);添加到你的配置 env 块中：
"SUPABASE_URL": "https://your-project.supabase.co",
"SUPABASE_SERVICE_ROLE_KEY": "eyJ..."你可以在 Supabase 项目的 Settings → API 下找到这两个值。
以下是所有可选密钥，按获取难度和获取内容分类。
这些都是免费的。注册是即时或近乎即时的。
获取内容 | 注册地址 | 配置中的密钥名称 |
CORE — 5700 万+ 全文 OA 论文，目前最大的馆藏 |
| |
Semantic Scholar — 2 亿+ 论文，提供 AI 驱动的推荐和引文图谱 |
| |
NASA ADS — 天文学、天体物理学和物理学文献的首要门户 |
| |
Smithsonian — 史密森尼博物馆的 1400 万条记录（同一密钥适用于 GovInfo） |
| |
Springer Nature — Springer 和 BioMed Central 的 1600 万+ 文章 |
| |
Zenodo — CERN 的开放研究存储库，更高的速率限制 |
| |
BHL — 生物多样性遗产图书馆，数百年的自然历史文献 |
| |
DigitalNZ — 新西兰的国家数字馆藏 |
| |
DPLA — 美国数字公共图书馆 |
| |
Europeana — 来自欧洲博物馆和档案馆的 5000 万+ 项目 |
| |
GitHub Token — OpenITI（1 万+ 伊斯兰文本）所需。无需特殊范围。 |
|
获取内容 | 注册地址 | 配置中的密钥名称 |
CourtListener — 美国联邦和州法院全文判例法 |
| |
Trove — 澳大利亚国家图书馆，数字化报纸和书籍 |
|
BASE 为你提供来自 11,000 多个学术提供商的 4 亿+ 记录——这是我们支持的最大索引。它是免费的，但需要通过电子邮件联系他们的团队将你的 IP 地址列入白名单。通常需要 2-3 个工作日。
从主题下拉菜单中选择 "Access BASE's HTTP API"
包含你的 IP 地址（在 whatismyip.com 查找）以及对你用例的简要描述（例如，“非商业研究聚合”）
等待他们的回复——他们会将你的 IP 列入白名单
批准后，添加到你的配置中："BASE_API_KEY": ""（如果他们使用仅 IP 验证，该值可以为空，或者他们会给你一个令牌）。
获取内容 | 注意事项 | 配置中的密钥名称 |
Google Books — 4000 万+ 书籍，公共领域标题的全文 | 在 Google Cloud Console 中创建一个项目，启用 Books API，创建一个 API 密钥 |
|
GovInfo — 美国国会记录，联邦公报 | 在 api.govinfo.gov/docs 注册——同一密钥也适用于 Smithsonian |
|
每个密钥都放在 env 块中。你的最终配置可能如下所示（仅包含你实际获取的密钥）：
{
"mcpServers": {
"alexandria": {
"command": "node",
"args": ["/full/path/to/alexandria-mcp/dist/index.js"],
"env": {
"TRANSPORT": "stdio",
"OPENAI_API_KEY": "sk-...",
"CONTACT_EMAIL": "you@example.com",
"CORE_API_KEY": "your-core-key",
"SEMANTIC_SCHOLAR_API_KEY": "your-s2-key",
"NASA_ADS_API_KEY": "your-ads-key",
"SMITHSONIAN_API_KEY": "your-data-gov-key",
"GOVINFO_API_KEY": "your-data-gov-key",
"SPRINGER_OA_API_KEY": "your-springer-oa-key",
"SPRINGER_META_API_KEY": "your-springer-meta-key",
"ZENODO_API_KEY": "your-zenodo-key",
"BHL_API_KEY": "your-bhl-key",
"DPLA_API_KEY": "your-dpla-key",
"EUROPEANA_API_KEY": "your-europeana-key",
"DIGITALNZ_API_KEY": "your-digitalnz-key",
"GITHUB_TOKEN": "ghp_...",
"COURTLISTENER_API_KEY": "your-cl-key",
"TROVE_API_KEY": "your-trove-key",
"GOOGLE_BOOKS_API_KEY": "your-books-key",
"SUPABASE_URL": "https://your-project.supabase.co",
"SUPABASE_SERVICE_ROLE_KEY": "eyJ..."
}
}
}
}每次更改配置时，请务必重启 Claude Desktop。
设置完成后，可以尝试以下操作：
Use library_ask to find recent papers on CRISPR gene editingUse library_search to search gutenberg for "Marcus Aurelius"Use library_read to get the full text of arxiv paper 2401.12345Use library_ask to find ancient Greek philosophical texts about justiceUse library_ask to find the Code Wiki documentation for the fastify/fastify GitHub repo46 个来源无需 API 密钥。 这些在安装后即可立即使用：
arXiv, Europe PMC, NASA NTRS, OSTI, ERIC, NSF, NIH, bioRxiv, PLOS, OpenAlex, Crossref, DOAJ, NARA, GovInfo, UK Legislation, Scottish Legislation, Norwegian National Library, OSF (PsyArXiv/SocArXiv), EarlyPrint, Harvard LibraryCloud, Cambridge Apollo, Oxford ORA, Google Code Wiki, Gutenberg, Open Library, Standard Ebooks, Wikisource, Internet Classics Archive, Sacred Texts, Marxists Internet Archive, CCEL, Project Runeberg, Cervantes Virtual, Classical Chinese Texts, Gallica, HathiTrust, Library of Congress, DOAB, OAPEN, Feedbooks, World Digital Library, Data.gov, Chronicling America, NDL (Japan)
15 个来源需要免费 API 密钥：
CORE, Semantic Scholar, NASA ADS, Smithsonian, Springer Nature, Zenodo, BHL, DigitalNZ, DPLA, Europeana, GitHub (OpenITI), CourtListener, Trove, Google Books, BASE (IP whitelist)
MIT — 随你使用。
Ask a question in plain English and get a synthesized answer with inline [n] citations, fused across sources with reciprocal rank fusion. Use this instead of library_ask when you want a cited answer rather than raw results. Every factual sentence is cited or dropped; an uncited or all-dropped answer is flagged in warnings[]. Requires OPENAI_API_KEY (or ALEXANDRIA_SYNTH_API_KEY). Set response_format: "detailed" for the full result set, routing, citation grades, and resolvability.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language question | |
| read_top | No | How many top full-text results to read and cite (default 4) | |
| max_sources | No | Max number of sources to search (default 6) | |
| response_format | No | concise (default) trims results/citations to high-signal fields; detailed returns the full payload, including routing reasons, scores, and stage diagnostics. | concise |
| results_per_source | No | Results to fetch per source (default 5) |
| Name | Required | Description |
|---|---|---|
| answer | Yes | |
| results | No | |
| routing | No | |
| warnings | No | |
| citations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only/open-world; the description adds genuine behavioral detail: 'Every factual sentence is cited or dropped', warnings[] flagging, 'fused across sources with reciprocal rank fusion', and the required API key. These are not visible in annotations or 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?
Purpose and sibling routing are front-loaded, and each subsequent sentence adds distinct information: citation behavior, warning flags, auth requirement, and response_format variant. 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?
With an output schema present, return structure does not need description. The description covers purpose, when-to-use, safety/behavior, auth prerequisites, and the detailed variant, leaving no critical gap for an agent deciding to call this tool.
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 covers 100% of the 5 params, so the baseline is 3. The description enriches two critical params: query is framed as 'plain English', and response_format:'detailed' is tied to specific outputs (routing, citation grades, resolvability).
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?
States the exact operation: 'Ask a question in plain English and get a synthesized answer with inline [n] citations'. The sentence 'Use this instead of library_ask when you want a cited answer rather than raw results' explicitly differentiates it from the closest sibling, so an agent can select it without opening schemas.
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?
Names the alternative 'library_ask' and the condition that selects it ('when you want a cited answer rather than raw results'). Also gives a conditional usage branch: 'Set response_format: "detailed" for the full result set, routing, citation grades, and resolvability.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask for content in plain English; automatically selects the best sources from all 152 libraries, generates optimized per-source queries, and searches in parallel. Use this as the default entry point for any natural-language request. Use library_search instead when you already know which source to query. Requires OPENAI_API_KEY (already set for embeddings). Set response_format: "detailed" for routing reasons and per-stage diagnostics.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language description of what you want to find | |
| max_sources | No | Max number of sources to search (default 5) | |
| response_format | No | concise (default) trims results/citations to high-signal fields; detailed returns the full payload, including routing reasons, scores, and stage diagnostics. | concise |
| results_per_source | No | Results to fetch per source (default 5) |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| errors | Yes | |
| intent | Yes | |
| stage1 | No | |
| stage2 | No | |
| results | Yes | |
| routing | Yes | |
| total_results | Yes | |
| sources_searched | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds context beyond them: it discloses the routing behavior, parallel search execution, the automatic source-selection logic, and the OPENAI_API_KEY environment requirement. It does not cover rate limits or failure behavior, but with annotations carrying the safety burden, the added behavioral context is solid.
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, with core behavior front-loaded and routing guidance following immediately. Every sentence earns its place, but the response_format directive in the final sentence partially duplicates what the schema already documents, so it is not maximally tight.
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 complex routing tool, the description covers the essential operational context: what it does, when to use it, the sibling alternative, an environment prerequisite, and a configuration hint. Since an output schema exists, the omission of return-value details is acceptable. Only minor gaps remain, such as rate limits or cost implications of parallel searching.
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 every parameter — including the response_format enum meanings — is already documented in the input schema. The description's 'Set response_format: detailed for routing reasons' adds framing but largely restates what the schema's enum description already says about diagnostics and routing reasons. This is the appropriate baseline-3 case where the schema does the heavy lifting.
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 and resource: it takes plain-English requests and routes them across all 152 libraries, generating per-source queries and searching in parallel. It also differentiates itself from its key sibling, library_search, by explicitly naming what it is not ('when you already know which source to query'). An agent can tell what this tool does without opening the schema.
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 explicitly declares this the default entry point for any natural-language request and names the exact alternative condition, 'Use library_search instead when you already know which source to query.' This is the strongest form of usage guidance: it gives when-to-use, when-not-to-use, and the sibling tool that applies instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the works a scholarly item cites (direction: "references") or the works that cite it (direction: "citations"), resolved through OpenAlex's citation graph with OpenCitations as a fallback when OpenAlex has no record. Accepts an id/source from library_search or library_ask, or a bare DOI/arXiv id. Set format: "bibtex" | "ris" | "apa" to also return a formatted bibliography string; BibTeX prefers Crossref's own citation when a DOI is resolvable, for the first 20 results only (a paced, one-at-a-time doi.org lookup per item), with later results using a locally generated entry instead. Set response_format: "detailed" for full result fields.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Item identifier from library_search/library_ask, or a bare DOI/arXiv id | |
| limit | No | Max results | |
| format | No | Also return a `formatted` bibliography string in this style | |
| source | Yes | Library source name. Run library_list_sources for the current list and descriptions. | |
| direction | Yes | references: works this item cites. citations: works that cite this item. | |
| response_format | No | concise (default) trims results/citations to high-signal fields; detailed returns the full payload, including routing reasons, scores, and stage diagnostics. | concise |
| Name | Required | Description |
|---|---|---|
| seed | Yes | |
| results | Yes | |
| direction | Yes | |
| formatted | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses OpenAlex-to-OpenCitations fallback behavior, Crossref DOI lookup pacing (one-at-a-time, first 20 only), and what 'detailed' returns including routing reasons and diagnostics. This is substantial 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?
Three sentences front-load the core operation and direction semantics, then pack necessary caveats into later clauses. Every clause adds decision-relevant information with no fluff.
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 identifiers, direction, fallback sources, formatting behavior, response modes, and diagnostics. Combined with the rich schema and output schema, an agent has what it needs to invoke this tool 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%, but the description adds important cross-parameter meaning: format triggers a formatted bibliography string, BibTeX has special Crossref behavior, and response_format controls field richness. This enriches the schema rather than repeating it.
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 names a specific verb ('List'), the resource (works cited by or citing a scholarly item), and the two directions with clear semantics. It also distinguishes itself from sibling query tools by framing the output as a citation graph operation.
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 clearly signals that this tool is for resolved items, explicitly accepting IDs from library_search or library_ask or a bare DOI/arXiv ID. It explains when to use format and response_format, though it does not explicitly name sibling tools to exclude.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report per-source health: 'ok', 'degraded', 'down', 'key_missing', or 'unknown', merging this process's live error rate and latency with the last off-process probe run. The probe layer reads eval/probe-latest.json, which published installs do not ship, so on a published install a source's status stays 'unknown' until this process itself calls it. Use before relying on a source that has been erroring, or to check whether a key is configured. Optionally filter by source or cluster. Set response_format: "detailed" for error rate, latency, and quota usage.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Library source name. Run library_list_sources for the current list and descriptions. | |
| cluster | No | Restrict to sources in this cluster | |
| response_format | No | concise (default) trims results/citations to high-signal fields; detailed returns the full payload, including routing reasons, scores, and stage diagnostics. | concise |
| Name | Required | Description |
|---|---|---|
| probeAt | No | |
| sources | Yes | |
| generatedAt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context beyond annotations: the probe layer reads eval/probe-latest.json, the published-install caveat ('status stays unknown until this process itself calls it'), and the data merge behavior. This meaningfully informs the agent about edge cases and internal mechanics.
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: core function with output states, behavioral caveat, and usage/parameter guidance. It is front-loaded, every sentence earns its place, and there is no redundant 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?
The tool has a rich output schema, clear annotations, and a description that covers purpose, behavior, edge cases, usage triggers, and parameter guidance. For a read-only health-reporting tool with all-optional parameters, nothing an agent needs to invoke it correctly is missing.
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 baseline is 3. The description adds value by explaining that response_format: 'detailed' exposes 'error rate, latency, and quota usage'—quotas are not mentioned in the schema—and by framing source/cluster as optional filters. This is a modest but genuine addition 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 ('Report') and resource ('per-source health'), enumerates the exact output states ('ok', 'degraded', 'down', 'key_missing', 'unknown'), and describes the data fusion mechanism. This clearly distinguishes it from siblings like library_list_sources (listing) or library_search (retrieval).
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 explicit when-to-use guidance: 'Use before relying on a source that has been erroring, or to check whether a key is configured.' It does not explicitly name exclusions or alternative tools, but the context is clear and actionable for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dry run: fetch text, chunk semantically, score OCR quality. No writes. Full-text sources only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| source | Yes | Library source name. Run library_list_sources for the current list and descriptions. |
| Name | Required | Description |
|---|---|---|
| title | Yes | |
| source | Yes | |
| sourceId | Yes | |
| totalChunks | Yes | |
| ingestPolicy | No | |
| sampleChunks | Yes | |
| droppedChunks | Yes | |
| avgQualityScore | Yes | |
| estimatedTokens | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds specific behavioral details: fetching text, semantic chunking, and OCR quality scoring, plus the full-text source constraint. It does not contradict annotations and provides useful context beyond them.
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 exceptionally concise, front-loaded with the core purpose, and every clause adds information: 'Dry run', 'fetch text, chunk semantically, score OCR quality', 'No writes', 'Full-text sources only'. No waste.
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 the core function and constraints, and an output schema exists, which helps. However, the undocumented id parameter is a notable gap, and the description doesn't explain what 'score OCR quality' means in practice. Overall, it's adequate but not complete for an agent to use without ambiguity.
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 50%: the source parameter is documented with a helpful reference to library_list_sources, but the id parameter has no description. The tool description does not mention parameters at all, so it fails to compensate for the undocumented id. An agent would have to infer that id identifies a document, which is a significant gap.
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 specific actions: dry run, fetch text, chunk semantically, score OCR quality, with explicit constraints (no writes, full-text sources only). This distinguishes it from sibling tools like library_ingest or library_read, making its 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: it's a dry run, no writes, and only for full-text sources. While it doesn't name specific alternatives, these constraints imply when it's appropriate versus the ingest tool. This is sufficient guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Chunk, embed, and store a text. Idempotent. Full-text sources only. Requires OPENAI_API_KEY + SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| source | Yes | Library source name. Run library_list_sources for the current list and descriptions. |
| Name | Required | Description |
|---|---|---|
| title | Yes | |
| source | Yes | |
| sourceId | Yes | |
| chunksDropped | Yes | |
| chunksWritten | Yes | |
| skippedDuplicate | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotency and safety hints, so the description needs less behavioral disclosure. It adds worthwhile context: the chunk-embed-store processing stages, source-type limitation, and required authentication environment variables. It does not go into failure modes or error behavior, but the bar is lowered by the annotations.
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 and front-loads the core action. Each sentence adds a distinct type of information: operation, idempotency, source scope, and prerequisites. It is slightly terse, but not bloated.
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 two-parameter tool with an output schema and helpful annotations, the description covers key constraints and auth needs. Still, the meaning of 'id' is left unexplained, and the relationship to the 'source' parameter is only implied, leaving a notable gap for an agent preparing a correct call.
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 only 50%, and the description does not explain how 'id' and 'source' map to the action beyond saying 'a text.' The schema's source description is helpful, but the id parameter has no description anywhere, and the tool description does not compensate for that gap.
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 names a specific pipeline ('Chunk, embed, and store a text') and a concrete resource (vector database), which clearly separates it from the sibling tools like library_read or library_search. The title reinforces the resource, and the 'Full-text sources only' constraint adds precision.
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 preconditions ('Full-text sources only', required API keys) that tell an agent when it is allowed to use the tool. However, it does not explicitly explain when to prefer this over a sibling like library_index, and no alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all 152 library sources (count computed from the live registry at startup) with descriptions and capabilities.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| sources | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond that: the source count of 152 is computed dynamically from the live registry at startup, so it may change between runs. It also signals that the response is a complete enumeration rather than a paginated or filtered subset.
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?
A single front-loaded sentence conveys the action, the full scope, the count, and the returned detail level. The parenthetical about the live registry is compact and adds value without wasting space.
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 parameterless list tool, the description is complete: it states what is listed, how much is listed, and what information each entry carries. Combined with the output schema and annotations, an agent has everything needed to invoke and interpret the tool 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?
The tool has zero parameters, so the description does not need to explain parameter usage. The baseline of 4 applies because there is no parameter burden for the description to carry.
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 and resource: 'List all 152 library sources' with the content of the listing ('descriptions and capabilities'). This clearly distinguishes it from siblings like library_search or library_read, which operate on content rather than enumerating sources.
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 use case is implied—use this to discover the full set of available library sources before selecting one—but there is no explicit when-to-use, when-not-to-use, or mention of alternatives. The description is sufficient for the obvious listing purpose, but it does not actively route the agent away from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch text from a library source. Full-text sources return cleaned text (truncated at 200k chars). Metadata sources return item details and an external URL.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Item identifier from library_search or library_ask | |
| source | Yes | Library source name. Run library_list_sources for the current list and descriptions. |
| Name | Required | Description |
|---|---|---|
| doi | No | |
| note | No | |
| text | No | |
| year | No | |
| pages | No | |
| title | Yes | |
| authors | Yes | |
| language | No | |
| charCount | No | |
| truncated | No | |
| externalUrl | No | |
| truncatedAt | No | |
| unavailable | No | |
| metadataOnly | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral details beyond the annotations: full-text results are cleaned and truncated at 200k characters, and metadata sources return details plus an external URL. This complements the readOnlyHint and idempotentHint annotations without contradiction.
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 and front-loaded: the first sentence states the core purpose, and the second sentence adds the key variant behavior. Every sentence earns its place with no 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 output schema exists, the description appropriately avoids detailing return values. It covers the main behavioral variation and works with the schema to give the agent enough to call the tool correctly. Minor gaps like error behavior are not critical here.
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 schema already explains both id and source. The description adds context about source type behavior but does not introduce new parameter-specific 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 operation: fetching text from a library source. It adds meaningful differentiation between full-text and metadata sources, which helps distinguish this tool from search-oriented siblings like library_search or library_ask.
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 context through the phrase 'from a library source' and the parameter note that ids come from library_search or library_ask. However, it does not explicitly say when to use this tool versus alternatives or state exclusions, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get papers similar to a given paper using Semantic Scholar's recommendation engine. Pass a paperId from a semanticscholar search result. Returns up to 500 similar papers.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Semantic Scholar paperId | |
| limit | No |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints, so the description carries a lower burden. It adds input provenance ('paperId from a semanticscholar search result') and a result-count ceiling, but doesn't disclose potential external API failures, rate limits, or invalid-ID 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?
Three short sentences, no filler, and the core purpose is front-loaded before usage guidance. Every sentence adds 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?
For a two-parameter, output-schema-backed tool with strong annotations, the description provides enough context: source of the id, operation, and result limit. It doesn't discuss failure modes, but the simplicity and annotations make that a minor gap.
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 50%; id is documented in the schema, and the description enriches it by requiring it come from a Semantic Scholar search result. limit has no schema description but the 'Returns up to 500 similar papers' phrase indirectly conveys its meaning, though not fully.
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 and resource: 'Get papers similar to a given paper' via Semantic Scholar's recommendation engine. This clearly separates it from siblings like library_search and library_citations by identifying the operation as recommendation rather than search or citation lookup.
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 gives an explicit when-to-use condition: you need an existing paperId from a Semantic Scholar search result and want similar papers. It doesn't spell out alternatives or exclusions, but the context is clear enough for an agent to pick this over search or citations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deep research on a topic: outlines 3 to 7 coverage objectives, generates search queries, answers each with library_answer, extracts learnings and follow-up questions, then recurses with half the breadth. Stops once every objective is covered by a learning, at the given depth, at the time budget, or once a round finds no new sources. Requires OPENAI_API_KEY (or ALEXANDRIA_RESEARCH_API_KEY / ALEXANDRIA_SYNTH_API_KEY). Set response_format: "detailed" for the per-round breakdown, elapsed time, citation grades, resolvability, and the objectives/coverage outline.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Recursion depth (default 2) | |
| query | Yes | Research topic or question | |
| breadth | No | Queries generated in the first round; halves each round (default 4) | |
| max_minutes | No | Wall-clock time budget in minutes (default 6) | |
| response_format | No | concise (default) trims results/citations to high-signal fields; detailed returns the full payload, including routing reasons, scores, and stage diagnostics. | concise |
| Name | Required | Description |
|---|---|---|
| report | Yes | |
| rounds | No | |
| coverage | No | |
| warnings | No | |
| citations | Yes | |
| elapsedMs | No | |
| objectives | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only and non-destructive. The description adds valuable behavioral context beyond that: it requires an external API key, calls library_answer as a sub-step, recurses with halved breadth, and stops on coverage/depth/time/no-new-sources. It does not repeat safety hints or contradict them.
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 dense but every sentence adds distinct information: the algorithm, the stopping conditions, the auth requirement, and the response_format distinctions. It front-loads the core purpose and avoids filler or restating the title.
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 complex recursive tool, the description covers the main workflow, termination criteria, hard prerequisite, and output options. An output schema exists, so return-value details need not be spelled out. Nothing required for an agent to decide on and invoke the tool correctly is missing.
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 extra meaning by explaining response_format 'detailed' returns per-round breakdown, elapsed time, citation grades, resolvability, and objectives/coverage outline, and by clarifying that breadth halves each round. This goes beyond the schema's brief parameter 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 opens with 'Deep research on a topic' and gives a concrete algorithm: outline objectives, generate queries, answer via library_answer, extract learnings, recurse. This is a specific verb plus resource and process, and it clearly distinguishes the tool from single-shot siblings like library_ask or library_search by framing it as a recursive orchestration tool.
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: 'Deep research on a topic' with 3–7 coverage objectives and recursion. It also implies it should be used for multi-round, exhaustive research rather than simple lookups, though it does not explicitly name exclusions or alternative tools, 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 a specific library source by name. Use library_ask instead for natural language queries across multiple sources.
Sources marked [full text] support library_read and library_ingest. Sources marked [metadata] return discovery info and external URLs only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| query | Yes | Title, author, subject, or keywords | |
| source | Yes | Library source name. Run library_list_sources for the current list and descriptions. | |
| response_format | No | concise (default) trims results/citations to high-signal fields; detailed returns the full payload, including routing reasons, scores, and stage diagnostics. | concise |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish a safe, read-only, idempotent operation, so the description does not need to restate that. It adds useful behavioral context beyond the annotations by distinguishing [full text] sources, which support read/ingest, from [metadata] sources, which return discovery info and external URLs only.
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 short, purposeful paragraphs: the core action, the key alternative, and source-type capability guidance. No filler or repetition of schema/annotation content.
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 strong schema (100% parameter coverage), explicit output schema, and annotations, the description covers the remaining operational context: which source to target, how to route to library_ask, and what result types to expect from metadata-only sources. Nothing needed to call it correctly is missing.
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 a little extra meaning by framing the query as a structured search of a specific source rather than a natural-language question, which reinforces the query and source parameters without replacing 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 action ('Search a specific library source by name') and names the resource (library source). It also differentiates from library_ask, which handles natural-language queries across multiple sources, so an agent can tell them apart.
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 says to use library_ask instead for natural language queries across multiple sources. It also explains when library_read and library_ingest apply based on [full text] source markings, giving clear routing to the relevant siblings.
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.
v11.0.0library_answerlibrary_asklibrary_citationslibrary_health_checklibrary_indexlibrary_ingestlibrary_list_sourceslibrary_readlibrary_recommendlibrary_researchlibrary_searchScored across 11 tools
Each tool targets a distinct operation—listing, health, natural-language search, specific search, read, dry-run indexing, ingest, recommend, answer, deep research, citations. Overlaps like ask vs. answer are clearly differentiated by descriptions.
All tools follow the library_<verb> pattern with consistent snake_case naming. Verbs are clear and predictable (list, search, read, ingest, etc.), with minor noun-based exceptions like 'health_check' and 'citations' that still fit the pattern.
11 tools is well within the ideal 3-15 range and each serves a distinct purpose, covering the full lifecycle from discovery to ingestion to synthesis without redundancy.
The tool set covers discovery (list_sources), health (health_check), search (ask, search), retrieval (read), ingestion (index, ingest), recommendation, synthesis (answer, research), and citations. No obvious gaps exist for a library server's expected operations.
Search a billion+ documents — papers, books, code, legal cases, forums, Wikipedia, and more.
Federated search of books and papers, BibTeX/RIS citations, open-access retrieval and reading.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Machine Library by Space Frontiers: retrieval across papers, books, patents, and social sources.
