[Feature] MCP tool schema descriptions too verbose — add compact mode to reduce context token overhead

[lg320531124]

Problem

OpenViking's MCP server exposes 15 tools (find, search, read, list, remember, add_resource, grep, glob, code_outline, code_search, code_expand, forget, health, list_watches, cancel_watch). Each tool's description docstring is passed verbatim as the MCP tool schema.

When Claude Code (or any MCP client) calls tools/list, it receives all 15 tool schemas at once. The combined description text consumes significant context tokens — each tool's docstring ranges from 1-5 lines, and some include usage examples and caveats.

Token Overhead Estimate

15 tools × ~50-100 chars average description = 750-1500 chars just in descriptions, before counting inputSchema fields. This is roughly 200-400 tokens of context per conversation turn, permanently consumed.

Real-World Impact

I built a separate stdio proxy (mcp-schema-diet) that intercepts MCP tools/list responses and compresses descriptions. It achieves 33-60% character reduction on OpenViking tool schemas depending on compression level:

Tool	Full description chars	Compressed chars	Savings
find	~80	~45	44%
search	~90	~50	44%
list_watches	~150	~60	60%
cancel_watch	~120	~55	54%

The fact that a separate proxy is needed to compress schemas suggests this should be a built-in feature.

Suggested Fix

Add a description_mode parameter to the MCP endpoint:

# Environment variable: OPENVIKING_MCP_DESCRIPTION_MODE
# Values: "full" (default) | "compact"

# In mcp_endpoint.py, each @mcp.tool() description:
# - "full": current behavior — full docstring
# - "compact": only the first sentence of the docstring

# Example:
# Full:    "List watch tasks (auto-refresh subscriptions) visible to the current user.\n\nEach line shows: target URI, refresh interval (minutes), active/paused status,\nand the next scheduled execution time. Returns \"No watch tasks.\" when empty."
# Compact: "List watch tasks (auto-refresh subscriptions) visible to the current user."

Implementation approach:

1. Add OPENVIKING_MCP_DESCRIPTION_MODE env var support in mcp_endpoint.py
2. When compact, truncate each tool's description to the first sentence (text before the first . or \n\n)
3. Default remains "full" — no behavior change for existing users

This is similar to how caveman's caveman-shrink MCP proxy compresses tool descriptions, but built into OpenViking itself.

Alternative

If per-tool description truncation is too aggressive, an alternative is to make the first sentence more informative so it can serve as a standalone compact description, then keep the full docstring for "full" mode.

Environment

• OpenViking v0.4.5 (latest)
• Claude Code with OpenViking MCP server
• macOS