This server has 5 tools with explicit schemas and descriptions visible in src/server.py. However, most descriptions are in Chinese and lack actionable guidance for LLM tool selection. Parameter descriptions are minimal (1-5 words each). Output schemas are not documented, LLMs cannot predict response structure. Error handling returns JSON strings but lacks recovery guidance. Tools are moderately well-named but descriptions do not explain WHEN to use each tool or its prerequisites. The average tool score is 42/100, reflecting incomplete definitions across the board.
Output schemas not documented. Tools return JSON responses but LLMs cannot predict field names, types, or structure. Response contains 'success', 'path', 'encoding', 'confidence', 'content', 'warnings', 'replacements', none of this is specified in tool definitions.
Descriptions are minimal and non-actionable for LLM selection. 'Read file (auto-detect encoding, return UTF-8 content)' does not explain WHEN to use this tool vs write_file, or what prerequisites exist. Descriptions are also in Chinese, reducing discoverability for non-Chinese-speaking agents.
Document output schemas for all tools. Add an 'outputSchema' field to each Tool definition specifying response structure: { type: 'object', properties: { success: { type: 'boolean' }, path: { type: 'string' }, encoding: { type: 'string' }, confidence: { type: 'number' }, content: { type: 'string' }, warnings: { type: 'array' } }, required: [...] }
Rewrite all descriptions in English and expand to 100-200 characters with WHEN/WHY guidance. Example: 'Read a file and detect its encoding (supports GBK, GB18030, UTF-8). Returns content as UTF-8. Call this FIRST before write_file_with_encoding to auto-detect the original encoding, then write_file will preserve it.'
Add format constraints and enums to parameter descriptions. For 'encoding', document supported values: 'Encoding name (GBK, GB18030, UTF-8, ASCII, etc.) to write file in. If not specified, uses the detected encoding from last read_file_with_encoding call. Supported encodings: GBK, GB18030, UTF-8, ASCII, LATIN-1.'
Enhance error messages with recovery guidance. Example: Instead of 'File not found: /path/file', return 'File not found at /path/file. Verify the path exists or call list_all_encodings to see cached files.'
Add enum constraints to 'encoding' parameter in write_file_with_encoding and edit_file_with_encoding. Extract supported encodings from is_encoding_supported() and embed in inputSchema: { 'encoding': { 'type': 'string', 'enum': ['GBK', 'GB18030', 'UTF-8', ...], 'description': 'Target encoding...' } }
Consider splitting edit_file_with_encoding into two tools if dry-run verification is needed: (1) preview_file_edit (returns the modified content without writing) and (2) apply_file_edit (writes the change). This lets agents verify before committing.
Score history
Overall score trend
First recorded score · v2 rubric
44/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-23
F
44
2026-07-28+
v2
Parameter descriptions are extremely brief (1-5 words). 'File path', 'file content', 'target encoding' lack format guidance, constraints, or context. Descriptions do not explain character limits, encoding names (which encodings are supported?), or whether paths must be absolute.
Error responses lack recovery guidance. Errors return JSON with 'success': false and 'error' text (Chinese), but do not guide the LLM toward next steps. E.g. 'File not found' should suggest 'Check the path or use list_all_encodings to discover available files.'
No validation constraints visible in schemas. 'encoding' parameter accepts a free-form string with no enum or pattern. The code checks is_encoding_supported(), but LLMs cannot see which encodings are valid and will hallucinate values like 'UNKNOWN_ENCODING'.
edit_file_with_encoding tool combines two concerns: string replacement (old_string → new_string) AND encoding management. If replacement fails, LLMs cannot isolate whether the issue is the replacement logic or encoding. Consider splitting into separate tools or adding a dry-run parameter.
write_file_with_encoding and edit_file_with_encoding both modify files. Naming convention suggests write → full overwrite, edit → partial replacement, but descriptions should explicitly state this distinction to prevent LLM confusion or misuse.
list_all_encodings returns all cached encodings with no pagination or limits. If thousands of files have been processed, the response could blow the context window. No indication of size or result set management.
Tool descriptions in Chinese ('读取文件' instead of English). International multi-lingual agents may not handle non-ASCII descriptions correctly, and the majority of LLM training data is in English. Descriptions should be in English for maximum compatibility.
Add pagination to list_all_encodings: include 'limit' (default 50) and 'offset' (default 0) parameters. Response should include 'total_count' and 'returned_count' to help agents iterate through large result sets.
Add a dry-run or preview mode to write_file_with_encoding. Before overwriting, return the detected current encoding and a confirmation prompt: 'File currently encoded in GBK. Write as UTF-8? (set confirm=true to proceed)' This prevents accidental encoding mismatches.
Document which encodings are supported in the tool description, not just in code. LLMs cannot introspect Python functions. Example: 'Supports GBK, GB18030, UTF-8, ASCII, LATIN-1, and 20+ other encodings via charset-normalizer.'
Add explicit per-tool permission/security notes. E.g. 'read_file_with_encoding: READ_ONLY, can read any file on disk the server has permission to access. Consider restricting to a sandboxed directory.' This helps security reviewers assess blast radius.