What Is `tool_result_snip_ratio` in DeepSeek-Reasonix? Pruning Stale Tool Output Before Compaction

tool_result_snip_ratio is a configurable float (default 0.6) that defines the exact token threshold at which the DeepSeek-Reasonix agent truncates ("snips") stale tool-call results before the compaction step, preserving only head and tail fragments to reduce context window pressure while maintaining reasoning continuity.

Managing context window pressure is critical for long-running LLM agents. In the esengine/DeepSeek-Reasonix repository, the tool_result_snip_ratio parameter provides fine-grained control over when obsolete tool output gets truncated prior to summarization. This guide examines the source code implementation to explain how this threshold triggers pruning and preserves essential reasoning fragments.

Understanding tool_result_snip_ratio Configuration

TOML Configuration and Struct Definition

In internal/config/config.go, the parameter appears as a float64 field within the agent configuration struct at line 1276:

ToolResultSnipRatio float64 `toml:"tool_result_snip_ratio"`

This allows operators to tune the pruning sensitivity via configuration files or environment variables.

Default Value Declaration

The default value of 0.6 (60% of the context window) is defined as a constant in internal/agent/compact.go at line 27:

const defaultToolResultSnipRatio = 0.6

When unspecified, the agent begins snipping stale tool results once token usage exceeds 60% of the total available context window.

How the Snip Threshold Triggers Pruning

Calculating the Three Context Window Thresholds

The agent computes distinct operational thresholds from the total contextWindow size in internal/agent/compact.go at line 84:

soft := int(a.contextWindow * a.compactRatio)
snip := int(float64(a.contextWindow) * a.toolResultSnipRatio)
high := // trigger for full compaction

These thresholds create distinct operational zones:

• soft — Initiates normal soft compaction of the conversation history.
• snip — The specific point where stale tool result snipping begins.
• high — The critical threshold forcing complete compaction or a new request.

The Snip Window Trigger Condition

During each agent run, the current PromptTokens count is evaluated against these thresholds in internal/agent/prune.go at line 144:

if u.PromptTokens >= snip && u.PromptTokens < high {
    // snip stale tool results before summary compaction
}

When token usage falls within the [snip, high) range, the agent invokes SnipStaleToolResults() to preemptively reduce payload size before full compaction becomes necessary.

The Snipping Mechanism Implementation

SnipStaleToolResults() Function

The SnipStaleToolResults() function in internal/agent/prune.go processes eligible tool messages when the threshold is breached. Rather than deleting content entirely, it rewrites tool results using a compact placeholder format defined at line 154:

snippedMarker = "[snipped tool result — %s (%d bytes) archive=%s]"

Head/Tail Preservation Strategy

The actual truncation applies a snipStrategy that preserves critical context from both ends of the output. The strategy uses character limits derived from the tool's SnipHint metadata or falls back to defaults (defaultReadOnlySnip for read-only tools, defaultSideEffectingSnip for side-effecting tools).

The resulting placeholder contains:

• Tool name and original byte count.
• Archive reference for full data retrieval.
• Head and tail character counts preserved for reasoning context.

Example output format:

[snipped tool result — my_tool (1234 bytes) archive=/tmp/… head=80 tail=12 …]

Integration with Agent Compaction Workflow

Validation Against CompactRatio

In internal/agent/agent.go at line 1176, the agent validates that ToolResultSnipRatio remains below CompactRatio. This constraint ensures the snip threshold always precedes general compaction, maintaining distinct phases for tool-specific truncation versus full history summarization.

Execution Order

The pruning operates as a pre-compaction optimization:

1. Token count enters the [snip, high) range.
2. SnipStaleToolResults() truncates stale tool outputs into placeholders.
3. The reduced prompt proceeds to normal compaction at the soft threshold.
4. If tokens later exceed high, full compaction (or a new request) occurs.

This staged approach ensures expensive tool outputs compress early, preventing emergency context window exhaustion while preserving the minimal necessary context for agent reasoning.

Configuring tool_result_snip_ratio in Practice

Customizing Agent Options

Configure the ratio during agent initialization to control pruning aggressiveness:

opts := reasonix.AgentOptions{
    ContextWindow:       20000,
    CompactRatio:        0.85,
    ToolResultSnipRatio: 0.5, // Earlier snipping than default 0.6
}
agent, _ := reasonix.NewAgent(opts)

With this configuration, snipping begins when PromptTokens reaches approximately 10,000 tokens (50% of the 20,000 token window), compressing tool outputs before the soft compaction trigger at 17,000 tokens.

Examining Snipped Session Output

Inspect session snapshots to verify snipping occurred:

fmt.Println(sess.Snapshot()[3].Content)
// Output:
// [snipped tool result — my_custom_reader (4123 bytes) archive=/tmp/… head=80 tail=12 …]

Summary

• tool_result_snip_ratio defaults to 0.6 and defines the context window percentage at which stale tool output truncation begins, calculated as int(float64(contextWindow) * toolResultSnipRatio) in internal/agent/compact.go.
• Snipping triggers in the [snip, high) token range, executing before full compaction to preemptively reduce payload size.
• The SnipStaleToolResults() function in internal/agent/prune.go replaces full tool results with compact placeholders preserving configurable head/tail context.
• The parameter is validated in internal/agent/agent.go to ensure it remains below compactRatio, guaranteeing tool-specific pruning precedes general compaction.
• Configuration occurs via AgentOptions or TOML config files defined in internal/config/config.go.

Frequently Asked Questions

What is the default value of tool_result_snip_ratio in DeepSeek-Reasonix?

The default value is 0.6 (60% of the context window), defined as defaultToolResultSnipRatio in internal/agent/compact.go. This means stale tool results begin snipping when token usage reaches 60% of the total context window capacity, well before the general compaction threshold.

How does tool_result_snip_ratio differ from compactRatio?

While compactRatio (typically 0.85) initiates general soft compaction of the entire conversation history, tool_result_snipRatio specifically targets stale tool outputs for truncation at a lower threshold. According to internal/agent/agent.go, the snip ratio is strictly validated to remain below the compact ratio, ensuring tool-specific pruning occurs as an early optimization before general compaction begins.

What happens to tool data after it gets snipped?

Snipped tool results are replaced with placeholders containing the tool name, original byte count, and archive path. The actual content moves to a temporary archive, while the placeholder retains configurable head and tail character fragments (typically 80 and 12 characters respectively) to preserve reasoning context without consuming full token bandwidth.

Can I adjust the amount of content preserved in snipped results?

Yes. While the tool_result_snip_ratio controls when snipping occurs, the amount of preserved content depends on the tool's SnipHint metadata or system defaults (defaultReadOnlySnip and defaultSideEffectingSnip). Tools can specify custom head/tail character limits to ensure critical output sections remain visible to the LLM even after truncation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}