Token-efficient skim-then-expand I/O for agentic models (Claude Code / desktop Claude) via MCP
skim-mcp demonstrates solid tool design with clear, action-oriented naming (skim_open, skim_expand, skim_search, skim_run, skim_repo, skim_patch) and comprehensive descriptions (avg ~180 chars, well within 10-1024 range). All tools have input schemas with typed parameters and descriptions. However, output schemas are not explicitly documented in the source code, the server returns structured results but the LLM-facing schema definitions are inferred rather than formally declared. Error handling is present but minimal; no recovery guidance or categorization. Parameter descriptions are good but lack explicit constraints (e.g., no min/max for command length, no enum for skim_run output format). Security is strong (no secrets in params, read-only/write risk labels present), and composition is excellent (each tool has one clear responsibility, chaining is natural via handles).
Expand one or more collapsed spans by anchor id, returning exact verbatim text from the file.
Open a large file and return a compact skeleton + expandable anchor ids (not the full text). Returns handle, report (token counts + compression ratio), skeleton (read this), and anchors (ids you can expand). Use instead of reading a whole large file when you only need parts. Collapsed bodies are NOT in the skeleton - expand the anchor when the answer needs the body. Pass `query` to also get `matches` (which lines/anchors contain it) in the same call, saving a skim_search round-trip when you already know what you're looking for.
Replace exactly one expanded span on disk - because expands are verbatim, the edit is drift-safe: it is refused if the file changed since skim_open.
Map a WHOLE repo/directory: ranked file skeletons within a token budget, each expandable to exact code - use it to understand a codebase before diving in.
Run a shell command and return a compact, expandable view of its output - use it for verbose commands instead of dumping the full output.
Output schemas not formally documented. Tool results are structured (SkimResult, token counts, anchors) but the LLM-facing response schema is not declared in tool definitions. LLMs cannot plan downstream calls without knowing what fields to expect.
No error recovery guidance. Tools return errors (e.g., 'unknown handle', 'file not found') but do not tell the LLM what to do next. Missing pattern: 'If handle is unknown, call skim_open() again.'
Parameter constraints not explicit. skim_run accepts any shell command with no length limit or timeout guidance. skim_repo accepts any path with no token budget explanation. Descriptions lack min/max, regex patterns, or format constraints.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 61 | 2026-07-28+ | v2 |
Search for a query string within a file and return which anchors contain matches.
skim_run is a write tool but lacks confirmation/dry-run pattern. Agents can execute arbitrary shell commands without a safety gate. No mention of command validation or sandboxing.
No pagination or result limits documented for skim_repo. Large repos could return unbounded results, exhausting context. No mention of token budget enforcement or how results are ranked/truncated.