The Morning My Table Ended in "… 2,847 more rows" — Separating Render Caps from Token Cost in Tool Output

Rebuild the full-table tool into three layers

With an estimate in hand, go back to the return value. The shape I use has three layers: a summary, a top-N table, and a pointer.

Before the refactor, my tool returned everything.

# Before: turn the query result into a markdown table and ship it
def daily_breakdown(date: str) -> str:
    rows = db.query(
        "SELECT day, category, hits, ratio, delta, note "
        "FROM daily_stats WHERE day = ? ORDER BY hits DESC",
        (date,),
    )
    lines = ["| day | category | hits | ratio | delta | note |",
             "|---|---|---|---|---|---|"]
    for r in rows:
        lines.append(f"| {r.day} | {r.category} | {r.hits} | {r.ratio} | {r.delta} | {r.note} |")
    return "\n".join(lines)  # all 3,047 rows go straight into context

At the time it felt right. Hand over everything and let the model pick out what it needs. What actually happened: I paid for 3,042 rows on every turn so the model could reach the five it cared about.

# After: return a summary, a top-N table, and a pointer to the full result
import json
from pathlib import Path
 
TOP_N = 20
ARTIFACT_DIR = Path("/var/run/agent-artifacts")
 
 
def daily_breakdown(date: str) -> str:
    rows = db.query(
        "SELECT day, category, hits, ratio, delta, note "
        "FROM daily_stats WHERE day = ? ORDER BY hits DESC",
        (date,),
    )
 
    # (1) Summary: the numbers that decide "fine or not" without reading rows
    total = sum(r.hits for r in rows)
    categories = len({r.category for r in rows})
    worst = min(rows, key=lambda r: r.delta) if rows else None
 
    # (2) Pointer: always persist the full set, hand over only the path
    ARTIFACT_DIR.mkdir(parents=True, exist_ok=True)
    artifact = ARTIFACT_DIR / f"daily_breakdown_{date}.json"
    artifact.write_text(
        json.dumps([r._asdict() for r in rows], ensure_ascii=False),
        encoding="utf-8",
    )
 
    # (3) Top-N: the slice a human and the model can both act on
    head = ["| category | hits | ratio | delta |", "|---|---|---|---|"]
    for r in rows[:TOP_N]:
        head.append(f"| {r.category} | {r.hits} | {r.ratio} | {r.delta} |")
 
    summary = (
        f"date={date} rows={len(rows)} total_hits={total} categories={categories}\n"
        f"largest_drop={worst.category if worst else 'n/a'} "
        f"delta={worst.delta if worst else 'n/a'}\n"
        f"full_result={artifact} (JSON, {len(rows)} rows)\n"
    )
    return summary + "\n" + "\n".join(head) + f"\n\n… {max(0, len(rows) - TOP_N)} more rows in {artifact.name}"
 
    # Expected head of the return value:
    # date=2026-07-16 rows=3047 total_hits=184213 categories=42
    # largest_drop=wallpaper-hd delta=-18.4
    # full_result=/var/run/agent-artifacts/daily_breakdown_2026-07-16.json (JSON, 3047 rows)

Why is TOP_N twenty and not two hundred? Because a render cap is not a budget. It says "nothing beyond this gets drawn." It does not say "everything up to here is fine to send."

I landed on twenty because twenty is roughly what I actually read during review. Past that I was opening the file and filtering with jq anyway. So I may as well hand over the file from the start.

Writing the path into full_result means the model fetches the rest with Read or bash only when it needs to. Cases that need every row still exist. They just do not need every row parked in context on every turn.

Read the 200-row cap as a constraint on review, not just on tools

That number shapes how humans read output, too.

When you read an unattended job's log after the fact and the table is truncated, you are implicitly assuming the truncated part holds nothing you need. Which means anything you need for a decision has to live inside the first 200 rows — realistically, inside the first few lines.

So I moved my summary above the table. Three lines: date=... rows=... total_hits=.... Read those and you know whether the night went well. The table is where you look only after the answer is "no."

Back when the order was reversed, I was scanning tables from the top looking for anomalies. Could I spot an anomaly in 3,000 rows? Honestly, I was not spotting them.

When you genuinely need every row, drop the table format

Some work really does need all of it in front of the model: classification, near-duplicate detection, outlier sweeps.

For those, my answer is not a bigger table. It is splitting the work across turns.

# When the model must judge every row: chunk it instead of one giant turn
CHUNK = 200  # sized for one good judgement, not to match the render cap
 
def classify_all(rows: list, client) -> list:
    results = []
    for i in range(0, len(rows), CHUNK):
        chunk = rows[i : i + CHUNK]
        payload = "\n".join(f"{r.category}\t{r.hits}\t{r.delta}" for r in chunk)
        # TSV visibly cuts per-row bytes compared to a markdown table
        resp = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=2048,
            messages=[{
                "role": "user",
                "content": f"Classify each row as anomaly or normal. Return a JSON array.\n{payload}",
            }],
        )
        results.extend(json.loads(resp.content[0].text))
    return results

The switch from markdown to TSV is not cosmetic. Pipes and padding cost real bytes — around 20 per row for six columns, which is roughly 60 KB of pure table borders across 3,047 rows. There is no reason to spend that on intermediate data no human will read.

On splitting tool results themselves, When a Tool Result Is Too Big and Melts Your Context Window: Designing Cursor-Based Pagination covers the cursor approach and Compressing Tool Results in Claude Agents — Aggregating Large Responses Without Bloating Context covers compression. This piece sits one step earlier: deciding how many rows belong on screen at all.

Where I tripped

Reading truncation as context savings. The easiest mistake, and I made it for a few minutes. Truncation is a rendering layer. One trip through count_tokens cures it instantly.

Returning 200 rows because the cap is 200. A cap is not permission. Size it from what you actually read during review. For me that was twenty.

Persisting the file and forgetting to return the path. Do that and the model never learns the full set exists, so it answers from what it can see. Summary and pointer ship together or not at all.

Never cleaning up artifacts. Writing 225 KB every day adds up quietly in long-running sessions. Your Overnight Session Wakes Up at 3GB — Four Places Memory Piles Up, and How to Tell Them Apart covers what accumulates over a long night. I date-stamp the names and expire them after seven days.

Hitting the read-side cap instead. Once you hand over artifacts, the truncation moves to the reader. When Claude Code's Read Tool Silently Truncates Large Files — offset/limit Patterns and When to Reach for Bash covers the offset and limit patterns.

One thing to try today

Pick the largest table one of your MCP tools returns, dump it to a file, and run it through count_tokens. That is the whole exercise.

Once the 200 rows you were looking at sit next to the number you are actually paying, the refactor writes itself. Seeing my own ratio is what got me into the habit of putting the summary above the table.

Faster rendering and right-sized payloads are two different problems. Version 2.1.209 solved the first one for us. The second is still sitting in our own designs.