tooltrim: Compress LLM Agent Tool Outputs

Overview

tooltrim is a Python library and proxy for compressing the results returned by agent tools, such as fetched pages, JSON responses, logs, and documents. It targets context bloat caused by replaying large tool outputs across agent turns, rather than compressing prompts or conversation history.

Its extractive approach keeps selected content and stores the original for retrieval by reference. The project also includes benchmarks for token savings and answer faithfulness, though those results are based on the project’s own test cases and should be validated against your workload.

Key Features

• Wrap Python tools with a decorator or use the ToolCompressor API to compress string outputs.
• Apply content-specific handling for HTML, JSON, tabular data, logs, and plain text.
• Use a query to prioritize relevant content with BM25, or configure an embedding scorer.
• Retrieve the original output, or a slice of it, using a reference returned with the compressed result.
• Run an OpenAI-compatible proxy that also accepts Anthropic message formats and compresses tool results in flight.
• Integrate with LangChain, LlamaIndex, OpenAI Agents, and MCP through optional packages.
• Use a CLI, streaming compression, and file, Redis, or S3 stores for different deployment needs.

Use Cases

• An agent that fetches long web pages can keep relevant passages in its context while retaining access to the full page.
• Teams using tools that return large JSON arrays, CSV exports, or log dumps can reduce repeated context without simply truncating the output.
• Applications that need to try output compression without modifying agent code can route compatible OpenAI or Anthropic requests through the proxy.
• Framework users can wrap existing LangChain, LlamaIndex, OpenAI Agents, or MCP tools rather than replacing their agent setup.

Getting Started

Install the core package:

pip install tooltrim

See the README for examples, optional integrations, proxy setup, and benchmark details.

Considerations

The project is new, so its recent development and releases are encouraging but do not establish long-term maintenance. Most contributions come from one person, and the supplied health data shows no issues closed or pull requests merged in the last 90 days; this is limited evidence of issue-handling practices, especially for a young repository. Compression is extractive and can omit information, so test it against representative tool outputs and provide expand() access where omissions could affect agent behavior. The README reports promising single-turn faithfulness results, while its multi-step tau-bench evaluation remains under pilot; frontier-model runs and native streaming passthrough in the proxy are listed as roadmap items. The core has no runtime dependencies, but optional features may require additional packages or services such as Redis, S3, or embedding models.