second-brain-mcp

Overview Schema Source Related Servers Discussions Admin

expand_semantic_keywords_tool

Extract and write semantic keywords into note frontmatter using local LLMs, then rebuild the full-text search index. Batch-process notes missing keywords or force-refresh existing ones.

Instructions

Batch-extract or refresh semantic_keywords for notes via llm_cli (local Gemma4 → Claude CLI → Gemini CLI, in that priority order — see llm_cli.py's module docstring).

Writes extracted keywords into each note's frontmatter and rebuilds FTS index. Skips notes that already have semantic_keywords unless force=True.

Args: note_path: Specific vault-relative path to process (e.g. 'decisions/my-note.md'). Leave empty to process all indexed notes missing keywords. force: If True, overwrite existing semantic_keywords (default False).

Returns: Summary dict: {"processed": N, "skipped": M, "failed": K}

Input Schema

TableJSON Schema

Name	Required	Description	Default
`force`	No
`note_path`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 13, 2026

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and largely succeeds: it discloses that keywords are written into frontmatter, that the FTS index is rebuilt (a real side effect), that existing keywords are skipped unless force=True, and the LLM backend fallback order. It omits auth/permission requirements and cost/latency implications of invoking LLM CLI backends.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

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

Purpose is front-loaded, then structured Args/Returns sections. Every line is informative, though the parenthetical backend-priority detail and pointer to llm_cli.py's docstring are marginally more than an agent needs for invocation.

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

Completeness4/5

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

For a two-parameter batch tool with no annotations, the description covers side effects, skip/force semantics, and output shape (redundantly, since an output schema exists). It is nearly complete, missing only permission/auth context that an agent might need before running it.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate, and it fully does: note_path is given semantics, an example format, and the empty-string behavior; force is given its exact effect and default. Nothing about either parameter is left undocumented.

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

Purpose4/5

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

States a specific verb+resource: 'Batch-extract or refresh semantic_keywords for notes.' An agent can immediately tell this operates on note frontmatter keywords at batch scale. However, it never differentiates itself from the existing sibling enrich_neighbor_keywords_tool, leaving the sibling boundary to inference.

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

Usage Guidelines3/5

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

Usage is only implied through parameter behavior ('Leave empty to process all indexed notes missing keywords'), which hints at when the no-arg mode applies. There is no explicit guidance on when to choose this over enrich_neighbor_keywords_tool or extract_rules_tool, and no stated prerequisites or exclusions.

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