Optimized tool descriptions in both server.js and deno-server.js to explicitly guide AI agents toward minimal token usage.
1. execute_command Tool
Before:
"Execute a shell command inside the container and return output."
After:
"Run commands with minimal output. Use sparingly and inspect only what is needed. Prefer precise paths, targeted filters (grep, grep -m, sed -n), and bounded output (head, tail, find with limits). Combine related checks concisely. Never dump entire large files, directories, logs, dependency trees, or recursive listings unless explicitly necessary. Avoid verbose flags and redundant output."
Impact: Strongly encourages AI to:
Use the tool sparingly
Request bounded output at the source
Avoid large dumps (files, directories, recursive listings)
Combine related checks
Use targeted filters (grep -m, sed -n, head, tail, find with limits)
2. read_file Tool
Before:
"Read an inclusive line range from a UTF-8 text file.
Line numbers are 1-based. If end_line is omitted, read through EOF."
After:
"Read only the smallest useful line range. Lines are 1-based. Prefer bounded start_line/end_line ranges and avoid reading to EOF for large files unless necessary. If the relevant location is unknown, locate it first with a targeted search, then read only the surrounding lines."
Impact: Strongly encourages AI to:
Read minimal line ranges
Use explicit start_line and end_line
Avoid reading to EOF for large files
Locate sections first with targeted searches, then read only relevant lines
3. write_file Tool
No changes - This tool is for output, not inspection, so token optimization guidance is not applicable.
Implementation Details
Server-Side Response Format
Preserved the existing compact behavior: return result.result ?? ""
No verbose metadata, command echoes, status labels, or wrappers added
Clean direct output only
No Automatic Truncation
Did NOT add server-side output truncation
Rationale: Blind truncation can silently remove important information
Instead, the descriptions guide AI to request bounded output at the command level
Files Modified
server.js (Node.js implementation)
deno-server.js (Deno/Val Town implementation)
Verification
✅ Syntax validated with Node.js
✅ Tool names unchanged
✅ Input schemas unchanged
✅ MCP protocol compatibility preserved
✅ Stateless HTTP behavior unchanged
Expected Behavior
AI agents using this MCP server should now:
Request fewer, more targeted inspections
Use command-line tools to limit output (head, tail, grep -m, etc.)
Read specific line ranges instead of entire files
Locate relevant sections before reading
Avoid expensive operations like recursive listings and dependency tree dumps
Token Savings Estimate
Conservative estimate for typical AI agent sessions: