Grok Build · Context Capacity

Estimation, Percentage, and Strict Thresholds

xai-token-estimation provides shared arithmetic primitives. It offers both a local rough estimate via bytes/4 and usage-rate plus threshold checks based on caller-supplied used and total values.

Lesson Objective Distinguish between local estimation and server-side usage observation; understand usage_percentage, exceeds_threshold, and exceeds_threshold_with_headroom; and correctly interpret the boundary behavior at 85% where the equals sign triggers.
Core Visual · 85% Boundary
context_window = 1,000 85% = 850 01,000 used = 849false used = 850true — equals triggers
Threshold uses integer cross-multiplication: used × 100 >= window × percent.
Three Core Functions
usage_percentage

Returns 0 when total == 0; otherwise calculates the percentage and caps the result at 100.

(used / total × 100).min(100)
exceeds_threshold

Uses integer saturating multiplication to avoid floating-point rounding that could shift trigger boundaries. The default compaction ratio commonly seen in config is 85.

used × 100 >= window × pct
...with_headroom

Reserves a fixed token margin before the percentage threshold. Subtraction uses saturating_sub; returns false when window is 0.

used × 100 >= window × pct - headroom × 100
Estimated vs. Server-Side Usage

Local Estimation

estimate_tokens(s) divides the UTF-8 byte length by 4. It provides rapid predictions before a request is sent or after tool output is added; the fixed estimate for a single low-resolution image is 765 tokens.

Server-Side Usage Observation

Server-side usage describes the actual metering of a completed request. The percentage functions do not fetch or evaluate the data source — they only process values passed in by the caller. The call chain can use either estimated totals or updated usage at different stages.

Boundary example: exceeds_threshold(850, 1000, 85) is true; 849 is false. With a window of 100,000, a threshold of 85%, and headroom of 4,000, the trigger moves earlier to 81,000.
Source Code Evidence
crates/codegen/xai-token-estimation/src/lib.rs · Lines 38–104 (excerpt)
pub fn usage_percentage(used: u64, total: u64) -> f64 {
    if total == 0 { 0.0 }
    else { ((used as f64) / (total as f64) * 100.0).min(100.0) }
}

pub fn exceeds_threshold(
    used: u64, context_window: u64, threshold_percent: u8
) -> bool {
    if context_window == 0 { return false; }
    used.saturating_mul(100)
        >= context_window.saturating_mul(threshold_percent as u64)
}

pub fn exceeds_threshold_with_headroom(
    used: u64, context_window: u64, threshold_percent: u8, headroom: u64,
) -> bool {
    if context_window == 0 { return false; }
    used.saturating_mul(100) >=
        context_window.saturating_mul(threshold_percent as u64)
            .saturating_sub(headroom.saturating_mul(100))
}
Source snapshot note: Based on the local repository grok-build-main, file crates/codegen/xai-token-estimation/src/lib.rs, cross-referenced with the compaction call sites. Verification date: 2026-07-17. The page does not use any fabricated formulas with separate pricing by language or code type.
Classroom Exercise
05

Calculate Two Trigger Points by Hand

The context window is 128,000 and the threshold is 85%. First, find the earliest triggering used value without headroom; then find it with a headroom of 4,000. Keep the equals sign in both answers.

Takeaway: Local bytes/4 estimation serves timely prediction; server-side usage provides observation of completed requests. The shared functions handle unified arithmetic. The 85% boundary uses >= — it becomes true as soon as the threshold is reached — and headroom shifts the trigger point even earlier.