Alexandria es un servidor MCP que le da a Claude (o a cualquier IA compatible con MCP) acceso a 61 bibliotecas digitales públicas —artículos académicos, libros clásicos, registros legales, archivos históricos, bases de datos gubernamentales y documentación de software— a través de una interfaz unificada.
Puedes pedirle cosas como:
"Búscame artículos recientes sobre mecanismos de atención en modelos transformer" "Busca textos griegos antiguos sobre la naturaleza de la virtud" "Busca registros militares de EE. UU. de la Segunda Guerra Mundial" "Obtén la documentación del framework web fastify"
Y automáticamente determina qué bibliotecas buscar, ejecuta las consultas en paralelo y devuelve resultados unificados.
Aquí está la versión honesta:
46 fuentes funcionan sin claves de API. Si solo quieres buscar en arXiv, Project Gutenberg, el repositorio de Oxford, el repositorio de Cambridge, Europe PMC, PLOS, OpenAlex, los Archivos Nacionales de EE. UU., la legislación del Reino Unido y docenas de otros, puedes hacerlo ahora mismo sin registrarte en nada.
La única clave que mejora significativamente la experiencia es tu clave de API de OpenAI, que potencia la búsqueda en lenguaje natural (library_ask). Sin ella, aún puedes buscar en fuentes específicas directamente, solo tienes que nombrar la fuente tú mismo.
Todo lo demás es opcional. Cada clave adicional desbloquea una fuente específica. Elige las que sean relevantes para lo que estás investigando. Ignora el resto.
Related MCP server: Paper Search MCP
Abre tu terminal y comprueba:
node --versionSi muestra v22.x.x o superior, estás listo. Si no, descarga la última versión LTS desde nodejs.org.
git clone https://github.com/suavecito585/alexandria-mcp.git
cd alexandria-mcp
npm install
npm run buildEsto toma unos 30 segundos. Cuando termine, verás aparecer una carpeta dist/. Ese es el servidor compilado.
Anota la ruta completa a esta carpeta; la necesitarás en el siguiente paso. En Mac/Linux puedes ejecutar pwd para imprimirla. En Windows, cd por sí solo imprime la ruta actual.
Busca tu archivo de configuración de Claude Desktop:
Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Ábrelo en cualquier editor de texto. Si ya tiene otros servidores MCP configurados, añade Alexandria junto a ellos. Si está vacío o es nuevo, usa esto como punto de partida:
{
"mcpServers": {
"alexandria": {
"command": "node",
"args": ["/full/path/to/alexandria-mcp/dist/index.js"],
"env": {
"TRANSPORT": "stdio"
}
}
}
}Reemplaza /full/path/to/alexandria-mcp con la ruta real del Paso 2.
Reinicia Claude Desktop después de guardar el archivo.
Para verificar que funcionó, pídele a Claude: "Use library_list_sources to show all available sources." Deberías ver las 61 fuentes listadas.
Sin esto, tienes que nombrar la fuente cada vez que busques, por ejemplo: "search arxiv for transformer papers". Con ella, puedes simplemente decir "find me papers on transformer models" y Alexandria averigua qué fuentes consultar.
Obtén tu clave en platform.openai.com/api-keys. Cuesta una fracción de centavo por búsqueda (la llamada de enrutamiento usa gpt-4o-mini, ~$0.0002 por consulta).
Añádela al bloque env en tu configuración:
"env": {
"TRANSPORT": "stdio",
"OPENAI_API_KEY": "sk-..."
}Reinicia Claude Desktop de nuevo.
library_ingest te permite fragmentar, incrustar y almacenar contenido de texto completo en una base de datos vectorial para su recuperación posterior. Esto solo es útil si estás construyendo una canalización RAG de investigación. Si solo quieres buscar y leer, omite esto por completo.
Si lo deseas:
Crea un proyecto gratuito en supabase.com
Ve al editor SQL y ejecuta esto:
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);Añade al bloque env de tu configuración:
"SUPABASE_URL": "https://your-project.supabase.co",
"SUPABASE_SERVICE_ROLE_KEY": "eyJ..."Encontrarás ambos valores en tu proyecto de Supabase en Settings → API.
Aquí tienes cada clave opcional, agrupada por cuánto esfuerzo requieren y qué obtienes.
Todas estas son gratuitas. El registro es inmediato o casi inmediato.
Qué obtienes | Dónde registrarse | Nombre de la clave en la configuración |
CORE — Más de 57M de artículos de texto completo en acceso abierto, la mayor colección disponible |
| |
Semantic Scholar — Más de 200M de artículos con recomendaciones impulsadas por IA y grafos de citas |
| |
NASA ADS — El portal principal para literatura de astronomía, astrofísica y física |
| |
Smithsonian — 14M de registros en todos los museos Smithsonian (la misma clave funciona para GovInfo) |
| |
Springer Nature — Más de 16M de artículos en Springer y BioMed Central |
| |
Zenodo — Repositorio de investigación abierta del CERN, límites de tasa más altos |
| |
BHL — Biodiversity Heritage Library, siglos de literatura de historia natural |
| |
DigitalNZ — Colecciones digitales nacionales de Nueva Zelanda |
| |
DPLA — Digital Public Library of America |
| |
Europeana — Más de 50M de artículos de museos y archivos europeos |
| |
Token de GitHub — necesario para OpenITI (más de 10k textos islámicos). No se requieren alcances especiales. |
|
Qué obtienes | Dónde registrarse | Nombre de la clave en la configuración |
CourtListener — Jurisprudencia federal y estatal de EE. UU. en texto completo |
| |
Trove — Biblioteca Nacional de Australia, periódicos y libros digitalizados |
|
BASE te ofrece más de 400M de registros de más de 11,000 proveedores académicos: el índice más grande que admitimos. Es gratuito, pero requiere enviar un correo electrónico a su equipo para incluir tu dirección IP en la lista blanca. Suele tardar entre 2 y 3 días hábiles.
Selecciona "Access BASE's HTTP API" en el menú desplegable de asunto
Incluye tu dirección IP (encuéntrala en whatismyip.com) y una breve descripción de tu caso de uso (por ejemplo, "agregación de investigación no comercial")
Espera su respuesta: incluirán tu IP en la lista blanca
Una vez aprobado, añade a tu configuración: "BASE_API_KEY": "" (el valor puede estar vacío si usan autenticación solo por IP, o te darán un token).
Qué obtienes | Notas | Nombre de la clave en la configuración |
Google Books — Más de 40M de libros, texto completo para títulos de dominio público | Crea un proyecto en Google Cloud Console, habilita la API de Books, crea una clave de API |
|
GovInfo — Registro del Congreso de EE. UU., Registro Federal | Regístrate en api.govinfo.gov/docs — la misma clave también funciona para Smithsonian |
|
Cada clave va en el bloque env. Tu configuración final podría verse así (incluye solo las claves que realmente hayas obtenido):
{
"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..."
}
}
}
}Recuerda reiniciar Claude Desktop cada vez que cambies la configuración.
Aquí hay algunas cosas para probar una vez que estés configurado:
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 fuentes no necesitan clave de API. Funcionan en el momento en que instalas:
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 (Japón)
15 fuentes necesitan una clave de API gratuita:
CORE, Semantic Scholar, NASA ADS, Smithsonian, Springer Nature, Zenodo, BHL, DigitalNZ, DPLA, Europeana, GitHub (OpenITI), CourtListener, Trove, Google Books, BASE (lista blanca de IP)
MIT — úsala como quieras.
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.
