Overview

Why tool results#

In an agent loop, every tool result is resent with every later model call. A 7,000-token test run read at step 3 of a 20-step task is paid for 17 more times, and most of it is passing tests the model never needed.

What the SDK does#

When a tool returns, the SDK decides what the model reads, in four steps:

1. Cleanup, locally and for free: color codes, progress bars, passing tests, repeated log lines, empty JSON fields and HTML markup go. Errors are never removed.
2. Size check: a result that fits its budget reaches the model as is.
3. Relevance: for larger results, the parts that match what the agent is doing are kept within the budget. Each gap says what is missing (… lines 12-240 omitted), and a note counts what was cut (for example status: delivered ×148), so the model rarely needs to ask for more. A result is only cut when that saves at least 1,000 tokens and 30% of it: a smaller cut isn't worth the extra model call an expand would cost.
4. Nothing lost: the model gets an expand tool to fetch any omitted part back, by asking for what it needs.

Your application still receives every tool's full output. Only the model's view changes.

Install#

npm install contextwaise

Both packages are named contextwaise and make the same decisions. They are published on npm and PyPI at launch; early-access teams get them first.

Requires Node.js 20 or later. The Vercel AI SDK adapter needs ai version 7 or later.

Connect to your dashboard#

With an API key, relevance is judged by the Contextwaise API and every result appears in your dashboard under Requests → Contextwaise SDK. Results still over budget after cleanup are sent in sections to be scored, and are not stored: the dashboard keeps tool names and sizes only.

CONTEXTWAISE_API_KEY=sw_live_...
CONTEXTWAISE_URL=https://app.contextwaise.com

Use the same keys as the API. Until then, the SDK works without a key: it cleans every tool result locally and sends it whole.

Without a key, or when the API is down#

Relevance is only ever judged by the Contextwaise API. Without a key, only the free local cleanup runs: noise is removed, and the model reads everything else in full. Nothing leaves your process.

The same happens if the API is slow or unreachable: the SDK never guesses which parts matter, so nothing is cut and your agent keeps running. It tries the API again 30 seconds later.

Next steps#

Building without an agent loop? The API covers RAG, search results and memory.