# How to Configure Headroom to Exclude Specific Tools from Compression

> Learn how to configure Headroom to exclude specific tools from compression easily. Use CLI flags, environment variables, or programmatically exclude tools.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-06

---

**You can configure Headroom to exclude specific tools from compression using the `--exclude-tools` CLI flag, the `HEADROOM_EXCLUDE_TOOLS` environment variable, or by passing an `exclude_tools` set to the `ContentRouter` class programmatically.**

Headroom is an open-source proxy that optimizes LLM tool call outputs through intelligent compression. To configure Headroom to exclude specific tools from compression, you modify the `ContentRouter` behavior via command-line arguments, environment configuration, or direct Python API calls, ensuring that designated tools like `Read` or `Glob` pass through to the LLM uncompressed.

## How ContentRouter Determines Compression Eligibility

The `ContentRouter` class (implemented in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py)) acts as the gatekeeper for tool output compression. By default, it references the `DEFAULT_EXCLUDE_TOOLS` constant defined in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) (lines 34-38), which contains a hardcoded set of tool names that typically produce large binary blobs or file contents unsuitable for compression.

When processing a tool call, the router checks whether the tool's ID exists in the exclusion set. If excluded, the router adds the marker `router:excluded:tool` to the routing log and returns the original output without modification, completely bypassing the standard Compress-Cache-Retrieve (CCR) pipeline.

## Three Methods to Configure Tool Exclusion

You can override the default exclusion list through three distinct interfaces, all converging on the `exclude_tools` configuration field in `ContentRouterConfig`.

### Using the --exclude-tools CLI Flag

The proxy server parses the `--exclude-tools` flag in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py) (lines 3150-3170). The `_parse_exclude_tools` function splits comma-separated values and merges them with the configuration. This method replaces `DEFAULT_EXCLUDE_TOOLS` entirely when the flag is non-empty.

```bash

# Exclude Read and Glob tools from compression

headroom --exclude-tools Read,Glob

```

### Using the HEADROOM_EXCLUDE_TOOLS Environment Variable

For Docker or Kubernetes deployments, set the `HEADROOM_EXCLUDE_TOOLS` environment variable (also parsed in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py), lines 3158-3168):

```bash
export HEADROOM_EXCLUDE_TOOLS="Read,Search,CustomTool"
headroom

```

This achieves identical behavior to the CLI flag without modifying startup commands, making it ideal for containerized environments.

### Programmatic Configuration via ContentRouter

When using Headroom as a Python library, instantiate `ContentRouter` with a custom `ContentRouterConfig`:

```python
from headroom.transforms import ContentRouter, ContentRouterConfig

router = ContentRouter(
    ContentRouterConfig(
        exclude_tools={"MyCustomTool", "LegacyAPI"}
    )
)

result = router.compress("some content")
print(result.routing_log)  # Contains "router:excluded:tool" for excluded tools

```

This approach (implemented in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py), lines 505-508) allows dynamic exclusion lists based on runtime conditions or user preferences.

## Internal Implementation Details

Inside `ContentRouter._compress()` (around lines 1900-1906), the exclusion logic builds a set of tool IDs to skip before processing:

```python
exclude_tools = (
    self.config.exclude_tools
    if self.config.exclude_tools is not None
    else DEFAULT_EXCLUDE_TOOLS
)
excluded_tool_ids = {
    tool_id for tool_id, name in tool_name_map.items() 
    if name in exclude_tools
}

```

If a tool call's `tool_use_id` matches an entry in `excluded_tool_ids`, the compression pipeline halts immediately for that specific output, preserving the raw tool response.

## Effects on Downstream Processing

Excluding a tool from compression affects two key downstream behaviors in the Headroom pipeline:

- **CCR Markers**: Excluded tools do not receive `compress:`, `cache:`, or `retrieve:` markers in the final payload, as they bypass the compression pipeline entirely according to the logic in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py).

- **Cost Telemetry**: The system records exclusion events via the `router:excluded:tool` marker in [`headroom/proxy/cost.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/cost.py) (lines 70-78). This enables accurate cost accounting and observability even for uncompressed tool outputs.

## Disabling Exclusion Entirely

To subject **all** tool output to compression—including the default `Read` and `Glob` tools—pass an empty string to either configuration method:

```bash

# Via CLI

headroom --exclude-tools ""

# Via environment variable

export HEADROOM_EXCLUDE_TOOLS=""
headroom

```

This sets `exclude_tools` to an empty set, meaning `DEFAULT_EXCLUDE_TOOLS` is ignored and no tools receive special treatment.

## Summary

- Headroom's `ContentRouter` controls compression eligibility via the `exclude_tools` configuration field defined in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py).
- Default exclusions (`Read`, `Glob`, etc.) live in `DEFAULT_EXCLUDE_TOOLS` within [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py).
- Configure exclusions via `--exclude-tools` CLI flag, `HEADROOM_EXCLUDE_TOOLS` environment variable, or `ContentRouterConfig` programmatically.
- Excluded tools bypass CCR markers but still log `router:excluded:tool` events to [`headroom/proxy/cost.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/cost.py) for cost tracking.
- Pass an empty string to disable exclusion entirely and compress all tool outputs without exception.

## Frequently Asked Questions

### What happens if I specify both the CLI flag and the environment variable?

According to the source code in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py), the `--exclude-tools` CLI flag takes precedence and overrides the `HEADROOM_EXCLUDE_TOOLS` environment variable. If the flag is omitted, the system falls back to the environment variable, and if neither is set, it uses `DEFAULT_EXCLUDE_TOOLS`.

### Can I exclude custom tools that I've defined myself?

Yes. The `exclude_tools` set accepts any string tool name. When using the Python API, simply include your custom tool names in the set passed to `ContentRouterConfig`. The router checks tool names case-sensitively against this list, so ensure the names match exactly what the LLM generates in tool calls.

### Why are Read and Glob excluded by default?

These tools typically return large file contents or directory listings that are either already compressed binary data or don't benefit from text-based compression algorithms. The `DEFAULT_EXCLUDE_TOOLS` constant in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) protects these high-volume outputs from unnecessary processing overhead and potential data corruption through text compression.

### How can I verify that a tool is actually being excluded?

Check the routing log output from the `ContentRouter`. When a tool is excluded, the router adds the `router:excluded:tool` marker to the routing log. You can also inspect the final payload to confirm that CCR markers are absent for that specific tool's output, or query the cost telemetry in [`headroom/proxy/cost.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/cost.py) which tracks these exclusion events separately from compression events.