An optimization utility for AI agents that prevents context window overflow by automatically offloading large tool outputs to disk storage.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install tool-result-size-controller
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install tool-result-size-controller using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Tool Result Size Controller?
The Tool Result Size Controller is a developer-focused utility designed to solve the problem of token explosion in AI agent workflows. When an agent executes a tool that returns a massive amount of data, such as a large JSON response or an extensive file search, the resulting tokens can quickly consume the context window, leading to degraded performance or failed requests. This skill implements a mechanism similar to the maxResultSizeChars feature found in Claude Code, providing a safety layer for your Openclaw Skills.
By monitoring the size of every tool output, the controller can decide whether to pass the data through directly or 'spill' it to a local disk. If the data exceeds a configurable threshold, it is compressed and stored, and the agent receives a concise metadata object with a preview instead. This ensures that the agent stays informed about the result's existence without being overwhelmed by its raw volume.
Tool Result Size Controller Use Cases
- Managing massive API payloads or database query results that would otherwise crash the context window.
- Protecting long-running research agents from reaching token limits during data gathering phases.
- Archiving large tool outputs for secondary processing without cluttering the primary conversation history.
- Standardizing tool output behavior across complex multi-agent systems using Openclaw Skills.
How Tool Result Size Controller Works
- The controller intercepts tool output through either a Python decorator or a direct functional wrapper.
- It measures the character count of the returned data against a predefined threshold (default is 10,000 characters).
- If the result is within the limit, it returns the data to the agent as usual.
- If the result exceeds the threshold, the controller automatically compresses the data using Gzip.
- The compressed file is saved to a designated results directory with a unique timestamped filename.
- A metadata object containing the file path, size information, and a 500-character preview is returned to the agent.
- The agent can then use the file path to read the full content only when specifically required.
Tool Result Size Controller Setup
To integrate this into your agent environment, ensure the results directory is accessible and configured correctly within your Openclaw Skills workflow.
# Create the directory for spilled results
mkdir -p tmp/tool-results/
# Configure environment variables (optional)
export DEFAULT_THRESHOLD=10000
export MAX_AGE_DAYS=7
In your Python code, wrap your tool functions:
from tool_result_size_controller import ToolResultWrapper
@ToolResultWrapper("my_heavy_tool", threshold=5000)
def fetch_data():
return large_dataset
Tool Result Size Controller Data Schema & Taxonomy
When a result is spilled to disk, the controller returns a structured JSON object to the agent instead of the raw string. This schema is standard across all Openclaw Skills using this controller:
| Property | Type | Description |
|---|---|---|
| spilled | boolean | Indicates if the result was offloaded to disk |
| file_path | string | The absolute path to the stored .gz file |
| size_chars | integer | The total character count of the original data |
| size_bytes | integer | The size of the compressed file on disk |
| content_hash | string | A unique hash for data verification |
| preview | string | The first 500 characters of the result for immediate context |
Tool Result Size Controller Advanced Features
- Intelligent Gzip compression automatically applied to any result over 10KB to save disk space.
- Automated cleanup routines that prune old result files based on a configurable retention policy (default 7 days).
- Transparent reading capabilities that allow agents to reload spilled data via a dedicated loading function.
- Granular threshold control allowing developers to set different limits for quick queries versus heavy file processing tasks.
- Comprehensive audit logging that tracks every spill event, including tool names and data sizes, for debugging and optimization.
SKILL.md
Loading
Related Openclaw Skills
Neural Learning Engine
A lightweight AI module that simulates a neural network learning loop to enable pattern recognition and adaptive responses in intelligent agents.
Safe File Editor
A robust file editing utility for AI agents that implements atomic operations, mandatory diff previews, and automated rollback recovery.
DeFi Skills
A stateless engine that converts natural language DeFi intents into deterministic, unsigned Ethereum transactions across major protocols.
Financial Index Pro
An AI-powered financial assistant that simplifies complex market indices using master investment frameworks and witty, conversational logic.
Session Context Injector
A specialized skill that ensures AI agents maintain project continuity in Telegram by injecting context from local status files after session resets.
Agent Concurrency Controller
A Fail-Closed scheduling layer for Openclaw Skills designed to manage agent concurrency, prevent network conflicts, and enforce granular permission auditing.
Featured*
