This filesystem MCP server has 18 tools with good naming conventions and basic schema documentation. Most tools start with action verbs (ls, cd, read_file, write_file, mkdir, rm, cp, mv, grep, ruff_check, ruff_format, shell_command), following the verb_noun or verb pattern established in production tools. All tools have descriptions present. However, there are significant gaps: (1) many parameter descriptions are minimal (10-30 chars), below the 72-char baseline for production tools; (2) no explicit output schema documentation visible in the code, return types are inferred from type hints but not formally described for LLM consumption; (3) no error handling guidance in descriptions, e.g., 'ls' does not explain what happens if the path does not exist; (4) no input validation constraints documented (e.g., read_file should warn about file size limits); (5) no tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels assigned; (6) shell_command is extremely permissive with no execution constraints or safety notes. Per-tool analysis shows naming quality at ~80 (clear action verbs), description quality at ~50 (present but sparse), and schema quality at ~55 (basic types visible in code but not formally documented for the LLM).

• Expand all parameter descriptions to 60-150 chars, following the 72-char baseline. Example for 'rm': 'Remove a file or empty directory. If the path is a directory with contents, returns an error, use rmdir to remove non-empty directories recursively. Supports relative and absolute paths.'
• Add formal output schema documentation to tool descriptions. Example for 'read_files': 'Returns a dict mapping each input file path to its full contents as a UTF-8 string. Large files are returned in full; consider breaking very large files into chunks with separate read_file calls if context becomes a concern.'
• Implement tool annotations in the FastMCP registration. Add readOnlyHint=true to tools marked READ_ONLY (ls, read_file, read_files, grep, summary, summarize, work_on, ruff_check); destructiveHint=true to rm and rmdir; and idempotentHint=true to tools that can safely retry (read_file, ls, grep, summary, etc.).
• Add error recovery guidance to descriptions. Example for 'edit_file': 'If search text is not found, raises ValueError with the search text. Ensure the search string exactly matches the file content, including whitespace. Include context lines to avoid partial matches.'
• Restrict 'shell_command' severely: (1) add description noting security implications and limitations, (2) add 'allowed_commands' parameter or environment variable restriction list, (3) document that arbitrary command execution is restricted to non-destructive utilities, (4) add timeout enforcement with explicit 30-second default, (5) return stdout and stderr separately so the LLM can distinguish error messages.