SpiderFS Master Control Program - File system operations for MCP
SpiderFS has 5 tools with explicit schemas and basic descriptions, but significant gaps in parameter documentation and output schema clarity. All tools lack descriptions for individual parameters (e.g., 'path' and 'pattern' in search_content have no descriptions in the schema). Parameter descriptions are present in the input schema properties but are minimal (1-3 words). Output schemas are completely undocumented, callers cannot predict return structure. Error handling is absent; tools return raw strings without guidance on failure modes. Tool names follow verb_noun convention (search_, read_, write_, edit_) which is good, but descriptions are generic (10-30 chars, below the 50-200 char baseline for LLM optimization). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite write_file and edit_file being destructive operations.
Edit file lines
Fuzzy search for files and directories using fzf
Read file contents
Search file contents using ripgrep
Write file contents
Parameter descriptions missing or trivial. Schema properties define 'path', 'pattern', 'content' with no descriptions (e.g., 'path': {'type': 'string'} lacks explanation of what path format is expected, whether relative/absolute, or constraints). LLMs cannot infer parameter semantics from names alone.
Output schemas completely undocumented. Tools return strings (search_content, read_file, write_file, edit_file) or lists (fuzzy_file_search) with no schema definition. Callers cannot predict structure, field names, or error format. Violates pattern:response-shaper.
Destructive tools (write_file, edit_file) lack tool annotations. No readOnlyHint=false or destructiveHint=true to signal to LLMs that these operations modify state and may be irreversible. Missing idempotentHint guidance.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 40 | <=2025-11-25 | v2 |
Tool descriptions are generic and under 50 characters (baseline 50-200 chars for LLM optimization). 'Read file contents' (21 chars), 'Write file contents' (19 chars), 'Edit file lines' (14 chars) lack context on when to use each tool, prerequisites, or return format.
No error handling or recovery guidance. Tools return raw strings ('Success', error messages, or raw file content) without categorization (retryable vs fatal) or actionable next steps. LLMs cannot distinguish between a permission error and a file-not-found error.