markdown-vault-mcp

Build Embeddings

build_embeddings

Idempotent

Update the vector index behind semantic and hybrid search to match vault notes, embedding only changed chunks or rebuilding all when forced; returns the number of chunks embedded.

Instructions

Bring the vector index behind semantic and hybrid search up to date with the notes; returns the number of chunks embedded.

Embeddings are built automatically, so it is needed only after reindex with force, after a failed build (last_build_embeddings_error in get_index_status), or with force to rebuild them all.

Input Schema

Name	Required	Description	Default
`force`	No	Re-embed every chunk, as after the embedding model changed; the current embeddings keep serving until the rebuild completes. Default false embeds only what changed.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv6.1.0Nov 2, 2026

changedInput schema / properties / force / description

Previous value: -"When True, discards existing embeddings and rebuilds from\nscratch. Use only if the embedding model has changed.\nWhen False (default), converges the vector index to the\nFTS chunk set — work scales with the size of the drift,\nnot the size of the vault (#665)."New value: +"Re-embed every chunk, as after the embedding model changed; the\ncurrent embeddings keep serving until the rebuild completes.\nDefault false embeds only what changed."

First observedv3.1.0Jul 8, 2026

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the write scope is structured. The description adds genuinely new operational context: the build is normally automatic, failures are diagnosable through last_build_embeddings_error, and force is the escalation path. It stops short of stating cost/duration or whether concurrent runs are safe for what is a heavy 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs: what it does and returns first, then exactly when it is warranted. No restatement of the name or title, and every clause carries decision-relevant information (automatic default, error hook, force path).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-optional-boolean tool with full schema coverage, complete annotations and an output schema, nothing an agent needs is missing. The definition covers scope, triggers, failure recovery and the interaction with reindex, which is the only real ambiguity in this cluster.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the force parameter already documents its own default and non-destructive swap behavior, so the baseline is 3. The description earns an extra point by tying force to concrete scenarios (a prior forced reindex, or a changed embedding model) that the schema does not name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb and resource: "Bring the vector index behind semantic and hybrid search up to date with the notes," plus the return value (chunks embedded). It implicitly distinguishes itself from reindex, embeddings_status and get_index_status by framing itself as the incremental catch-up step rather than a status query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the default of not needing it ("Embeddings are built automatically") and enumerates the three conditions that do select it: after reindex with force, after a failed build indicated by last_build_embeddings_error in get_index_status, or with force for a full rebuild. Both when-to-use and when-not are covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.