Loading ToolBench
MCP server for managing a markdown-based note vault with file operations, search, and link querying capabilities
Second Brain MCP demonstrates strong definition quality with comprehensive schemas, detailed descriptions, and clear parameter documentation. All 8 tools have explicit input and output schemas validated against JSON Schema Draft 2020-12. Descriptions are substantive (100-400+ chars), explaining WHAT the tool does, WHEN to use it, and key constraints. Parameters are well-typed with enums, bounds, and clear semantics. Tool names follow verb_noun convention (create_file, read_file, etc.). Error handling is present with actionable recovery guidance. Main gaps: descriptions could be more LLM-optimized (some exceed 400 chars and bury key details); no explicit output schema examples in source; some parameter relationships (e.g., canvas_node_id + canvas_field mutual dependency) documented but could be clearer.
Create a supported concrete file under notes/. Creation is atomic and requires the destination to be absent. The format field describes whether each registered type accepts content or source and whether it requires a transform. The declared format, destination extension, and actual content must agree. Specialized handlers validate or transform input before the shared persistence, revision, and Git pipeline.
Soft-delete a concrete file. The file is moved to .trash and removed from Git tracking. Requires the exact-byte revision from a preceding read to prevent accidental deletion.
List files in a vault area with pagination. Returns file paths, formats, and modification times.
Atomically move a file or directory within the vault. For files, requires the exact-byte revision from a preceding read. For directories, no revision is required.
Query the vault link graph. Supports outgoing links from a file and backlinks to a file. Results can be grouped by occurrence and filtered by source path.
read_file description is verbose (400+ chars) and buries key details about view modes, pagination, and Canvas handling. LLM may miss critical constraints like 'metadata view returns no content' or 'canvas_node_id and canvas_field must be repeated for continuation.'
Parameter relationships not enforced in schema: read_file's canvas_node_id and canvas_field are mutually dependent (both required together, both must be repeated), but schema does not use 'dependentRequired' or 'allOf' to express this. LLM may pass one without the other.
update_file 'replacements' parameter accepts up to 1000 items but no guidance on atomicity or partial failure. If one replacement fails, does the entire update fail or does it apply successful replacements? Error handling should clarify.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 68 | 2025-06-18+ | v2 |
Read one known file after list_files, search_vault, or query_links. Use view=metadata for content-free Markdown title/tags/word count/links or bounded PDF title/author/page labels/outline; do not combine metadata with content selectors. The default content view returns bounded UTF-8 chunks, log lines, image inspection facts, or physical PDF pages. Image formats return visual payloads only with render=true; GIF rendering returns at most 8 sampled frames. For a Canvas result from search_vault, pass both canvas_node_id and canvas_field to read only that decoded field instead of paging through the raw JSON; repeat both selectors on every continuation. Continue text with text_window.next_byte_offset and the same revision as expected_revision. Reads under notes/ return the exact revision required before update_file, delete_file, or file-form move_path.
Search vault content by full-text query or metadata. Returns matching files with format, location, and optional Canvas node details.
Update a concrete file with replace, append, or patch mode. Replace and append modes accept content; patch mode accepts exact text substitutions. All updates require the exact-byte revision from a preceding read to prevent lost updates.
No explicit output schema examples or documentation in source code. While schemas are validated, LLM cannot see what fields are returned (e.g., does read_file return 'text_window' or 'window'? Does search_vault return 'canvas_node_id'?). Output structure must be documented.
Tool descriptions do not explicitly state which operations are idempotent vs. non-idempotent. Agents need to know: can I safely retry create_file if it times out? (No, it will fail if file exists.) Can I retry read_file? (Yes.) This must be explicit.