Brings context compaction, history summarization, file re-hydration, and session persistence to GitHub Copilot in VS Code, enabling efficient long coding sessions without losing context.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@compaction-mcp Check context pressure and compact history if needed."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A portable MCP stdio server that brings Claude Code's /compact lifecycle to any
MCP host — GitHub Copilot (VS Code), Claude Desktop, or a custom local-LLM
agent loop (e.g. Qwen-Coder via Ollama).
It exposes context compaction as tools/resources/prompts so the agent can: gauge context
pressure, summarize accumulated history into a dense block (a real inference call, not
truncation), re-hydrate live files from disk, persist session-long rules and a
verification ledger across the compact_boundary, and run PreCompact/PostCompact
hooks.
See SPEC.md for the full protocol design and the host/server
responsibility split, ENTERPRISE.md for deploying under
GitHub Copilot Enterprise (org policy gates, MCP registry, in-tenant summarizer,
distribution), and runbooks/ for step-by-step operational guides for each
strategy (offload, recall, compact, re-seed, auto-compact, hooks/ledger).
/compactIn Claude Code, /compact is host-level — the CLI owns the context window. An MCP server
doesn't. So this server provides the mechanism (summarize, re-hydrate, persist,
snapshot ledger) and returns a compacted context block; the host installs that block
as its new ground truth and discards pre-boundary history. Read §1 of the spec first.
Related MCP server: SharedMemory MCP Server
npm install
npm run build # → dist/index.jsVar | Default | Purpose |
|
|
|
|
| OpenAI-compatible endpoint (Ollama) |
|
| summarizer model |
| — | optional bearer token |
| — | JSON of extra request headers (Azure |
|
|
|
|
| session + ledger persistence |
| cwd | colon-separated roots for file re-hydration |
| — | path to hooks JSON (see |
|
| set |
|
| default window size when host doesn't declare one |
|
| auto-compact on ingest when pressure ≥ |
|
|
|
| — | embeddings model for semantic recall (e.g. |
| = LLM base URL | OpenAI-compatible |
The server is manual by default — it only acts when a tool is called. context_status
tells you when to compact, but the host decides.
For deterministic auto behavior, use COMPACTION_MODE=store + COMPACTION_AUTO=true:
turn_add then checks pressure after each turn and, once it crosses the compact-now
threshold, runs compaction inline and returns the block under autoCompacted. Your agent
loop just installs autoCompacted whenever it's present. Passthrough mode stays manual
(the server doesn't hold continuous history).
direct works on every host (incl. Copilot) — the server calls the LLM itself.
Point it at Ollama for fully local operation.
sampling needs a sampling-capable host (Claude Desktop). Copilot does not
support sampling — don't use it there.
auto uses sampling if the client offers it, else falls back to direct.
.vscode/mcp.jsonCopilot is tools-only, so use passthrough mode + direct summarizer (Ollama):
{
"servers": {
"compaction": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/compaction-mcp/dist/index.js"],
"env": {
"COMPACTION_SUMMARIZER": "direct",
"COMPACTION_LLM_BASE_URL": "http://localhost:11434/v1",
"COMPACTION_LLM_MODEL": "qwen2.5-coder:14b",
"COMPACTION_MODE": "passthrough",
"COMPACTION_ALLOWED_ROOTS": "${workspaceFolder}"
}
}
}
}Then instruct Copilot (e.g. in .github/copilot-instructions.md): when the conversation
grows long, call context_compact with the recent history as transcript, then continue
from the returned summary + rehydratedFiles + persistentRules.
No Ollama? (Copilot-only) Copilot doesn't lend its model to MCP servers (no sampling),
so direct must point at some OpenAI-compatible endpoint. Easiest for a Copilot user is
GitHub Models (free, OpenAI-compatible) — see
examples/vscode-mcp.github-models.json. It
uses VS Code's inputs to prompt for a GitHub token (scope models: read) once and store
it encrypted. Any other OpenAI-compatible provider (OpenAI, OpenRouter, Groq, …) works the
same way — just change COMPACTION_LLM_BASE_URL / COMPACTION_LLM_MODEL.
claude_desktop_config.json{
"mcpServers": {
"compaction": {
"command": "node",
"args": ["/abs/path/compaction-mcp/dist/index.js"],
"env": { "COMPACTION_SUMMARIZER": "auto" }
}
}
}auto lets Claude Desktop run the summary via sampling (same model, no extra infra).
Point direct at your company's OpenAI-compatible gateway (LiteLLM, Portkey, Kong/Cloudflare
AI Gateway, or Azure OpenAI fronted by one) so code + transcripts stay in-tenant. Non-Bearer
auth goes in COMPACTION_LLM_HEADERS (e.g. Azure's {"api-key": "..."}). See
examples/vscode-mcp.enterprise-gateway.json.
Raw Azure OpenAI isn't drop-in (its URL is /openai/deployments/{d}/chat/completions?api-version=…),
so front it with a gateway rather than pointing the server at it directly.
On a Copilot Enterprise/Business plan there are also org-policy gates that block MCP
unless an admin opts in — see ENTERPRISE.md for the full deployment guide.
Use COMPACTION_MODE=store: feed each message through turn_add, poll context_status,
and call context_compact (no transcript arg) when it returns compact-soon/compact-now.
context_status, context_compact, context_trim, context_clear, turn_add,
handoff_brief, read_offloaded, offload_store, offload_fetch, recall, files_track,
files_untrack, files_rehydrate, rules_set, rules_append, rules_get,
ledger_record, ledger_query, ledger_snapshot.
Resources: compaction://session/{id}, compaction://rules/{id},
compaction://ledger/{id}, compaction://summary/{id}/{boundaryId},
compaction://handoff/{id}, compaction://blob/{handle}.
Re-seed recovers after the window is big; offloading keeps it small in the first place.
Instead of dumping a full file or command output into chat, read_offloaded / offload_store
stash it and return a short digest + handle; the agent pulls the full body (or a line
slice) via offload_fetch only when needed. On Copilot this only helps if the agent uses
read_offloaded instead of the native file-read tool. See SPEC.md §10B.
On hosts with their own retrieval (e.g. Augment), add recall { query }: it searches the
ledger + offloaded blobs for already-known facts/content so the agent doesn't re-pull the same
files. Instruct the agent to recall before querying the codebase. Ranking is semantic
when COMPACTION_EMBED_MODEL is set (e.g. Ollama nomic-embed-text), else lexical; auto
falls back gracefully. See SPEC.md §10C.
On Copilot (passthrough), context_compact produces a great summary but doesn't shrink
the live window — the server can't evict the host's messages, so the summary is additive.
The way to actually reclaim tokens is re-seed: compact → open a new chat → seed it from handoff_brief → continue. A new chat starts with an empty window.
handoff_brief returns the seed (rules + latest summary + ledger + files to re-open) and
always writes it to disk (and to outPath, e.g. .compaction/handoff.md), so a new chat
can attach the file even if MCP is blocked for the account. See SPEC.md §10A.
rules_set — pin session-long rules (survive every boundary).
files_track — list active files to re-hydrate.
…work… ledger_record whenever something is verified.
context_status → compact-soon? → context_compact { transcript, preserve }.
Install the returned block; drop everything before boundary. Continue.
v0.1 scaffold — stub logic is wired end-to-end and typechecks; replace the token
estimator (§ estimateTokens) with a real tokenizer and harden hook sandboxing before
production. Roadmap in SPEC.md §13.
Hard reset turns and boundaries. Keeps rules and ledger by default.
| Name | Required | Description | Default |
|---|---|---|---|
| keepRules | No | ||
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden. It discloses that rules and ledger are kept by default, but it does not state what happens to turns, boundaries, or other context, nor whether the reset is reversible or requires specific authorization. The 'hard reset' phrasing implies destructive behavior without detailing consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, containing only two short sentences, which is appropriate from a verbosity standpoint. However, it is under-specified to the point of being cryptic, and the terseness detracts from its utility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, and a schema with 0% description coverage, the description fails to provide a complete picture. It does not explain the return format, side effects on other context components, or how sessionId influences the reset, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two parameters (keepRules, sessionId) with 0% description coverage. The description's mention of keeping rules and ledger by default partially maps to keepRules but does not explain the boolean semantics or what happens when false. The sessionId parameter is entirely unaddressed, leaving its purpose and format unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Hard reset turns and boundaries') and identifies the resource, making the basic purpose clear. However, the term 'turns and boundaries' is somewhat ambiguous without context, and it doesn't explicitly differentiate from siblings like context_compact or context_trim beyond the 'hard' qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as context_compact or context_trim, nor are exclusions or assumptions mentioned. The description only implies usage for a hard reset without situating it among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize accumulated history into a dense block, snapshot the ledger, re-hydrate tracked files, and run Pre/PostCompact hooks. Returns the compacted context block to install as new ground truth.
| Name | Required | Description | Default |
|---|---|---|---|
| preserve | No | Extra preservation instructions, e.g. 'keep all exact error strings'. | |
| sessionId | No | ||
| transcript | No | Required in passthrough mode: the full history to compact. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses multiple behavioral traits beyond a simple summarize: it snapshots the ledger, re-hydrates tracked files, and runs Pre/PostCompact hooks. Since no annotations exist, this is valuable. It also states the return value. However, it does not mention potential destructive effects or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the primary action and lists additional side effects. No wasted words; every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core operation, side effects, and return value, which is adequate given no output schema. However, it omits context for 'passthrough mode' referenced in the transcript parameter and does not clarify sessionId, leaving some gaps for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes two of three parameters (preserve and transcript) with clear descriptions, but sessionId is undocumented. The tool description adds no parameter explanations or usage examples, leaving ambiguity about sessionId and passthrough mode.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs (summarize, snapshot, re-hydrate, run) and identifies the resource (accumulated history, ledger, tracked files). It clearly distinguishes from sibling tools like context_trim and context_clear by describing the full compaction process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for compacting accumulated history but does not provide explicit guidance on when to use it versus alternatives like context_trim or context_clear. No exclusions or alternative names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report context pressure and a compaction recommendation (ok | compact-soon | compact-now | at-limit).
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | ||
| tokenBudget | No | ||
| estTokensUsed | No | Host-reported current window usage; overrides server estimate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Report' implies a read-only operation, but it doesn't disclose how pressure is computed, whether server estimates are used by default, or that estTokensUsed overrides the estimate. Minimal behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that efficiently conveys the tool's output and recommendation levels. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a status tool with no output schema and no annotations. It doesn't explain what 'context pressure' means, how the recommendation is derived, or what the parameters do if omitted. The optionality of parameters is not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only estTokensUsed has a description), and the tool description adds no parameter semantics. It doesn't explain sessionId or tokenBudget, and fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports context pressure and a compaction recommendation, with the exact recommendation values. This distinguishes it from sibling tools that perform actions like compaction, trimming, or clearing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance is provided. The purpose implies it's a pre-compaction check, but the description doesn't state when to invoke it versus sibling tools or mention any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove low-value/duplicate tool output without an inference call. Store mode only.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | ||
| dropToolOutputOlderThanTurns | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the burden of behavioral disclosure. It discloses that the operation does not invoke inference and only works in store mode, which is useful. However, it does not explain side effects (e.g., irreversibility), what constitutes low-value/duplicate, or what happens if store mode is not active.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 11 words, front-loaded with the core action and key constraints. Every word earns its place; there is no filler or repetition. This is an example of efficient, well-structured writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description is incomplete given the absence of annotations and output schema. It lacks parameter explanations, usage conditions beyond 'store mode', and behavioral details. An agent would likely need clarification to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention the parameters at all. The parameters 'sessionId' and 'dropToolOutputOlderThanTurns' are only self-descriptive by name, which may be insufficient for an agent to know how to set them correctly. The description offers no compensation for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove low-value/duplicate tool output') and adds specific constraints ('without an inference call', 'Store mode only'). It distinguishes itself from siblings like context_compact and context_clear by focusing on pruning specific tool output rather than compressing or clearing all context. However, the phrase 'Store mode only' is ambiguous without additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for cleaning up low-value or duplicate tool output and restricts to store mode. It does not explicitly name alternatives or state when not to use this tool. The sibling list suggests related tools (context_compact, context_clear), but no comparison is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read tracked (or given) files from disk and return current contents.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | No | ||
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation via the verb 'Read', which is helpful, but it does not disclose potential side effects (e.g., updating tracked state, interactions with sessionId) or error conditions. With no annotations provided, the description carries the full burden and only partially fulfills it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the verb and provides the essential details. It avoids redundancy and is appropriately concise for the tool's simple purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters and no output schema, yet the description omits the meaning of 'sessionId', does not specify return format, and offers no usage context. The description is not complete enough for an agent to reliably decide when and how to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage. The description explains that 'paths' can provide given files, but it does not explain the 'sessionId' parameter at all, nor does it clarify the relationship between 'tracked' and 'given' files or how parameters combine. This leaves significant ambiguity for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Read') and target ('tracked (or given) files from disk'), and it clarifies the outcome ('return current contents'). This differentiates it from sibling tools like files_track or offload_fetch by focusing on loading file content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as read_offloaded, offload_fetch, or context_status. The description only mentions the mechanism ('tracked or given files') but does not explain under what circumstances one would rehydrate files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark files to silently re-read from disk on every compaction.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | ||
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that marking causes silent re-reads on every compaction, a useful behavioral trait. However, it does not mention side effects, persistence, or scope of the 'mark' operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool, the description covers the core action but leaves ambiguities around the optional sessionId parameter and potential return values. Given no output schema, more detail on behavior would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not describe 'paths' or 'sessionId' explicitly. 'paths' can be inferred from 'files', but 'sessionId' is unexplained, leaving a semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'mark' with resource 'files' and specifies the behavior 'silently re-read from disk on every compaction', clearly distinguishing it from siblings like files_untrack or files_rehydrate which imply opposite or immediate actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when files should be refreshed during compaction, but does not explicitly mention alternatives like files_untrack or exclusions. The context is clear enough but lacks explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop re-hydrating the given files.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | ||
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states the action ('stop re-hydrating') but omits side effects, reversibility, permission requirements, or impact on existing state/sessions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no unnecessary words. It is front-loaded and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is too sparse. It doesn't explain the context system, what re-hydration entails, or usage scenarios. Sibling tools are not referenced for differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description only implies that 'given files' correspond to the paths parameter, but doesn't explain the sessionId parameter or path format. This is insufficient compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stops re-hydrating specified files, using a specific verb and resource. It distinguishes from sibling tools like files_track and files_rehydrate by describing the inverse action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites, exclusions, or context where untracking is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Produce a small, self-contained brief (rules + latest summary + verification ledger + active files) to START A FRESH CHAT with. This is how you actually reclaim tokens on hosts that own their window (e.g. Copilot): open a new chat and seed it with this brief. Always written to disk too, so a new chat can attach the file even if MCP is unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
| outPath | No | Also write the brief here (must be within allowed roots), e.g. .compaction/handoff.md | |
| sessionId | No | ||
| includeFileContents | No | Inline current file contents for a fully self-contained brief (larger). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses a key side effect: 'Always written to disk too'. It also notes the brief is 'self-contained'. But it doesn't state whether this tool modifies the current context, requires specific permissions, or what the tool returns as its direct result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no fluff. The first sentence front-loads the verb and purpose, while the second provides practical context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It explains what the brief contains, its use case, and the disk-writing behavior. Missing are return-value details, prerequisites (e.g., active session or existing files), and clarification of sessionId. Given 3 parameters and no output schema, some gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, leaving sessionId undocumented. The description provides no parameter-level guidance, so it doesn't compensate for that gap. OutPath and includeFileContents are already described in the schema, but the tool description adds no further meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Produce') and resource ('re-seed handoff brief'), enumerates its contents ('rules + latest summary + verification ledger + active files'), and clearly states the goal ('to START A FRESH CHAT'). It also distinguishes itself from sibling tools by explaining the token-reclaiming workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool: to reclaim tokens on hosts like Copilot by opening a new chat and seeding it with the brief. It also mentions the disk-write fallback for MCP unavailability. However, it does not explicitly contrast with alternative context-management tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filter ledger entries by claim substring and/or result.
| Name | Required | Description | Default |
|---|---|---|---|
| result | No | ||
| sessionId | No | ||
| claimContains | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the filtering behavior but does not mention that all parameters are optional (behavior when no filters are applied), how filters combine (AND/OR semantics), or the return format/pagination. It also omits sessionId as a filterable field, which is part of the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is front-loaded with the operation ('Filter') and directly states the key criteria. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with 3 optional parameters and no output schema, so a brief description can be adequate. However, the description does not mention sessionId, does not explain default behavior when no filters are applied, and provides no output format details. These omissions make it incomplete for fully guiding an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides useful meaning for two of three parameters: 'claim substring' clarifies claimContains as a substring match, and 'result' maps to the enum. However, it omits sessionId entirely and does not explain how the filters interact, leaving a gap in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Filter' on a clear resource 'ledger entries' and specifies the filtering criteria ('claim substring and/or result'). This clearly distinguishes it from sibling tools like ledger_record (which likely records entries) and ledger_snapshot (which likely captures snapshots).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a query/filter use case but provides no explicit guidance on when to use this tool versus alternatives like ledger_snapshot or recall. There are no exclusions, prerequisites, or alternative tool references, leaving the agent without enough contextual decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append an entry to the verification ledger (maker/checker). Survives compaction; verified results are copied verbatim into summaries.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | agent | |
| claim | Yes | ||
| method | Yes | ||
| result | Yes | ||
| evidence | Yes | ||
| sessionId | No | ||
| supersedes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses key behavioral traits: appending (persistent write), surviving compaction (durability), and verbatim propagation to summaries (downstream effect). It does not fully cover reversibility or authorization, but the added context goes beyond a bare statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero fluff. The action verb is front-loaded, and the second sentence provides essential behavioral context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no annotations, and no output schema, the description offers some essential context (durability, summary propagation) but leaves parameter semantics and edge cases unaddressed. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only lightly hints at parameters via 'maker/checker' (for 'by') and 'verified results' (for 'result'/'evidence'), but leaves crucial parameters like claim, method, evidence, sessionId, and supersedes unexplained. This is a significant gap for a 7-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Append an entry') and a specific resource ('verification ledger (maker/checker)'), which differentiates it from read-oriented siblings like ledger_query and ledger_snapshot. This is a model of purpose clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool by highlighting that entries 'survive compaction' and feed 'summaries', which suggests durable verification records. However, it does not explicitly mention alternatives or provide exclusionary guidance, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full current ledger (used at boundaries for re-injection).
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the tool returns the ledger, implying a read-only operation, but does not describe any side effects, the meaning of the optional sessionId parameter, or potential limitations such as size or performance. This is insufficient detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently communicates the core action and primary use case, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and no output schema, but the description leaves the sessionId parameter unexplained and provides no details about the returned ledger's structure or size. While the core purpose is clear, the lack of parameter semantics and behavioral detail makes it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not explain the 'sessionId' parameter at all. Since the parameter is optional and its purpose is not revealed, the description adds no semantic value beyond the schema's type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'full current ledger', which precisely defines the tool's purpose. It also distinguishes from siblings like ledger_record and ledger_query by specifying 'full current' and the boundary re-injection context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'used at boundaries for re-injection' provides clear context for when to use this tool. It does not explicitly mention alternatives or exclusions, but the intended use case is clearly communicated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a blob's full content, or a 1-indexed inclusive line slice. Use the smallest slice that answers the question to keep the window small.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | ||
| endLine | No | ||
| startLine | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behavioral traits: the slice is 1-indexed and inclusive, and the tool can return full content or a slice. This adds valuable context beyond the schema, though it does not mention error handling or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core function ('Retrieve a blob's full content, or a 1-indexed inclusive line slice'), followed by practical guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with no output schema and no annotations, the description covers the basic retrieval behavior and slicing guidance. However, it lacks information about return format, error conditions, and how it differs from read_offloaded, leaving some context gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that startLine/endLine define a 1-indexed inclusive slice and that handle refers to a blob. However, it does not clarify that startLine and endLine are optional, must be used together, or any constraints like startLine <= endLine.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a blob's full content or a line slice, using a specific verb and resource. However, it does not differentiate from the sibling tool 'read_offloaded', which likely serves a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using the smallest slice to keep the window small, which is useful usage guidance for parameter selection. However, it does not explicitly state when to use this tool versus alternatives like read_offloaded or offload_store, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stash large text (command output, grep results, logs, API payloads) as a blob and return a digest + handle instead of putting it all in the window.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | ||
| content | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the core behavior (store text, return digest + handle) but omits lifecycle details such as persistence, retrieval methods, size limits, or whether the stored content affects context state. This is a partial disclosure, leaving important behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action, provides examples, and states the outcome. No extraneous words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple store tool with no output schema, the description covers the main purpose, usage context, and return value. It doesn't mention how to retrieve the stored blob (though sibling tools exist) or any persistence rules, but these are arguably outside this tool's scope. Overall, it's sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that 'content' is the large text being stashed, but does not explain the 'label' parameter's role or how it relates to the returned digest/handle. With only two simple string params, partial compensation is acceptable but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'Stash,' and clearly states the resource (large text as a blob) and the outcome (return a digest + handle). It also gives concrete examples (command output, grep results, logs, API payloads) and distinguishes itself from siblings like read_offloaded and context_compact by explaining the benefit of avoiding window clutter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you have large text that would otherwise occupy the window. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide appropriately relative to siblings like context_compact or offload_fetch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file from disk and OFFLOAD it: returns a short digest (preview + structural outline + line/byte counts) and a handle, instead of dumping the full contents into the window. Prefer this over a normal file read for large files. Fetch the full body only when needed via offload_fetch or the compaction://blob/{handle} resource.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| label | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on the burden of behavioral disclosure. It transparently explains the offload behavior (returns a digest, not full contents) and mentions the handle, but does not cover edge cases like file access errors or handle expiration. Still, the core behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, immediately front-loading the main behavior and return value, followed by concise usage guidance. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, and return format (digest components, handle), and points to alternatives for full content. It is fairly complete for a simple read/offload tool, though it omits details about the label parameter and handle lifecycle. Given no output schema, this is a reasonable level of completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists two parameters (path, label) with no descriptions, and the description does not explain either parameter. 'path' is implied by the tool name, but 'label' remains completely unexplained. With 0% schema coverage, the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a file and returns a digest and handle, explicitly contrasting with a normal file read by avoiding full content in the window. It also distinguishes itself from offload_fetch by indicating when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to prefer this tool over a normal file read for large files, and directs the user to offload_fetch or the compaction://blob/{handle} resource when the full body is needed. This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the verification ledger + offloaded blobs for already-known facts and content. CALL THIS BEFORE querying the codebase / context engine: a cached fact or a known blob line range avoids pulling whole files back into the window (token saver, esp. on hosts with their own retrieval like Augment). Semantic ranking when embeddings are configured, else lexical. Returns ledger hits + blob hits with line ranges (use with offload_fetch).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It reveals meaningful behavioral traits: semantic vs lexical ranking depending on embeddings, returning both ledger hits and blob hits with line ranges, and its link to offload_fetch. This adds valuable context beyond a simple search tool, even though it does not explicitly state 'read-only' or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler, front-loaded with the primary action. The second sentence is slightly long with a parenthetical, but each sentence adds distinct value. It is concise without being sparse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description covers the core functionality, use case, behavioral contingencies, and how to pair it with offload_fetch. The missing piece is parameter documentation, but overall it is complete enough for an agent to understand when and how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It only implicitly addresses the query (the search term) and mentions 'limit' indirectly via 'line ranges', but does not clarify the meaning of 'limit' or 'sessionId'. The description falls short of compensating for the complete lack of schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search the verification ledger + offloaded blobs for already-known facts and content.' This clearly distinguishes it from siblings like ledger_query (which only queries the ledger) and offload_fetch (which fetches offloaded content), making the tool's purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is present: 'CALL THIS BEFORE querying the codebase / context engine' and explains the benefit (avoids pulling whole files, token saver). It also mentions an alternative ('querying the codebase / context engine') and provides a concrete use case, making it highly actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a rule that survives every boundary.
| Name | Required | Description | Default |
|---|---|---|---|
| rule | Yes | ||
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states that the rule survives boundaries, but does not disclose the mutating nature, ordering, duplicates, permissions, or whether rules can be removed. This is a significant gap for an append/mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that is easily scannable. It is appropriately short, though it could still convey more useful details without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and two parameters, the description leaves important invocation details (e.g., what sessionId does, how rules are ordered, whether duplicates are allowed) unaddressed. The agent receives only the core purpose, not enough for full correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the description only implies the meaning of 'rule' but does not explain the optional 'sessionId' parameter. No additional meaning is added beyond the parameter names, so the description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Append') and resource ('a rule') and adds the key behavioral trait 'survives every boundary', indicating persistence. This clearly distinguishes it from sibling tools like rules_set and rules_get by the action of appending.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention rules_set, rules_get, or any scenarios where appending is preferred over setting or clearing rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the current persistent rules.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. Stating 'Return' implies a read-only operation, but it does not disclose behavior in edge cases like an invalid sessionId or whether result is a list or single object. It is minimal but acceptable for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource. Every word earns its place; no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and no output schema, so the description covers the core operation. However, it lacks sessionId context and usage guidance, making it adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention the sessionId parameter at all. The parameter's purpose and formatting remain unclear, and the description adds no value beyond the schema's empty property definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Return' and a clear resource 'persistent rules', which immediately distinguishes it from sibling tools like rules_set and rules_append that modify rules. It clearly states what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. While sibling tools (rules_set, rules_append) imply this is the getter, the description itself does not mention any exclusions, prerequisites, or alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the CLAUDE.md-equivalent rules that survive every boundary.
| Name | Required | Description | Default |
|---|---|---|---|
| rules | Yes | ||
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose that the tool replaces rules and that those rules persist across boundaries, which gives some behavioral context. However, it does not clarify whether it clears all previous rules, how rules are scoped, or any side effects. Some transparency exists but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys the core purpose without extra words. It is concise and front-loaded, with every part contributing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (2 params, no output schema, no annotations), the description is adequate for basic understanding but incomplete. Missing details like parameter semantics and a explicit statement that it overwrites all existing rules reduce completeness. It does not fully cover the behavioral nuances an agent would need for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters. The 'rules' parameter's name and the description suggest it holds the rule content, but there is no detail about formatting, allowed values, or the optional 'sessionId'. The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Replace' and clearly identifies the resource as 'CLAUDE.md-equivalent rules that survive every boundary.' This distinguishes it from siblings like rules_append and rules_get, which have different actions. The purpose is immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by saying 'Replace', which suggests this tool is for overwriting rules, contrasting with rules_append. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Guidance is only implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a message to the server-held transcript. Store mode only. When COMPACTION_AUTO=true and pressure crosses the compact-now threshold, compaction fires automatically and the compacted block is returned under autoCompacted.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | ||
| pinned | No | ||
| content | Yes | ||
| sessionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the core append behavior and the auto-compaction trigger, which is useful context, but it omits details about response format, error conditions, and prerequisites, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three sentences and a clear front-loaded action. It includes relevant edge-case behavior without unnecessary verbosity, though 'Store mode only' could be clarified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and zero parameter coverage, the description is incomplete. It covers the primary action and one edge case but lacks return value details, mode context, and parameter semantics, making it insufficient for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention any of the four parameters (role, content, pinned, sessionId). It adds no meaning beyond the schema's names and types, failing to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action with a specific verb 'append' and identifies the resource as 'server-held transcript.' It is distinct from the given sibling tools by function, though it does not explicitly name alternatives or differentiate itself from them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. The phrase 'Store mode only' is a condition but not a usage guideline, and no exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0context_clearcontext_compactcontext_statuscontext_trimfiles_rehydratefiles_trackfiles_untrackhandoff_briefledger_queryledger_recordledger_snapshotoffload_fetchoffload_storeread_offloadedrecallrules_appendrules_getrules_setturn_addThe tools cover distinct actions across context, files, offloading, rules, and ledger. Some close concepts (context_compact vs context_trim, handoff_brief vs context_compact, recall vs ledger_query) have subtle differences that require careful reading, but the descriptions disambiguate them. Overall, each tool has a specific role.
Most tools follow a resource_verb pattern (context_*, files_*, offload_*, rules_*, ledger_*), but a few outliers like read_offloaded and recall break this pattern. The prefix grouping is helpful and consistent within subgroups, making the set mostly predictable despite a few deviations.
At 19 tools, the set is on the heavier side. While each tool serves a distinct need across multiple subdomains (context, handoff, files, offload, rules, ledger), the number is above the typical 3-15 sweet spot, giving it a sense of bloat. A more focused server could combine some tools or drop rarely used ones.
The set covers the full lifecycle of context management: status, compact, trim, clear, handoff, turn recording, file tracking, offloading, recall, rules, and ledger. Missing operations include offload deletion and explicit restoration of compacted blocks, but these are minor and workarounds exist. Overall the surface is comprehensive.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Path-scoped team memories, rules and skills for Claude Code, Cursor, Codex and other MCP clients.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Ink01101011/compaction-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
