Lore Agent
Scholar Agent
Los LLM de propósito general suelen ser inexactos y estar desactualizados en dominios especializados. Scholar Agent combina investigación en línea + acumulación de conocimiento local en un volante de inercia de conocimiento sostenible, haciendo que su IA sea más inteligente en su dominio con el tiempo. También construye una base de conocimiento legible por humanos para un aprendizaje rápido. Se integra perfectamente con Claude Code y VS Code Copilot a través de MCP.
Qué hace
Your question
│
▼
Online research (LLM web search + academic APIs)
│
▼
Structured synthesis (with citations, confidence, uncertainty)
│
▼
Local accumulation (Markdown knowledge cards + BM25 index)
│
▼
Next question: AI checks local first ── hit? ──► use directly, fast & accurate
│ miss
▼
Research again → accumulate → reindex ──► knowledge base keeps growingCada ronda se compone. Las tarjetas de conocimiento tienen una gestión completa del ciclo de vida: borrador → revisado → confiable → obsoleto → desaprobado.
Related MCP server: ContextAtlas
Pipeline de investigación académica
Scholar Agent incluye un pipeline integral de investigación de artículos académicos:
Búsqueda de artículos — Busque artículos en arXiv, DBLP y Semantic Scholar. Filtre por las principales conferencias (CVPR, ICCV, ECCV, ICLR, AAAI, NeurIPS, ICML, ACL, EMNLP, MICCAI)
Puntuación inteligente — Motor de puntuación de cuatro dimensiones (relevancia, actualidad, popularidad, calidad) que clasifica los artículos según sus intereses de investigación
Notas de análisis profundo — Generación automática de más de 20 secciones de notas en formato markdown estilo Obsidian con marcadores de posición
<!-- LLM: -->para completar con asistencia de IAExtracción de figuras — Extraiga imágenes de archivos fuente de arXiv y PDF (a través de PyMuPDF)
Recomendaciones diarias — Búsqueda diaria automatizada de artículos, puntuación, deduplicación y generación de notas de recomendación
Artículo → Tarjeta de conocimiento — Convierta los análisis de artículos en tarjetas de conocimiento que se retroalimentan al volante de inercia del conocimiento
Autoenlace de palabras clave — Escanee notas en busca de términos técnicos y cree
[[wiki-links]]automáticamente
Inicio rápido
Integrar en un proyecto existente
cd my-project && git clone https://github.com/zfy465914233/scholar-agent.git
bash scholar-agent/setup.sh
# Restart Claude Code to activateEsto creará la estructura de directorios, copiará las plantillas de configuración, instalará las habilidades y construirá el índice de conocimiento.
Usar como proyecto independiente
# Clone and install
git clone https://github.com/zfy465914233/scholar-agent.git
cd scholar-agent
pip install -r requirements.txt
# Build the knowledge index
python scripts/local_index.py --output indexes/local/index.jsonLas configuraciones de MCP están preconfiguradas:
Claude Code:
.mcp.jsonestá listo.cden el proyecto e inicie Claude Code.VS Code Copilot:
.vscode/mcp.jsonestá listo. Abra el proyecto, habilite el modo agente.
Herramientas MCP
Herramientas principales (siempre disponibles)
Herramienta | Descripción |
| Buscar en la base de conocimiento local |
| Guardar resultados de investigación estructurados como una tarjeta de conocimiento |
| Explorar todas las tarjetas de conocimiento |
| Captura rápida de un par de preguntas y respuestas como tarjeta de borrador |
| Ingerir una URL o texto sin formato en la base de conocimiento |
| Generar un gráfico de conocimiento interactivo (vis.js) |
Herramientas académicas (establezca SCHOLAR_ACADEMIC=1 para habilitar)
Herramienta | Descripción |
| Buscar en arXiv + Semantic Scholar con puntuación de 4 dimensiones |
| Buscar artículos de conferencias a través de DBLP + enriquecimiento S2 |
| Generar notas de análisis profundo en markdown (más de 20 secciones) |
| Extraer figuras de la fuente de arXiv / PDF |
| Convertir el análisis de un artículo en una tarjeta de conocimiento |
| Flujo de trabajo de recomendación diaria de artículos |
| Autoenlace de palabras clave como |
Flujo de trabajo recomendado
Para obtener la mejor calidad de análisis, siga este orden:
Descargar el artículo:
download_paper("2510.24701", title="Paper Title", domain="LLM")Extraer imágenes:
extract_paper_images("2510.24701")(detecta automáticamente el PDF local)Análisis profundo:
analyze_paper(paper_json)(detecta automáticamente el PDF local, extrae el texto completo)
Consejo: Descargar el PDF antes del análisis permite la extracción de texto completo, produciendo notas de alta calidad con datos específicos, fórmulas y resultados experimentales. Sin un PDF local, el análisis se basa solo en el resumen.
Configuración
.scholar.json
El archivo .scholar.json configura las rutas de conocimiento y los ajustes de investigación académica. Consulte .scholar.example.json para ver un ejemplo completo con comentarios.
Secciones clave:
knowledge_dir— Ruta al directorio de tarjetas de conocimientoindex_path— Ruta al índice de búsqueda BM25academic.research_interests— Sus dominios de investigación, palabras clave y categorías de arXivacademic.scoring— Pesos y dimensiones de puntuación de artículos
Variables de entorno
Copie .env.example a .env y configure:
Variable | Requerido | Descripción |
| No | Establecer en |
| No | Clave de API de Semantic Scholar (obtenga una gratis) |
| No | Clave de API de LLM para el pipeline de síntesis avanzada |
Estructura del proyecto
scholar-agent/
├── mcp_server.py # MCP server (13 tools)
├── setup_mcp.py # Embed into existing projects
├── pyproject.toml # Package configuration
├── .scholar.json # Project & academic configuration
├── schemas/ # Answer + evidence JSON schemas
├── scripts/
│ ├── academic/ # Academic research modules
│ │ ├── arxiv_search.py # arXiv + Semantic Scholar search
│ │ ├── conf_search.py # Conference paper search (DBLP)
│ │ ├── paper_analyzer.py # Deep-analysis note generation
│ │ ├── scoring.py # 4-dim paper scoring engine
│ │ ├── image_extractor.py # Figure extraction from PDFs
│ │ ├── note_linker.py # Wiki-link discovery + keyword linking
│ │ └── daily_workflow.py # Daily recommendation pipeline
│ ├── scholar_config.py # Configuration reader
│ ├── local_index.py # BM25 index builder
│ ├── local_retrieve.py # Knowledge retrieval
│ ├── close_knowledge_loop.py # Knowledge card builder
│ └── ... # Research, synthesis, governance, graph
├── knowledge/ # Knowledge cards (gitignored, user-generated)
├── indexes/ # Generated indexes (gitignored)
└── tests/ # 247 testsMás características
Investigación desde múltiples perspectivas — Investigación paralela desde 5 perspectivas (académica, técnica, aplicada, contraria, histórica)
Compatible con Obsidian — Markdown estándar + YAML frontmatter +
[[wiki-links]]CLI de gobernanza del conocimiento — Validar frontmatter, detectar tarjetas huérfanas, encontrar duplicados, gestionar el ciclo de vida
Tolerancia a fallos del proveedor — Cada fuente de búsqueda falla de forma independiente; vuelve a la recuperación local cuando está desconectado
Pruebas
python -m pytest tests/ -v247 pruebas, ~13s. No se necesitan servicios externos.
Licencia
MIT — consulte LICENSE.
Available Tools
12 toolsbuild_graphA
Build an interactive knowledge graph visualization.
Generates a self-contained HTML file showing all knowledge cards as nodes and their wiki-links as edges. Open the output file in a browser to explore the knowledge graph visually. Compatible with Obsidian vaults.
Returns the path to the generated graph.html file.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It discloses that the tool generates a self-contained HTML file and returns its path. Potential side effects like processing time for large knowledge bases are not mentioned, which prevents a 5.
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 relatively concise with four sentences. The first sentence clearly states the purpose, and subsequent sentences add details. However, the phrase 'self-contained HTML file' could be merged with the next sentence to reduce redundancy. Still, it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, no parameters, and the presence of an output schema (which likely describes the return path), the description is complete enough to guide an agent. It covers what the tool does, the output format, and even compatibility. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the description fully compensates by explaining what the tool does without needing to describe parameter semantics. The description adds value beyond the schema by detailing the output and compatibility with Obsidian vaults.
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 verb 'build' and the resource 'knowledge graph visualization.' It distinguishes itself from sibling tools by specifying it generates an interactive HTML graph, unlike query_knowledge or list_knowledge. The purpose is specific and 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?
While there is no explicit when-to-use or when-not-to-use guidance, the description implies use when wanting to visualize knowledge cards as nodes and wiki-links as edges. None of the sibling tools serve a similar purpose, so differentiation is naturally clear. A slight improvement would be to explicitly mention not to use for non-graph queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
capture_answerA
Capture a useful Q&A answer as a draft knowledge card.
Use this ONLY when a conversation produces a SUBSTANTIVE answer that is worth persisting — meaning it provides genuine technical insight, a non-obvious explanation, or actionable knowledge that cannot be found in standard references.
DO NOT use this tool for:
Single-sentence answers or brief definitions
Answers that could be found in any standard reference (Wikipedia, docs)
Trivial facts, simple yes/no responses, or content shorter than 150 characters
Paper or topic-level knowledge that requires source verification
If you have structured evidence and claims, prefer save_research instead — it produces higher-quality cards with proper source attribution.
The answer text MUST be at least 150 characters. Write a thorough explanation covering the key insight, context, and practical implications.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Comma-separated tags for the card (optional). | |
| query | Yes | The question that was answered. | |
| answer | Yes | The answer text (plain text or markdown). Minimum 150 characters. | |
| language | No | Language for the card content — "zh" (Chinese, default) or "en" (English). | zh |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses the 150-character minimum, content expectations, and the type of answer suitable. However, it does not mention any side effects or authorization requirements, though the tool is likely non-destructive. Overall, good transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and then provides clear usage guidelines in a bullet-like structure. While slightly verbose, every sentence adds value, and the structure is logical and easy to parse.
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 output schema present and full schema coverage, the description covers purpose, usage guidelines, parameter semantics, and context relative to siblings. It is complete enough for an AI agent to correctly select and invoke the 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 coverage is 100%, but the description adds significant value: clarifies tags as optional, language defaults, and importantly the 150-character minimum for answer. It also explains the expected content quality, which goes beyond the schema's description.
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 captures a Q&A answer as a draft knowledge card, specifying it is for substantive answers from conversations. The verb 'capture' and resource are distinct and well-defined, and it differentiates from sibling tools like 'save_research'.
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?
Explicitly states when to use (substantive answers worth persisting) and when not to use (single-sentence, standard references, etc.), and provides a clear alternative: 'save_research' for structured evidence. This gives excellent guidance to an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fetch_urlA
Fetch a web URL and return its main content as markdown — first-hand retrieval (G5).
抓取网页正文(已做 HTML→正文提取)返回给调用方,用于在 save_research 之前把
knowledge card 建立在一手出处之上,而非凭记忆或摘要。同时把完整正文存本地
快照 knowledge/_snapshots/<sha1(url)>.md(含 captured_at),防止原链接失效
(招聘 JD、网页易下架)后无法回溯(G2)。
典型用法:fetch_url 抓一手 → 基于正文写带具体数字/机制的深度 answer → save_research 存卡。
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | 要抓取的 http(s) URL。 | |
| max_chars | No | 返回 content_md 的最大字符数(默认 6000;完整正文在快照里)。 |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: it saves a local snapshot with captured_at to prevent link rot, and the returned content_md is truncated by max_chars while full content is in the snapshot. Since no annotations are provided, the description fully carries the burden of behavioral disclosure.
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 informative but somewhat verbose, mixing English and Chinese. It includes a typical usage flow that adds value, but could be streamlined. It is structured with clear sections but overall slightly long for a tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (external fetch, snapshot, truncation) and the presence of an output schema (so no need to detail return values), the description is complete. It covers purpose, behavior, usage flow, and parameter implications adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both params (url and max_chars). The description adds context: max_chars controls returned content length and that full content is in the snapshot, which is beyond the schema's default value and description. Baseline 3 plus extra value justifies 4.
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 action: 'Fetch a web URL and return its main content as markdown.' It emphasizes first-hand retrieval (G5) and distinguishes itself from siblings like save_research, which saves knowledge cards, and query_knowledge, which retrieves stored knowledge.
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 a typical usage flow: 'fetch_url to fetch primary source → write deep answer with specific numbers/mechanisms → save_research to save card.' It explicitly connects to the sibling tool save_research and implies when to use (before saving). However, it doesn't explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
import_paperpulse_noteA
Import a distilled paper note from PaperPulse SaaS directly into the local Scholar Agent knowledge base.
| Name | Required | Description | Default |
|---|---|---|---|
| paper_id | Yes | The UUID of the paper to import. | |
| api_token | No | Optional API token. If not provided, reads 'paperpulse_token' from config.json. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states the action but does not disclose side effects (e.g., overwriting existing notes), authentication requirements beyond the optional token, or validation 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?
A single, grammatically correct sentence that conveys the core purpose without any unnecessary words or 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?
While an output schema exists, the description lacks context about the PaperPulse integration, prerequisites, and how it differs from ingest_source. This is adequate but not fully complete for a tool with specific external dependency.
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 schema already documents both parameters adequately. The description adds no additional meaning 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 clearly states a specific verb ('Import') and resource ('distilled paper note from PaperPulse SaaS into local Scholar Agent knowledge base'), which distinguishes it from siblings like ingest_source or save_research that are more generic.
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 the tool is for importing from PaperPulse but provides no explicit guidance on when to use it vs alternatives, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ingest_sourceA
Ingest a URL or raw text into the knowledge base as a draft card.
For URLs: fetches the page content, extracts text, and saves as a card. For text: saves the provided text directly as a card.
Use this when you want to add external documents, articles, or notes to the knowledge base without requiring structured JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Comma-separated tags for the card (optional). | |
| title | No | Optional title for the card. Auto-detected from URL pages. | |
| source | Yes | A URL (starting with http:// or https://) or raw text/markdown. When providing raw text and language="zh", the text MUST be in Chinese (中文). | |
| language | No | Language for the card content — "zh" (Chinese, default) or "en" (English). When "zh" and providing raw text, ensure the content is in Chinese. For URL sources, the content language is determined by the original page. | zh |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that for URLs it fetches page content and extracts text, and for text it saves directly. However, it does not cover potential errors, idempotency, or what 'draft card' entails (e.g., whether it's editable). This is adequate but not comprehensive.
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 concise, front-loaded with the core action, and uses clear bullet-like statements for URL vs text behavior. Every sentence adds value 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 tool's complexity (4 parameters, simple types, output schema exists), the description covers the main use cases and key behaviors. It could mention error handling or the draft card concept more explicitly, but overall it is sufficient for an agent to use 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?
Schema coverage is 100% (all 4 parameters described). The description adds value by explaining the behavioral difference between URL and text input, and emphasizing the language constraint for Chinese text ('MUST be in Chinese'). This goes beyond the schema descriptions for 'source' and 'language', making parameter semantics clearer.
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 ingests a URL or raw text into the knowledge base as a draft card, with specific behaviors for each type. It distinguishes from sibling tools like fetch_url (which only fetches) and save_research (which likely expects structured JSON) by emphasizing 'without requiring structured JSON'.
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 says 'Use this when you want to add external documents, articles, or notes to the knowledge base without requiring structured JSON,' providing clear context. It implies not to use for structured data but does not name specific alternatives, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lint_knowledgeA
Run read-only content health checks over the local knowledge base.
Reports orphan cards, broken wiki-links, cards not updated within stale_days, and highly overlapping titles. This tool never edits files.
| Name | Required | Description | Default |
|---|---|---|---|
| stale_days | No | Age threshold in days for the updated_at lint check. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden. It explicitly states the tool is read-only and never edits files, and enumerates the exact checks performed, providing complete transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the purpose and listing actions without any filler. Every sentence contributes value.
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 one parameter, no annotations, and an output schema (inferred), the description covers the tool's scope well. It mentions all performed checks and the parameter.
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 single parameter 'stale_days' is fully described in the input schema. The tool description already mentions stale_days in context, so the description adds minimal extra meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action: 'Run read-only content health checks' on the 'local knowledge base.' It lists the specific checks (orphan cards, broken wiki-links, stale cards, overlapping titles) and states it never edits files, making the purpose distinct from siblings.
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 for health checks but does not explicitly state when to use this tool versus alternatives like scan_dead_links or scan_stale_knowledge. However, it is clear that this is a composite check tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_knowledgeA
List all knowledge cards in the local knowledge base.
Returns card metadata (id, title, topic, type) for browsing and discovery.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Optional topic filter (e.g. 'qpe', 'markov_chain'). Returns all if omitted. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes a read-only listing operation with no side effects, but does not disclose any potential limitations like pagination or performance considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core purpose and list return fields. No wasted words or repetition.
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 existing, the description adequately covers the tool's purpose and basic parameter. It could mention it's a local knowledge base listing, but overall it is complete for simple browsing.
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% for the single optional parameter. The description adds minimal extra meaning beyond the schema, stating it's optional and returns all if omitted. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and resources: 'List all knowledge cards' and returns specific metadata fields. It clearly distinguishes from siblings like 'query_knowledge' which likely searches or filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The context of sibling tools implies it's for browsing all cards or filtering by topic, but no alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
query_knowledgeA
Search the local knowledge base for relevant information.
Returns top-k knowledge cards matching the query, with scores and content. Use this to find existing knowledge before doing web research.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (default 5). | |
| query | Yes | The search query in natural language. | |
| rerank | No | When true, fetches limit*3 candidates and uses an LLM cross-encoder to score each (query, candidate) pair on 0-10 relevance. Improves top-1 precision for ambiguous queries at the cost of one LLM call per candidate (~2s each). Default false. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose behavior. It describes return format (top-k, scores, content), implying read-only. Could add more detail on response structure, but sufficient for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with a clear usage directive. Zero fluff, every sentence adds value.
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, description doesn't need to detail return values. It covers purpose, usage, and basic input semantics. Complete enough for a simple search 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 coverage is 100%, so parameters are already well-documented in the schema. The description adds no further semantic meaning beyond the schema's own descriptions, meeting baseline expectations.
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 searches the local knowledge base, returns top-k cards with scores and content, and distinguishes it from sibling tools like fetch_url or save_research.
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?
Explicit guidance to 'use this to find existing knowledge before doing web research' tells the agent when to invoke this tool and implies alternatives (web research tools).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
save_researchA
Save structured research results as a knowledge card in the local knowledge base.
The answer_json must conform to schemas/answer.schema.json: { "answer": "detailed answer text", "supporting_claims": [{"claim": "...", "evidence_ids": ["..."], "confidence": "high|medium|low"}], "inferences": ["..."], "uncertainty": ["..."], "missing_evidence": ["..."], "suggested_next_steps": ["..."], "sources": ["https://example.com/source1", "https://example.com/source2"], "visual_aids": [{"type": "mermaid|image_url|image_path", "content": "...", "caption": "...", "alt_text": "..."}] }
IMPORTANT quality requirements:
The "answer" field MUST be at least 200 characters of substantive content.
You MUST include at least 1 supporting_claim with evidence_ids and confidence.
Each claim text MUST be at least 20 characters — vague one-word claims are rejected.
DO NOT create cards with empty supporting_claims — every card needs evidence-backed claims.
Aim for 3+ supporting claims, inferences, uncertainty, and suggested_next_steps for high-quality cards.
DO NOT use this tool for trivial facts or one-sentence answers — those are not worth persisting.
ALWAYS include a "sources" array with the URLs you referenced during research. These are written to the card's frontmatter source_refs for provenance tracking.
evidence_ids in supporting_claims SHOULD cite the source URL (from "sources") — the card renders them as clickable
[host](url)source links. Opaque ids like "s1" stay as bare text and lose the link.For first-hand depth: call
fetch_urlon key sources BEFORE writing the answer, so it cites concrete numbers/mechanisms from the actual page (not memory). fetch_url also archives a local snapshot (knowledge/_snapshots/) so dead links stay traceable. save_research best-effort snapshots any listed sources in the background even without an explicit fetch_url.When language="zh" (default), the entire answer field MUST be written in Chinese (中文). When language="en", write in English.
When to include visual_aids (auto-judge by topic):
Processes / workflows / data flow → mermaid flowchart or sequence diagram
Architecture / system design → mermaid graph or class diagram
Comparisons or hierarchies → mermaid diagram or table
Spatial / geometric concepts → image_url or mermaid
Pure definitions or simple facts → omit visual_aids
When sources contain useful images (charts, diagrams, figures):
If a source page has a relevant diagram/chart with clear explanatory value, include it as visual_aids with type "image_url" and the image's absolute URL
Judge relevance: prefer diagrams explaining mechanisms, architecture overviews, comparison charts, result plots — skip decorative screenshots or generic stock photos
Always provide a descriptive caption explaining what the image shows
For method/procedural content (how-to, implementation, deployment, etc.), also include:
expected_output: Description of what a successful result looks like — output format, shape, key metrics, or acceptance criteria. Synthesize from the answer if sources don't explicitly provide this.
example: A minimal worked example (sample input → processing steps → expected output). Construct synthetically based on the answer if sources lack one. Write '[insufficient data — needs supplementation]' only if impossible to construct.
Visual aids placement (optional after_section field):
"answer" — insert after the main answer paragraph (default for architecture/pipeline diagrams)
"supporting_claims" — insert after claims (default for evidence figures/charts)
"inferences", "uncertainty", "missing_evidence", "suggested_next_steps" — after respective sections
Omit after_section to place at the end of the card (backward compatible)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The original research question. | |
| domain | No | Optional domain/folder name for the card (e.g. "quant-backtest"). When provided, the card is placed directly under knowledge/<domain>/ and all auto-routing (AI, folder matching, heuristic) is skipped. | |
| language | No | Language for the card content — "zh" (Chinese, default) or "en" (English). When "zh", the answer, claims, inferences, and all other text fields MUST be in Chinese. | zh |
| card_type | No | Optional explicit card type — "engineering" (a step-by-step implementation playbook with prerequisites/implementation_steps/verification/pitfalls/rollback), "method", or "knowledge". If omitted, inferred from query + content. Use "engineering" for how-to / landing / deployment knowledge so it renders as actionable steps instead of an abstract research summary. | |
| answer_json | Yes | JSON string with the structured answer. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it creates knowledge cards, enforces quality requirements, and best-effort snapshots source URLs. It explains side effects like background snapshots and the persistence of cards, which is sufficient for a non-destructive write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy and includes many details that could be separated or placed in schema annotations. While it is well-organized with headings (IMPORTANT, When to include, etc.), it is not concise and may overwhelm agents scanning for quick purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no annotations, output schema exists), the description is exceptionally complete. It covers output format, quality constraints, visual aid placement, source handling, and language rules, leaving no ambiguity about what the tool does and expects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description dramatically adds value by elaborating on the answer_json structure, quality rules, language expectations, visual_aids inclusion logic, and source referencing. This far exceeds the brief schema descriptions, making parameter usage clear and correct.
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 clear verb+resource: 'Save structured research results as a knowledge card in the local knowledge base.' This explicitly states the tool's function and distinguishes it from read-only or ingestion tools like query_knowledge or ingest_source.
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 warns against using the tool for 'trivial facts or one-sentence answers,' but it provides no explicit guidance on when to choose this tool over siblings like capture_answer or validate_knowledge. The absence of alternatives or when-not-to-use scenarios limits its usefulness for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
scan_dead_linksA
Diagnose dead source URLs (404/410/connection failure) across knowledge cards.
Probes each unique source_refs URL once (HEAD first, GET fallback) and fans
the result out to every card that cites it. Paywalled domains are reported
as blocked; offline=True marks every URL skipped. Read-only — never
edits cards or snapshots.
| Name | Required | Description | Default |
|---|---|---|---|
| offline | No | Skip all network probes. | |
| timeout | No | Per-request timeout in seconds. | |
| concurrency | No | Maximum concurrent URL probes. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully covers behavior: probing strategy (HEAD then GET), result fan-out, handling of paywalled (blocked) and offline (skipped), and explicitly states read-only. No contradictions.
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 concise sentences, front-loaded with purpose, no fluff. Each sentence adds distinct information (purpose, method, constraints).
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 output schema exists, no need to explain return values. Parameters are fully covered in schema and description. Complexity is moderate; description handles all aspects clearly.
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 description adds value: offline=skip network probes, timeout=per-request, concurrency=maximum concurrent probes. Only minor gap: no format details beyond 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?
Description starts with 'Diagnose dead source URLs' (specific verb+resource) and clarifies scope 'across knowledge cards.' Distinguishes from siblings like fetch_url (single URL fetch) and scan_stale_knowledge (stale content).
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?
Implies usage for diagnosing dead links, but lacks explicit when-to-use or when-not-to-use vs. alternatives. Could mention not for single URL checking (fetch_url) or content validation (validate_knowledge).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
scan_stale_knowledgeA
Report knowledge cards whose source freshness exceeds domain thresholds.
Unlike lint_knowledge's updated_at check, this uses source_date/captured year with the domain-specific freshness policy used by card validation. This tool is read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly declares read-only behavior, which is critical since no annotations are provided. Describes the evaluation basis (source_date/captured year and domain policy), but doesn't mention other behaviors like performance or error handling.
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: purpose, sibling differentiation, read-only statement. Every sentence is necessary and front-loaded with purpose. No redundant 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?
Given no parameters and an output schema exists, the description covers input (none), criteria (source freshness vs threshold), behavior (read-only), and sibling context. No gaps for a simple reporting 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?
No parameters in schema, so baseline is 4. Description does not need to add parameter info. The description adds no param-specific details, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Report knowledge cards whose source freshness exceeds domain thresholds' – specific verb and resource with exact criterion. Contrasts with lint_knowledge to differentiate purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (check source freshness with domain-specific policy) and distinguishes from lint_knowledge by specifying different date field and policy, providing alternative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_knowledgeA
Validate local knowledge cards without modifying files.
Runs card frontmatter validation plus body-density/source-freshness checks. Use this before relying on a knowledge base or after bulk imports.
| Name | Required | Description | Default |
|---|---|---|---|
| verbose | No | When true, include warning-only cards in the per-card report. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description clearly states 'without modifying files' and lists validation types (frontmatter, body-density, source-freshness). No behavioral surprises.
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: purpose, scope, usage. No fluff. Front-loaded with key action and resource.
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 simple tool (1 optional param, output schema exists), description covers purpose, behavior, and usage. Adequate for AI agent decision-making.
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%, and description adds context for the verbose parameter: 'include warning-only cards in the per-card report.' Adds value beyond 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 explicitly states 'Validate local knowledge cards' with a specific verb and resource. It distinguishes from siblings like lint_knowledge by mentioning body-density/source-freshness checks.
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?
Gives clear usage context: 'Use this before relying on a knowledge base or after bulk imports.' Does not explicitly contrast with alternatives, but the guidance is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
12 tool updates
v0.1.0- First observed
build_graph - First observed
capture_answer - First observed
fetch_url - First observed
import_paperpulse_note - First observed
ingest_source - First observed
lint_knowledge - First observed
list_knowledge - First observed
query_knowledge - First observed
save_research - First observed
scan_dead_links - First observed
scan_stale_knowledge - First observed
validate_knowledge
TDQS
Scored across 12 tools
Most tools have distinct purposes (query, save, ingest, validate, fetch, list, lint, scan, build, import). However, save_research, capture_answer, and ingest_source all persist knowledge cards with different input formats, which could cause confusion despite detailed descriptions.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., query_knowledge, save_research, fetch_url). Verbs are descriptive and the pattern is predictable across all 12 tools.
12 tools is well-scoped for a knowledge management server. The set covers querying, saving, ingesting, validating, listing, linting, scanning dead links, building graphs, and importing notes—no bloat or deficiency.
The tool surface covers create (save, capture, ingest), read (query, list), and checking tools, but lacks update and delete operations for knowledge cards. This is a notable gap that could hinder full life cycle management.
Maintenance
Related MCP Connectors
The project brain for AI coding agents — memory, decisions, sprints, knowledge base via MCP.
