Loading ToolBench
MCP server for managing a markdown-based knowledge vault with file operations, search, link querying, and path management
SecondBrainMCP demonstrates strong naming conventions, comprehensive parameter schemas, and detailed descriptions across all 8 tools. All tools follow verb_noun patterns (create_file, read_file, update_file, delete_file, list_files, search_vault, query_links, move_path). Parameter descriptions are detailed and include constraints. However, there are critical gaps: (1) Output schemas are referenced as present in test code but NOT visible in the tool definitions provided, (2) Error handling descriptions are generic and do not guide recovery, (3) Some parameter relationships and dependencies are underdocumented. The tools are well-composed for a vault management system with proper resource IDs (path, format, revision) and idempotent patterns (expected_revision prevents lost updates). Tool descriptions average ~400 characters (above baseline 194), providing good context. Most parameters have clear types and descriptions, meeting the 10-1024 character guideline.
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 git-removed. Expected revision prevents accidental deletion of modified files. Returns the trash path and deleted revision for manual recovery verification.
List files in a vault area with optional limit and continuation. Results are sorted and include path, format, and optional metadata fields. Supports pagination via cursor.
Atomically move or rename a file or directory within the vault. For files, expected_revision prevents moving modified files. For directories, no revision is required. Returns source and destination paths on success.
Query the knowledge graph for incoming and outgoing links. Supports backlinks and forward links with optional grouping and filtering. Returns resolved paths, formats, and occurrence counts.
Output schemas not visible in tool definitions; test code validates against schemas but definitions do not show outputSchema field. This violates the pattern:tool requirement that tools document return types. Score cannot be raised without seeing explicit output schema declarations.
Error handling descriptions are absent or generic. Tools do not document what errors are possible, how to recover, or whether errors are retryable. Test code shows ERROR_SCHEMA validation, but tool descriptions do not explain failure modes or recovery guidance. Violates pattern:recovery-guide and pattern:error-classification.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 65 | 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 the vault by full-text query or regex pattern. Returns results from notes/ and references/ with path, format, and optional preview. Search scans all supported file types and returns ranked results.
Update a concrete file with replace, append, or patch mode. Expected revision prevents lost updates; update fails if the file has changed. Patch mode applies exact text substitutions; replace mode overwrites the entire file; append mode adds content to the end. All modes validate format consistency before writing.
Parameter 'transform' in create_file has enum:[] (empty), making it unusable. Either populate the enum with valid transformation types or remove the parameter entirely. Current definition is incomplete and will cause schema validation to fail.
Parameter dependencies are underdocumented. For example, read_file's canvas_node_id and canvas_field are mutually required, but this constraint is only stated in the description text, not enforced or prominently highlighted. Similarly, update_file's 'replacements' array is only valid in patch mode, but this relationship is not explicitly documented in the replacements description.
Dry-run or confirmation pattern missing for destructive operations. delete_file and update_file (replace mode) are irreversible, but no confirmation step or dry-run variant is offered. Violates pattern:confirmation-request.
Pagination documentation is incomplete. list_files and search_vault support cursor-based pagination, but descriptions do not explain when to use cursor, what 'end of results' looks like, or whether cursor is stable across calls. query_links also supports cursor but does not document result ordering or when additional pages exist.