Auditable context capsules, repo handoffs, streaming sessions, and capsule diffs for LLM agents and OpenCode MCP workflows.
Server provides 11 tools with generally clear naming and reasonable descriptions. All tools have documented input schemas with type constraints and enums. However, several critical gaps limit production readiness: (1) NO output schemas documented, LLMs cannot predict return structure or chain tools; (2) descriptions lack depth about WHEN to use tools vs similar ones and what constraints apply; (3) parameter descriptions are minimal, many lack actionable format/range guidance; (4) no error handling documentation; (5) streaming session tools introduce stateful server-side complexity without clear lifecycle guidance. Tool names follow verb_noun conventions well (compress_*, streaming_*, explain_*, etc.), and most use appropriate action verbs. Parameters include enums and defaults, but descriptions rarely explain the WHAT/WHEN/WHY reasoning an LLM needs for correct selection.
Batch-process multiple files into capsules. Each input file produces one output capsule.
Benchmark Context Diamond against head/tail clipping for one file.
Compress a UTF-8 text/markdown file into a context capsule. Supports templates, precise tokenizers, and loss reports.
Compress raw text into a Context Diamond capsule. Supports templates, precise tokenizers, and loss reports.
Explain shard-level facets, scores, tokens, and reasons for a text. Useful for debugging why certain content was selected.
List all active streaming session IDs.
Create a capsule from repository state and selected files. Captures branch, git state, and chosen files.
NO OUTPUT SCHEMAS DOCUMENTED. LLMs cannot predict return structure, field types, or which fields are available for chaining. This violates pattern:tool and pattern:response-shaper. Critical for tools like compress_* (what fields in capsule?), streaming_* (what does capsule look like?), and batch_compress (success/fail per item or bulk response?).
STREAMING TOOLS INTRODUCE STATEFUL SERVER-SIDE COMPLEXITY WITHOUT CLEAR LIFECYCLE. Global dict _STREAMING_SESSIONS creates memory leaks if sessions are not explicitly closed. No documented max session count, timeout policy, or garbage collection. Violates pattern:stateless-operation, MCP should handle stateless request/response pairs. If streaming is needed, document clear cleanup semantics and warnings about long-lived sessions.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 52 | 2026-07-28+ | v2 |
Add a message to a streaming compressor session. Creates a new session if session_id does not exist.
Get the current capsule markdown from a streaming session.
Close and remove a streaming session.
Clear all messages in a streaming session but keep the session active.
DESCRIPTIONS LACK WHEN/WHY GUIDANCE. Most descriptions say WHAT the tool does but not WHEN to use it vs alternatives. E.g., compress_text vs compress_file vs batch_compress, what's the user workflow? When is streaming_add preferred over compress_text? Descriptions should guide LLM selection per pattern:tool-description.
PARAMETER DESCRIPTIONS LACK ACTIONABLE CONSTRAINTS. E.g., 'budget' param appears in many tools but only says 'Token budget', no guidance on what token counts mean in context, typical ranges, or when to adjust. 'template' param references domain-specific templates but doesn't list available templates or describe what each does. Per pattern:tool-description, every param needs actionable format/range guidance.
STREAMING TOOLS LACK CLEAR STATE TRANSITIONS AND ERROR SCENARIOS. What happens if you call streaming_capsule on a non-existent session_id? Does streaming_add create a session automatically (yes, per description), but is there a race condition if two requests create the same session_id concurrently? What's the session ID format? How does the LLM know if a session is still valid? No error guidance.
BATCH_COMPRESS BEHAVIOR ON PARTIAL FAILURE IS UNDOCUMENTED. If 3 of 5 files are invalid, does the tool fail completely or return mixed results (3 capsules + 2 errors)? Per pattern:response-shaper and mxe:partial-failure, clarify whether batch operations are atomic and what per-item error reporting looks like.
EXPLAIN_TEXT FORMAT OUTPUTS ARE UNDER-DOCUMENTED. Enum choices are 'table' vs 'json' but descriptions don't explain what fields appear in each format, what 'shard-level facets' and 'scores' represent, or how to interpret the output. LLM cannot reason about whether to use table (human-readable?) or json (machine-parseable?).
MISSING ERROR HANDLING GUIDANCE. No tool descriptions mention what failures are possible (file not found, invalid path, tokenizer mismatch, quota exceeded, etc.) or how to recover. Per pattern:recovery-guide, error responses should guide next steps, but that depends on defining failure modes in descriptions first.
REPO_CAPSULE 'include' PARAMETER LACKS CLARITY. Type is array[string] but what do the strings represent? File paths? Glob patterns? Relative to repo root? Absolute? Description says 'Files to include before changed/untracked files' but doesn't explain the ordering logic or whether it accepts patterns.