mcp: tool descriptions cause inefficient agent usage — agents read full files and exceed token limits

[justrach]

Problem

Agents using codedb MCP tools produce wasteful query patterns that result in multi-megabyte responses exceeding token limits. This was reported in #160 where Claude Opus 4.6 generated 3.2M character bundle responses.

Root Cause

The MCP tool descriptions do not guide agents toward efficient usage patterns. Specifically:

1. codedb_read description says "Read file contents" — agents use it to read entire files instead of using codedb_outline first
2. codedb_bundle description says "max 20 ops" but does not warn about response size — agents bundle 6+ codedb_read calls producing megabytes of output
3. codedb_search with max_results=30 on broad queries returns hundreds of KB
4. No description tells agents: "use outline first, then symbol or read with line ranges"

Failing Test

test "issue-160: bundle with multiple full reads should warn about size" {
    // A bundle of 6 codedb_read calls on large files should either:
    // 1. Truncate output to a reasonable size, or
    // 2. Return an error suggesting outline + targeted reads
}

Proposed Fix

1. Improve tool descriptions in src/mcp.zig tools_list:

   • codedb_read: Add "Use codedb_outline first to understand file structure, then read specific line ranges. Avoid reading entire large files."
   • codedb_bundle: Add "Warning: total response is capped at 100KB. Use outline + targeted reads, not full file reads."
   • codedb_search: Add "For broad queries, start with max_results=10. Use scope=true for context."
   • codedb_outline: Add "START HERE — use this first to understand any file before reading it."

2. Add response size cap to bundle — if total response exceeds 100KB, truncate and return a warning

3. Add codedb_read size warning — if reading a file >50KB without line range, suggest using outline instead

Environment

• codedb v0.2.53
• Claude Code Opus 4.6, max effort

Related

• Closes Extremely inefficient tool usage #160

[justrach]

Fixed in PR #159 — improved MCP tool descriptions to guide agents toward efficient usage (outline first, targeted reads, small max_results). Added 200KB response cap to codedb_bundle to prevent multi-megabyte responses that exceed token limits.