Click on "Deploy 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., "@TokenSaver MCP compress my 10-turn conversation history"
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.
Cut your AI API costs by up to 97% — without changing a single prompt.
An MCP (Model Context Protocol) server that gives AI agents ten tools to measure, compress, cache, and prune token usage — so developers on limited plans can do more with less.
Every API call sends more tokens than necessary. Conversation history accumulates. Web pages arrive as raw HTML. Tool results get re-fetched on every turn. System prompts bloat over iterations.
TokenSaver intercepts each of these patterns and fixes them at the agent level — no model changes, no prompt engineering, no plan upgrades.
Scenario | Before | After | Saved |
10-turn conversation history | 40,000 tokens | 8,000 tokens | 80% |
Webpage fetch (raw HTML) | 22,000 tokens | 1,200 tokens | 94% |
Bloated system prompt | 600 tokens | 220 tokens | 63% |
Repeated tool call (cached) | 1,500 tokens | 50 tokens | 97% |
Related MCP server: claw-tsaver
Tool | What it does |
| Measure token cost before sending — decide whether to compress first |
| Shrink long text or conversation history with offline LSA summarization |
| Persist tool results to disk with TTL — never run the same lookup twice |
| Fetch a URL and return only the readable content, not raw HTML |
| Get a structural + content summary of any file or directory |
| Remove filler turns and compress old messages in conversation history |
| Shorten verbose system prompts while preserving constraints |
| Diagnose token bloat and get targeted recommendations |
All tools work fully offline — no API key required for core features.
git clone https://github.com/pozii/tokensaver.git
cd tokensaver
pip install -e .Python 3.11+ required. On first use,
compress_contextwill auto-download the NLTKpunkt_tabtokenizer (~2 MB) if not already present.
TokenSaver has no URL and runs no background server by default. It uses stdio transport: the AI client reads your config, spawns python -m tokensaver as a child process, and talks to it through stdin/stdout. You never open a port or start anything manually — the client does it for you when it launches.
Your AI client ──spawn──▶ python -m tokensaver ──stdio──▶ tools availableThe alternative is SSE transport, where you start the server yourself on a local port and the client connects over HTTP. This is useful for multi-agent setups or when multiple clients share the same server instance.
Config file location:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"tokensaver": {
"command": "python",
"args": ["-m", "tokensaver"]
}
}
}Save the file and restart Claude Desktop. The tokensaver tools will appear in the tool list.
claude mcp add tokensaver -- python -m tokensaverOr add manually to ~/.claude/settings.json:
{
"mcpServers": {
"tokensaver": {
"command": "python",
"args": ["-m", "tokensaver"]
}
}
}Config file: ~/.config/opencode/config.json
{
"mcp": {
"servers": {
"tokensaver": {
"type": "local",
"command": ["python", "-m", "tokensaver"]
}
}
}
}Start the server once:
python -m tokensaver --transport sse --port 8765Then point your client at:
http://localhost:8765/sseIf your system has multiple Python versions and python resolves to the wrong one, use the full path:
# Find the right Python
which python3 # macOS / Linux
where python # WindowsThen use the full path in your config:
{
"mcpServers": {
"tokensaver": {
"command": "/usr/local/bin/python3",
"args": ["-m", "tokensaver"]
}
}
}{
"mcpServers": {
"tokensaver": {
"command": "C:\\Python314\\python.exe",
"args": ["-m", "tokensaver"]
}
}
}Each turn:
1. count_tokens → How large is my current context?
2. advise_context_window → Am I approaching the model's limit?
Before expensive tool calls:
3. cache_get → Did I already run this?
When fetching web content:
4. extract_webpage → Clean text, not raw HTML
When history grows long:
5. prune_conversation → Drop filler turns, compress old ones
6. compress_context → Shrink large injected context blocks
When writing system prompts:
7. optimize_prompt → Remove redundant phrasing{
"content": "Some long text or list of messages...",
"model": "claude-sonnet-4",
"include_message_overhead": true
}Returns token_count, encoding_used, model. Accepts a plain string or an OpenAI-format message list.
{
"text": "3,000-token context block...",
"target_tokens": 600,
"mode": "extractive"
}extractive (default) uses LSA sentence ranking — free, offline, no API call.abstractive uses claude-haiku for higher quality — requires ANTHROPIC_API_KEY.
Returns compressed, original_tokens, compressed_tokens, reduction_pct.
# Standard pattern: check before running
key = cache_key("extract_webpage", {"url": "https://example.com"})
hit = cache_get(key=key)
if not hit["hit"]:
result = extract_webpage(url="https://example.com")
cache_store(key=key, value=str(result), ttl_seconds=3600)Cache is stored on disk at ~/.tokensaver/cache/ and survives server restarts.
{
"url": "https://example.com/article",
"max_tokens": 2000,
"include_links": false,
"include_metadata": true
}Uses trafilatura with BeautifulSoup as fallback. Returns content, title, token_count, truncated.
{
"path": "/home/user/myproject",
"mode": "both",
"max_tokens": 500,
"file_extensions": [".py", ".md"],
"max_depth": 3
}mode options: "structure" (tree only), "content" (summarized text), "both".
{
"messages": [...],
"max_output_tokens": 2000,
"keep_last_n": 4,
"prune_strategy": "hybrid"
}"remove" drops filler turns ("Sure!", "Got it.")."compress" summarizes older turns in place."hybrid" does both — recommended for most cases.
Returns the pruned messages list, original_tokens, pruned_tokens, counts of removed/compressed turns.
{
"prompt": "Please make sure to always answer questions...",
"optimization_level": "medium",
"preserve_constraints": true,
"output_format": "prose"
}"light" removes filler phrases. "medium" deduplicates sentences. "aggressive" restructures.preserve_constraints: true always keeps sentences containing never, must, always, do not.
{
"model": "gpt-4o",
"current_tokens": 110000,
"messages": [...],
"target_utilization": 0.75
}Returns status ("ok" / "warning" / "critical"), headroom_tokens, prioritized recommendations, and a per-turn breakdown sorted by token cost.
Supports: GPT-4o, GPT-4o-mini, Claude 3–4 series, Gemini 1.5/2.0/2.5, O1/O3, Llama 3, Mistral.
For higher-quality abstractive compression on very large texts (>5,000 tokens):
pip install "tokensaver-mcp[llm]"Set ANTHROPIC_API_KEY in your environment or a .env file, then use mode: "abstractive" in compress_context.
pip install -e ".[dev]"
python -m pytest tests/ -v38 tests — all offline, no API key or network required.
src/tokensaver/
server.py # FastMCP app, tool registration
models.py # Context window table, shared types
tools/
counter.py # count_tokens
compress.py # compress_context
cache.py # cache_store / cache_get / cache_invalidate
extractor.py # extract_webpage
summarizer.py # summarize_file
pruner.py # prune_conversation
optimizer.py # optimize_prompt
advisor.py # advise_context_window
utils/
token_utils.py # tiktoken wrapper
text_utils.py # sentence splitting, deduplicationAnalyze current token usage vs model context window and recommend what to trim. Use this meta-tool to know WHERE to apply compress_context, prune_conversation, or other tokensaver tools for maximum effect.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | Model name (e.g. "claude-sonnet-4", "gpt-4o", "gemini-1.5-pro"). | |
| current_tokens | Yes | Current total tokens being sent (use count_tokens first). | |
| messages | No | Optional conversation history for per-turn breakdown. | |
| target_utilization | No | Fraction of context window to target (default 0.75 = 75%). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool analyzes and recommends, but omits details about the output format, whether it is read-only, or any side effects. Since no annotations are provided, the description carries the full burden; more specifics on what 'recommend' entails would improve transparency.
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 long, with the first sentence stating the core function and the second providing usage context. It is front-loaded and every word adds value.
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 comprehensive input schema and the presence of an output schema (not detailed but noted), the description provides sufficient context for tool selection. It mentions sibling tools and usage context. Minor gap: it could briefly describe the output structure, but the existing output schema compensates.
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 100% description coverage, so the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions; it does not elaborate on how parameters like 'current_tokens' or 'target_utilization' are used.
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 identifies the tool as a meta-tool that analyzes token usage and recommends trimming actions. It distinguishes itself from sibling tools like compress_context and prune_conversation by positioning itself as a diagnostic step before applying those tools.
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 tells when to use this tool: before applying compression tools, and it names specific sibling tools (compress_context, prune_conversation) as targets. It does not provide explicit 'when not to use' guidance, but the context is clear enough for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a cached result. If hit, skip re-running the original tool.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Cache key used in cache_store. | |
| namespace | No | Must match the namespace used in cache_store. | default |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. States hit behavior, but doesn't disclose miss behavior or possible error conditions. Good but could be more explicit.
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?
Single sentence, front-loaded with essential purpose. No unnecessary 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?
Output schema exists, so return structure is defined. Description covers core behavior (hit/miss skip), but misses explicit mention of miss behavior. Adequate for simple cache get.
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 100%, and parameter descriptions already explain each parameter. The description adds no additional parameter meaning beyond the schema.
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?
Clear verb 'Retrieve' and resource 'cached result', with behavioral constraint 'If hit, skip re-running the original tool'. Distinguishes from siblings like cache_store and cache_invalidate.
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 guidance on when to use this vs alternatives. The description implies usage when a cached result exists, but doesn't address when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a stale cache entry (e.g. after file changes).
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Cache key to remove. | |
| namespace | No | Must match the namespace used in cache_store. | default |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states 'remove' without disclosing side effects (e.g., error handling if key missing, permissions needed, or whether operation is idempotent).
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?
Single sentence that is front-loaded with verb and resource, followed by a helpful example. 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 invalidation tool with 2 parameters and an output schema, the description is largely sufficient. Missing details like behavior on missing keys, but overall adequate.
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 covers 100% of parameters with descriptions. The tool description adds no further semantics beyond the schema, so baseline score applies.
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?
Description clearly states verb ('Remove') and resource ('stale cache entry'), with a concrete example ('after file changes'). Distinguishes from sibling tools like cache_get and cache_store.
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?
Provides a clear context for use (after file changes), but does not explicitly mention when not to use or alternatives. Still, the example gives practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a tool result in the persistent cache with a TTL. Prevents re-running the same expensive operation twice. Recommended: set key = make_cache_key(tool_name, args).
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Cache key (use make_cache_key helper for deterministic keys). | |
| value | Yes | Result to store (JSON string or plain text). | |
| ttl_seconds | No | How long to keep (default 1 hour). Use 0 for no expiry. | |
| namespace | No | Logical group (e.g. "web", "files", "default"). | default |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses caching with TTL and purpose, but omits details like key conflict behavior, return value, persistence guarantees, or error handling. Lacks depth for a full behavioral model.
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, both relevant and front-loaded. No redundant or unnecessary text. Highly efficient.
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?
Covers main purpose and key recommendation. Output schema exists but description doesn't mention return value, nor does it address edge cases (e.g., overwriting existing keys). Adequate for a caching tool but could be more 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?
With 100% schema coverage, baseline is 3. The description adds value by recommending the make_cache_key helper for the key parameter, which clarifies intended usage beyond the schema's generic description.
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 caches tool results with TTL and prevents re-running expensive operations. It distinguishes from sibling tools like cache_get and cache_invalidate by focusing on storage.
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 make_cache_key for deterministic keys and explains the benefit (avoid re-running expensive operations). Could explicitly mention when to use alternatives (e.g., cache_get before storing) but provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compress long text or conversation history into a dense summary. Use before re-injecting large context on repeated turns.
Extractive mode (default): offline, free, uses LSA sentence ranking. Abstractive mode: higher quality but requires ANTHROPIC_API_KEY env var.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The content to compress. | |
| target_tokens | No | Approximate desired output size in tokens. | |
| mode | No | "extractive" (free/offline) or "abstractive" (LLM-backed). | extractive |
| preserve_format | No | If True, output as bullet points; else dense prose. | |
| model | No | Used for token counting (does not affect which API is called). | gpt-4o |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: extractive is offline/free using LSA, abstractive requires ANTHROPIC_API_KEY, and model param only for token counting. Could mention limits or errors but sufficient.
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 clear paragraphs, no wasted words. First sentence states purpose, then usage, then mode details. Well structured and efficient.
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 5 parameters, 1 required, and output schema exists, the description covers core behavior, usage, modes, and clarifies the model parameter's role. Missing potential error handling but overall complete for the task.
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 100%, baseline 3. Description adds meaning beyond schema: explains 'extractive' uses LSA, 'abstractive' needs API key, and preserve_format affects output style. Adds value.
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 it compresses long text or conversation history into a dense summary. It distinguishes from siblings by specifying two modes (extractive vs abstractive) and their characteristics.
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?
Explicitly recommends usage 'before re-injecting large context on repeated turns' and distinguishes between modes. However, it does not directly compare with sibling tools like prune_conversation or summarize_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate token count for text or a message list before sending to an API. Use this to decide whether to compress, prune, or skip content.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Plain string OR list of {"role": "...", "content": "..."} dicts. | |
| model | No | Model name — used to pick the right tokenizer encoding. | gpt-4o |
| include_message_overhead | No | Add per-message role/separator overhead (4 tokens each). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full burden for behavioral disclosure. It only states 'estimate token count' without explaining how estimation works (e.g., local tokenizer, model-dependence, accuracy) or any side effects, which is insufficient for a tool requiring trust in its output.
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: first states purpose, second gives usage advice. No redundant words, front-loads key information, and earns its brevity.
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 presence of an output schema (so return values need not be described), the description covers purpose and usage adequately but misses details about how the count is determined and potential limitations, which is a notable gap for a utility 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 coverage is 100% with well-described parameters including defaults and behavior (e.g., 'include_message_overhead' description). The description adds little beyond the schema, so baseline score of 3 is appropriate.
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 'estimate' and resource 'token count for text or a message list', distinguishing it from sibling tools like 'compress_context' or 'prune_conversation' by positioning it as a pre-action decision tool.
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 says 'Use this to decide whether to compress, prune, or skip content', giving clear context for when to invoke this tool. However, it does not explicitly state when not to use it or mention alternatives beyond implied ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a webpage and return only its main readable content — no HTML, scripts, navigation, ads, or cookie banners. Saves 85–95% of tokens vs raw HTML.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to fetch. | |
| max_tokens | No | Truncate output to this many tokens if exceeded. | |
| include_links | No | If True, preserve hyperlinks as [text](url). | |
| include_metadata | No | If True, prepend title/author/date when available. | |
| model | No | Used for token counting. | gpt-4o |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the core behavior (stripping clutter, token savings) and mentions truncation and metadata inclusion via parameters. However, it does not disclose error handling (e.g., fetch failures), rate limits, authentication requirements, or how dynamic content is handled. This leaves gaps in understanding the tool's full behavior.
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: two sentences with no unnecessary words. The first sentence explains the core action and output; the second gives a quantifiable benefit. Every word earns its place, and the main idea is front-loaded.
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 tool's moderate complexity (5 parameters, output schema exists), the description covers the essential behavioral aspects and parameter effects. It lacks some contextual completeness regarding error conditions and network dependencies, but the presence of an output schema and complete parameter descriptions compensates. It is mostly sufficient for an informed AI 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 100%, meaning the input schema already fully describes each parameter's purpose. The tool description adds no additional semantic detail beyond summarizing the overall behavior. Per the guidelines, baseline is 3 when coverage is high.
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 function: fetch a webpage and return only the main readable content. It specifies what is removed (HTML, scripts, navigation, ads, cookie banners) and quantifies the token savings. This makes the purpose unmistakable and distinct from raw HTML fetching tools.
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 you need clean textual content from a URL, but it does not explicitly state when to use this tool versus alternatives like cache tools or compress_context. Siblings are primarily for context management, so the usage context is somewhat clear, but no direct guidance on prerequisites or when not to use it is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shorten a verbose or redundant prompt/system prompt while preserving intent. Typical savings: 30–65%. Run once on system prompts that accumulate over iterations.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The prompt text to optimize. | |
| optimization_level | No | "light" removes obvious filler, "medium" restructures, "aggressive" rewrites minimally. | medium |
| preserve_constraints | No | Never remove sentences with "never/must/always/do not". | |
| output_format | No | "prose" for flowing text, "bullets" for a bulleted list. | prose |
| model | No | Used for token counting. | gpt-4o |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions preserving intent and typical savings, but lacks details on safety, rate limits, or side effects. The description of the model parameter indicates token counting, but overall limited behavioral disclosure.
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: first states purpose, second gives usage context and typical savings. Concise and front-loaded with no fluff.
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 5 parameters, good schema, and an output schema, the description is adequate but does not fully explain when to use this vs siblings like compress_context, nor the exact return format (though output schema exists).
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 100%, so baseline 3. The description adds minimal extra meaning beyond param descriptions; it provides context like 'run once' and typical savings, but most parameter info is in the schema.
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?
Description clearly states 'Shorten a verbose or redundant prompt/system prompt while preserving intent', using a specific verb ('shorten') and resource. It also provides typical savings (30–65%), distinguishing it from siblings like compress_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?
Explicitly says 'Run once on system prompts that accumulate over iterations', giving clear context. However, it does not mention when not to use or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reduce conversation history token footprint by removing filler turns and compressing older verbose ones. Saves 60–80% on long conversations.
| Name | Required | Description | Default |
|---|---|---|---|
| messages | Yes | OpenAI-format list of {"role": "...", "content": "..."} dicts. | |
| max_output_tokens | No | Target total size for the pruned history. | |
| keep_last_n | No | Always preserve the N most recent turns verbatim. | |
| prune_strategy | No | "remove" drops low-value turns, "compress" shrinks older turns, "hybrid" does both. | hybrid |
| model | No | Used for token counting. | gpt-4o |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full transparency burden. It states actions but doesn't disclose side effects (e.g., irreversibility, potential loss of important messages) or define 'filler turns'. Lacks important behavioral details.
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 concise sentences, front-loaded with action and benefit. No redundant information. Every sentence adds value.
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 having an output schema, the description doesn't mention what the tool returns (pruned messages). For a tool with 5 parameters and one required array, more context on output and behavior is needed for complete understanding.
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 100%, so baseline is 3. The description adds no additional context for parameters beyond their schema descriptions, e.g., does not explain when to use remove vs compress strategies.
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 reduces token footprint by removing filler turns and compressing verbose ones, with a specific resource (conversation history) and verb (prune). It distinguishes from sibling tools like compress_context by mentioning removal as well, though not explicitly.
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 on when to use vs alternatives (e.g., compress_context, count_tokens). Only implies use for long conversations via the benefit claim, but no when-not or explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize a file or directory without reading every byte. Agents get full structural understanding in ~500 tokens instead of 50,000+.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a file or directory. | |
| max_tokens | No | Total output budget in tokens. | |
| mode | No | "content" (summary of text), "structure" (tree only), "both". | both |
| file_extensions | No | Filter by extensions like [".py", ".md"] (directory only). | |
| max_depth | No | Directory traversal depth limit. | |
| model | No | Used for token counting. | gpt-4o |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only mentions token efficiency but does not disclose behavioral traits such as permissions, limits, or what happens with non-text files.
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, 17 words, front-loaded with purpose. Every sentence adds value with zero 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?
Moderate complexity with 6 params and output schema present. Description is minimal but schema covers parameters. Lacks usage guidance and behavioral context needed for full 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 100%, so baseline is 3. Description does not add new meaning to parameters beyond what schema already provides.
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?
Clearly states verb 'summarize' and resource 'file or directory', distinguishes from reading every byte, and highlights efficiency benefit of ~500 tokens vs 50,000+.
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 guidance on when to use this tool versus siblings like compress_context or extract_webpage. No when-not-to-use or alternative naming.
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.
v0.1.0advise_context_windowcache_getcache_invalidatecache_storecompress_contextcount_tokensextract_webpageoptimize_promptprune_conversationsummarize_fileScored across 10 tools
Each tool targets a clearly distinct purpose: advising, caching, compressing, counting, extracting, optimizing, pruning, and summarizing. No two tools overlap in functionality, reducing the chance of misselection.
Most tools follow a verb_noun pattern (e.g., compress_context, count_tokens), but the cache tools use noun_verb (cache_get, cache_invalidate). This minor inconsistency prevents a perfect score.
With 10 tools, the server is well-scoped for token management. Each tool covers a necessary aspect (analysis, caching, compression, extraction, counting, optimization, pruning, summarization) without redundancy or bloat.
The tool surface covers the core lifecycle: analyze usage, apply various compressions, cache results, and count tokens. A minor gap is the lack of an automatic application tool that acts on advisement, but the exist set is sufficient for most workflows.
Cloudflare Workers MCP server: ai-cost-optimizer
MCP server for building and testing AI agents with multi-model experimentation and insights.
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
Cloud-hosted MCP server for durable AI memory
