Provides semantic search, project context, task extraction, decision logs, and related notes retrieval from an Obsidian vault, with support for frontmatter, wikilinks, and backlinks.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SecondBrain MCP list my active projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Safe MCP-сервер для Obsidian vault. Даёт AI-ассистентам (Claude, ChatGPT и др.) семантический доступ к заметкам, проектам, решениям и задачам, а также безопасные операции создания и подтверждённого редактирования.
Вместо сырого доступа к файлам предоставляет структурированные инструменты:
Tool | Описание |
| Статус vault и статистика |
| Полнотекстовый поиск + фильтры по frontmatter |
| Чтение заметки по пути или имени |
| Список заметок с метаданными, |
| Batch-чтение нескольких заметок для сборки LLM-контекста |
| Метаданные заметки: frontmatter, hash, links, backlinks, tags, line count |
| Проверка безопасности пути для чтения или записи |
| Создание новой markdown-заметки с YAML-frontmatter |
| Подготовка diff без записи файла |
| Применение подтверждённой правки с |
| Добавление блока в заметку или секцию |
| Чтение памяти агента из |
| Добавление правила, ошибки, примера, проекта, роли или стиля в память агента |
| Список проектов с фильтром по статусу |
| Полный контекст проекта: содержимое + связи + задачи + решения |
| Связанные заметки через wikilinks, backlinks, общие теги |
| Открытые/завершённые задачи из vault или папки |
| Записи из журнала решений |
Related MCP server: Obsidian MCP Server
MCP v0.3 поддерживает запись, но не даёт агенту тихо перезаписывать vault.
Клиент получает hash через list_notes или get_note_metadata.
Клиент вызывает propose_note_update и показывает пользователю diff.
Пользователь подтверждает изменение в UI.
Клиент вызывает apply_note_update с confirmed: true и тем же expected_hash.
Если файл изменился между шагами, MCP вернёт ошибку hash mismatch.
Все операции записи проходят validate_vault_path. Запрещены абсолютные пути, выход за пределы vault, запись не-.md файлов и доступ к исключённым папкам.
Память агента хранится в:
00_Meta/AI-System/
role.md
rules.md
style.md
projects.md
mistakes.md
examples.mdДля second-brain-vault действует соглашение: новые заметки должны иметь YAML-frontmatter, поля type, status, created, updated, tags, aliases, related, а related должен ссылаться хотя бы на один MOC.
search_knowledge теперь использует ранжирование по нескольким полям:
title и имя файла;
aliases;
tags;
related;
markdown content.
Запрос нормализуется по пробелам, дефисам, /, _ и wikilink-синтаксису, поэтому AI Sprint может находить AI-Sprint, ai/sprint и [[AI Sprint]]. В ответе есть score, matches и snippet, чтобы UI мог показать, почему заметка попала в выдачу.
Рекомендуемый flow для приложения:
search_knowledge
→ read_notes_batch top-K
→ find_related / get_note_metadata при необходимости
→ LLM context buildergit clone <repo-url> && cd sb-mcp
npm install
npm run build
npm testOBSIDIAN_VAULT_PATH=/path/to/vault node dist/index.jsOBSIDIAN_VAULT_PATH=/path/to/vault \
MCP_AUTH_TOKEN=your-secret-token \
MCP_PORT=3100 \
node dist/index.js --httpВ HTTP-режиме задайте переменную MCP_AUTH_TOKEN для защиты доступа. Токен можно передать двумя способами:
1. Заголовок Authorization — для клиентов с поддержкой кастомных заголовков (Claude Code, API-клиенты):
Authorization: Bearer your-secret-token2. Query-параметр — для клиентов без поддержки заголовков (Claude.ai, ChatGPT):
https://your-server/mcp?token=your-secret-tokenЕсли MCP_AUTH_TOKEN не задан, сервер работает без аутентификации (не рекомендуется для публичных сетей).
Сгенерировать токен:
openssl rand -hex 32Переменная | По умолчанию | Описание |
| текущая директория | Путь к Obsidian vault |
|
| Режим транспорта: |
|
| Порт HTTP-сервера |
| — | Токен для аутентификации в HTTP-режиме |
.mcp.json)Stdio (локально):
{
"mcpServers": {
"secondbrain": {
"command": "node",
"args": ["/path/to/sb-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/vault"
}
}
}
}HTTP (удалённо):
{
"mcpServers": {
"secondbrain": {
"type": "url",
"url": "https://your-server/mcp",
"headers": {
"Authorization": "Bearer your-secret-token"
}
}
}
}Используйте URL с токеном в query-параметре:
https://your-server/mcp?token=your-secret-token# /etc/systemd/system/secondbrain-mcp.service
[Unit]
Description=SecondBrain MCP Server
After=network.target
[Service]
Type=simple
ExecStart=/usr/bin/node /path/to/sb-mcp/dist/index.js --http
Environment=OBSIDIAN_VAULT_PATH=/path/to/vault
Environment=MCP_AUTH_TOKEN=your-secret-token
Environment=MCP_PORT=3100
Restart=on-failure
[Install]
WantedBy=multi-user.targetИсключённые папки: .git, .obsidian, node_modules, 99_Private, _attachments, mcp
Типы заметок: project, area, resource, person, daily, moc, decision, inbox, about
Статусы: active, paused, done, someday
Frontmatter: YAML с полями type, status, created, updated, tags, aliases, related
Связи: [[wikilinks]] + related: в frontmatter + backlinks + общие теги
Оптимистическая блокировка: write-операции используют hash, чтобы UI применял только просмотренную пользователем версию файла
Append a rule, mistake, example, project, style, or role memory entry under 00_Meta/AI-System.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional memory tags | |
| type | Yes | Memory entry type | |
| content | Yes | Memory entry content | |
| source_path | No | Optional source note path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full weight. It only states the basic action without disclosing side effects, permissions, duplicate handling, or return behavior. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, very concise, and front-loaded with the verb. It wastes no words but could benefit from a bit more detail. Still good structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (2 required) and no output schema, the description is too brief. It lacks return value info, behavioral details, and comparison to sibling tools, leaving the agent underinformed.
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 described in the schema. The tool description mentions the allowed types but does not add further meaning beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Append'), the resource ('memory entry'), specifies the allowed types ('rule, mistake, example, project, style, or role'), and the location ('under 00_Meta/AI-System'). It is specific and distinguishes from sibling tools like 'read_agent_memory' (read vs write) and note tools.
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 no guidance on when to use this tool versus alternatives (e.g., 'append_to_note' or 'create_note'). There is no mention of prerequisites, exclusions, or context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append markdown to a note or section. Useful for Inbox, logs, and incremental memory entries.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative .md path inside the vault | |
| content | Yes | Markdown content to append | |
| section | No | Heading text to append under or create | |
| expected_hash | No | Optional optimistic-lock hash | |
| create_if_missing | No | Create the note if it does not exist |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It states the tool appends markdown, implying additive behavior, and mentions section support and create_if_missing parameter. However, it does not explain the return format, whether appending is to the end or under a heading, or potential side effects like overwriting sections. It adds some context but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with practical context, no filler or redundancy. It front-loads the core action and quickly conveys value. Every word 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 five parameters and no output schema, the description provides essential action context but omits information about return values or post-append behavior. It adequately distinguishes from siblings but leaves the agent guessing about what happens after invocation. Somewhat incomplete for a mutating tool with multiple parameters.
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 documents all parameters well. The description repeats the action theme ('Append markdown') without adding new meaning to individual parameters beyond what the schema provides. The use-case context might help an agent decide to use create_if_missing, but it does not explain parameter details. 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 a specific verb and resource: 'Append markdown to a note or section.' It distinguishes itself from sibling tools like create_note (which creates new notes) and apply_note_update (which might update more comprehensively) by focusing on appending. The use cases 'Inbox, logs, and incremental memory entries' further clarify its specific role.
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 suggests use cases: 'Useful for Inbox, logs, and incremental memory entries.' This provides context on when to use the tool. However, it does not explicitly state when not to use it or suggest alternatives, which would improve the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a confirmed note update. Requires confirmed=true and expected_hash to prevent accidental overwrites.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative .md path inside the vault | |
| backup | No | Create a backup under 00_Meta/AI-System/backups (default true) | |
| confirmed | Yes | Must be true after user confirmation | |
| new_content | Yes | New markdown body without YAML frontmatter | |
| expected_hash | Yes | Hash of the version the user reviewed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry disclosure weight. It mentions safety features (hash verification, backup by default) but lacks details on error handling, return values, or behavior on failure. Adequate but incomplete.
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 with no wasted words. Every part contributes meaning (verb, resource, key precondition).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema or annotations, the description covers core purpose and key constraint but omits return format, error scenarios, and detailed backup behavior. Adequate but not fully comprehensive.
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 description adds only marginal value by highlighting confirmed and expected_hash. Baseline 3 is appropriate; no extra parameter insights 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 clearly states the verb 'Apply' and resource 'confirmed note update', distinguishing it as a write operation that requires preconditions. It 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?
The description mentions required parameters (confirmed=true, expected_hash) to prevent accidental overwrites, providing clear context for when to use. However, it does not explicitly contrast with siblings like propose_note_update or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new markdown note safely. Requires frontmatter with type/status/related and refuses to modify existing files.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative .md path inside the vault | |
| content | Yes | Markdown body without YAML frontmatter | |
| dry_run | No | Return serialized hash without writing | |
| if_exists | No | Existing-file behavior; create_note refuses existing files | |
| frontmatter | Yes | YAML frontmatter object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool refuses to modify existing files, requires specific frontmatter fields, and is safe to use for creation. It does not mention auth or side effects, but for a creation tool, the main behavioral traits are sufficiently covered.
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 only two sentences, both of which add critical information. The first sentence front-loads the primary purpose and safety, and the second adds the frontmatter requirement and modification refusal. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, 3 required) and no output schema, the description adequately explains creation constraints and the non-overwrite behavior. It could mention what the tool returns, but the absence of output schema reduces that expectation.
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%, but the description adds valuable context beyond schema: it specifies that frontmatter must contain 'type/status/related', which is a constraint not present in the schema definition. This helps the agent prepare correct input.
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 'Create', the resource 'markdown note', and includes the safety constraint 'refuses to modify existing files'. This distinguishes it from sibling tools like 'append_to_note' or 'apply_note_update' which handle modifications.
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: to create a new note, and it specifies that the tool will error if the file exists. It does not explicitly list when not to use, but the sibling differentiation is implied by the name and behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract decisions from decision log folders (02_Areas/*/Decisions/). Optionally filter by area name. Sorted newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | Filter by area name (e.g. "EdTech", "B2B", "Content") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states 'Sorted newest first' and optional filtering, but lacks details on whether the operation is read-only, permissions needed, or the exact return format (e.g., fields returned). 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 two sentences with no fluff: first sentence states purpose and location, second adds filter and sorting. Every piece of information 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 no output schema, the description should clarify what is returned (e.g., titles, full decision text). It covers location, filtering, and ordering, but leaves output structure ambiguous, which is a gap for a simple 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% with the parameter description already explaining filtering. The description adds no new semantic value beyond restating the parameter is optional, and mentions sorting which is not a parameter. 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 states the tool extracts decisions from specific decision log folders (02_Areas/*/Decisions/), distinguishing it from sibling extract_tasks which extracts tasks. The verb 'Extract' and resource 'decisions' are 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?
The description implies usage for retrieving decisions and mentions optional area filtering, providing clear context. However, it does not explicitly exclude usage for other sibling tools like extract_tasks, nor does it describe when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract checkbox tasks (- [ ] / - [x]) from vault notes. Optionally scope to a folder. By default returns only open tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Scope to folder (e.g. "01_Projects" or "01_Projects/SimpleClaw") | |
| include_completed | No | Include completed tasks (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but offers minimal behavioral insight; it does not disclose return format, read-only nature, or performance characteristics, only the default open-task filter.
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 that front-load the core action and then add optional context; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two simple parameters and no output schema, the description is adequate but missing details on output format or limitations; overall sufficiently covers what the tool does.
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's mention of optional folder and default open tasks adds no value beyond the schema's own 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 clearly states the action (extract) and resource (checkbox tasks from vault notes), specifies the checkbox format, and distinguishes from sibling tools like extract_decisions.
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 retrieving tasks but provides no explicit when-to-use or when-not-to-use guidance compared to alternatives; it only mentions optional folder scoping and default behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a single note by path or name. Returns full content with parsed YAML frontmatter.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | Note path (relative to vault root) or note name/alias |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It identifies the operation as a read, but does not mention behavior on missing notes, error handling, permissions, or side effects. Important behavioral context is missing.
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: first states action and scope, second describes return content. No wasted words, front-loaded with key 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 simple single-parameter read tool, the description adequately covers purpose and return content. However, it lacks details on error behavior and return structure beyond frontmatter. Given no output schema, slightly more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'identifier' parameter (path or alias), and the description rephrases this without adding new semantics. With 100% schema coverage, baseline is 3; the description adds marginal value by noting the return includes parsed frontmatter.
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 reads a single note by path or name, distinguishing it from sibling tools like get_note_metadata (metadata only) and read_notes_batch (batch read).
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 use for retrieving a single note's full content, but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one note metadata: frontmatter, tags, mtime, hash, wikilinks, backlinks, line count.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | Note path, name, or alias |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It indicates a read operation returning a set of metadata fields but does not mention authentication, rate limits, or potential error conditions. The description is adequate but not detailed beyond the field list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with purpose and includes a list of returned metadata fields. It is concise, though slightly more structure (e.g., separate listing) could improve readability.
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?
No output schema exists, so the description must convey return values. It lists all metadata fields, which is sufficient for this simple tool. It does not describe response format but is otherwise complete given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, already documenting the identifier parameter as 'Note path, name, or alias'. The tool description adds no further meaning to the parameter, so 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?
Description clearly states 'Get one note metadata' and lists specific fields: frontmatter, tags, mtime, hash, wikilinks, backlinks, line count. This distinguishes it from sibling tools like get_note which presumably retrieves full 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?
No explicit guidance on when to use this tool versus alternatives like get_note. The purpose is implied by the name and listed fields, but the description does not provide situational recommendations or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full context for a project: README content + related notes (via wikilinks) + open tasks + linked decisions. The key tool for understanding what a project is about.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project path, name, or alias |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the content returned (README, notes, tasks, decisions) but does not mention behavioral traits like read-only status, performance, or any side effects. The description is partially transparent but lacks important behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus a summarizing second sentence. It front-loads the key information and contains no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (aggregating multiple data types) and the absence of an output schema, the description adequately explains what the tool returns. It could optionally include more detail about the output structure, but it is sufficient for understanding the tool's purpose.
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 parameter 'project', with a clear description in the schema. The description does not add additional meaning beyond what the schema provides, so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and the resource 'context for a project', and enumerates specific components: README content, related notes, open tasks, linked decisions. It distinguishes itself from sibling tools like get_note or list_projects by aggregating multiple aspects.
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 calls this 'the key tool for understanding what a project is about', which conveys when to use it. However, it does not provide explicit guidance on when not to use it or mention alternative tools for more specific queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check vault accessibility and return statistics: note counts by type/status, active projects, areas, decisions
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly identifies the tool as a read-only check ('check vault accessibility') and describes the output. While it could mention performance or error handling, for a simple health check this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the tool's purpose and output. Every word 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?
Given no output schema, the description adequately explains the return values. It could mention handling of an inaccessible vault, but the core information is provided. The tool is simple and the description is complete enough for an agent.
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?
There are no parameters, so the description adds meaning beyond the empty schema by specifying the return statistics. Baseline 4 applies as the zero-parameter case.
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 checks vault accessibility and returns specific statistics (note counts by type/status, active projects, areas, decisions). It uses a specific verb-resource pair and distinguishes from sibling tools that perform CRUD operations on notes or projects.
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 checking vault health and state but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion criteria. Given the sibling tools are content-focused, the context is clear but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notes with metadata for browsing UI: path, title, frontmatter, mtime, size, hash. Supports folder/type/status/tag filters and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Filter by tags (OR logic) | |
| type | No | Filter by note type | |
| limit | No | Max results (default 50) | |
| folder | No | Folder scope, e.g. "01_Projects" | |
| offset | No | Pagination offset (default 0) | |
| status | No | Filter by note status | |
| sort_by | No | Sort field | |
| include_archived | No | Include 04_Archives notes (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool lists metadata and supports filters/pagination, but does not explain default sort order, pagination metadata (e.g., total count), or any side effects. Adequate but could be more detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and contains no unnecessary words. Every sentence adds value, making it highly concise and well-structured.
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 lists the metadata fields returned, which is essential since no output schema exists. It covers filters and pagination. However, it does not mention pagination metadata (e.g., total count, next page token) or default behavior, leaving minor gaps.
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 description mentions 'folder/type/status/tag filters and pagination' which summarizes parameters, but since the input schema already provides descriptions for all parameters (100% coverage), the description adds no new meaning beyond repetition. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'notes', specifies the metadata fields returned (path, title, frontmatter, mtime, size, hash), and mentions supported filters and pagination, distinguishing it from sibling tools like get_note or create_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for browsing UI' provides clear context for when to use this tool. It implies it is for listing multiple notes, not for retrieving a single note (which is get_note), but does not explicitly exclude other use cases or specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects with status, deadline, and tags. Optionally filter by status (active/paused/done/someday).
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by project status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits like read-only nature, auth requirements, or rate limits. For a safe read operation, this is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the main action, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description hints at return fields (status, deadline, tags). Sufficient for a simple list tool, but could mention pagination or ordering.
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%, and description repeats the parameter info. No additional semantics beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List all projects' and specifies the fields included (status, deadline, tags). Distinguishes from sibling tools which focus on notes and memory.
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?
Mentions optional filtering by status, but does not explicitly advise when to use this tool versus alternatives. No alternative project tools exist among siblings, so it's acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepare a note update without writing. Returns old/new hashes and a line diff for user confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative .md path inside the vault | |
| new_content | Yes | New markdown body without YAML frontmatter | |
| expected_hash | No | Optional optimistic-lock hash from get_note_metadata/list_notes | |
| update_reason | No | Why this update is proposed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It correctly states the tool is non-destructive (doesn't write) and describes the output (hashes and diff). However, it doesn't mention optimistic locking or error cases, which are partially covered by the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveying all essential information. No filler words; every word 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?
For a simple preview tool, the description covers the purpose, behavior, and return values. It could mention integration with 'apply_note_update' and prerequisites, but overall it is sufficient given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra detail about parameters beyond the schema's own descriptions, which are already adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Prepare' and explicitly states the tool does not write, clearly distinguishing it from sibling 'apply_note_update'. It also mentions the return values (hashes, diff), making the tool's function 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 implies usage for previewing changes before committing, contrasting with 'without writing'. It does not explicitly name alternatives or specify when not to use, but the purpose is clear enough from the sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read agent memory files from 00_Meta/AI-System.
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Memory files to read; defaults to all files |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states the operation without disclosing any behavioral traits (e.g., idempotency, error handling, file existence assumptions), which is insufficient for a mutation-free but potentially critical 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?
Single sentence front-loading the purpose, no wasted words; efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description is adequate but lacks detail on return format or possible errors, which would help the agent plan the 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 100% with the 'files' parameter described as 'Memory files to read; defaults to all files'. The description adds no additional meaning beyond the schema, 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 verb 'Read' and the resource 'agent memory files' with specific path '00_Meta/AI-System', distinguishing it from sibling tools like add_agent_memory (write) and other read tools (read_notes_batch).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no exclusions or prerequisites mentioned, leaving the agent to infer usage solely from the name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read multiple notes in one call for context building. Returns missing paths separately.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | Note paths, names, or aliases | |
| include_content | No | Include markdown body (default true) | |
| max_chars_per_note | No | Optional content truncation per note | |
| include_frontmatter | No | Include parsed frontmatter (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds the behavioral detail 'Returns missing paths separately,' which is useful. However, it does not disclose other traits like read-only nature, authentication needs, or rate limits, which would enhance 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 extremely concise, consisting of two sentences with no extraneous information. It front-loads the purpose and includes a key behavioral promise (missing paths). Every word 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?
For a tool with four parameters, no output schema, and no annotations, the description adequately states the core functionality but lacks details on the response structure (e.g., format of returned notes and missing paths). This leaves the agent partially uninformed about the output.
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?
With 100% schema description coverage, the baseline is 3. The description does not add additional semantic meaning beyond what the schema already provides for the four parameters. The usage hint 'for context building' is contextual, not parameter-specific.
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 'Read multiple notes in one call for context building,' which clearly indicates the tool's purpose as a batch read operation for gathering context. It distinguishes from single-note tools like get_note, but does not explicitly differentiate 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 when multiple notes are needed for context building, but lacks explicit guidance on when not to use this tool versus alternatives (e.g., get_note for single note, list_notes for listing). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranked lexical search across vault: title/name/aliases/tags/related/content matching. Filter by type, status, tags. Returns score, matches, and snippets.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Filter by tags (OR logic — matches any) | |
| type | No | Filter by note type | |
| limit | No | Max results (default 20) | |
| query | Yes | Search query — matches name, aliases, tags, and content | |
| status | No | Filter by note status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it returns score, matches, and snippets, which gives some behavioral insight, but lacks details on auth, rate limits, or exact search behavior (e.g., case sensitivity).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence covering key aspects without redundancy. It could be split for readability but is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 params, no output schema), the description adequately covers functionality and output structure (score, matches, snippets). However, it could elaborate on ordering or pagination.
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?
All parameters have descriptions in the schema (100% coverage), so the description adds minimal extra meaning beyond context. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a ranked lexical search across vault fields (title, name, etc.), with filtering capabilities. This distinguishes it from sibling tools like list_notes (list all) or find_related (related notes).
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 search with filters, but does not provide explicit when-to-use or when-not-to-use guidance, nor mentions alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate whether a relative vault path is safe for read or write. Rejects traversal and excluded folders such as 99_Private.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path inside the Obsidian vault | |
| operation | Yes | Operation to validate |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It mentions rejection of traversal and excluded folders, which is useful, but fails to disclose return values, error handling, or authorization requirements.
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 key constraints. Every sentence adds essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple validation tool with two parameters and no output schema, the description adequately covers purpose and constraints. It could specify the return type (boolean or error) for full completeness.
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% as both parameters are described. The description adds value by clarifying that the path is relative and that the operation restricts to read/write, plus the safety validation intent, slightly exceeding the schema baseline.
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 validates a vault path for read/write safety, including rejecting traversal and excluded folders like 99_Private. This specific action distinguishes it from sibling tools that perform direct file operations.
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 use before read/write operations but does not explicitly state when not to use it or mention alternatives. It could benefit from clearer guidance on pre-validation context.
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.
v0.3.0add_agent_memoryappend_to_noteapply_note_updatecreate_noteextract_decisionsextract_tasksfind_relatedget_noteget_note_metadataget_project_contexthealthchecklist_noteslist_projectspropose_note_updateread_agent_memoryread_notes_batchsearch_knowledgevalidate_vault_pathScored across 18 tools
Each tool has a clearly distinct purpose: note CRUD separated from search, tasks, decisions, project context, and memory read/add. No overlapping functions.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_notes, create_note, search_knowledge). Only healthcheck is a single word but still clear.
18 tools cover the breadth of a second brain system: notes, tasks, decisions, projects, memory, search, and validation. The count feels complete without bloat.
Core CRUD operations are present with safety mechanisms. Missing explicit delete/move tools, but the design prioritizes safety and append-only patterns. Minor gaps but overall solid.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Read-only search of your Sortio knowledge graph (files and entities) for Claude and ChatGPT.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
