What you will be able to do
- Explain why raw tool outputs stuck deep in a message history keep using context and tokens on every later turn
- Sort the tool outputs in a long transcript into clearing candidates and items to keep, using consumption, supersession and re-fetchability
- Clear an output safely by pulling out the facts that still matter first, and tell clearing apart from compaction, starting a new chat and removing tool definitions
Key concept
Tool output clearing — When the context window is nearly full, you remove the raw payload of a tool result the agent has already used. The facts, decisions and recent working state the task still needs stay in place. You clear the bulky evidence, not the conclusions the agent drew from it.
1.Why a deep history runs out of room
An agent's working state for one interaction is its transcript: user messages, the model's replies, every tool call and every tool result, in order. A single-agent system loops. It calls a tool, adds the output to the conversation, reasons over it, and often calls another tool. Each loop makes the transcript longer, and tool results are usually the largest items in it. A message from the model might be a few hundred tokens. A SQL result set, a retrieved document, a file listing or the stdout of a code-interpreter run can be many thousands.
The model has no memory of earlier turns outside what it is sent. So the full transcript goes back to the model on every turn. A large result returned at turn 3 is paid for again at turns 4, 5 and 20, even if the agent finished with it long ago. Databricks describes this cost pattern for Genie Code: the later a message comes in a chat, the more it costs, because the context it carries keeps growing. As the window fills, two problems arrive together. Cost and latency rise on every turn, and the context that matters is buried under stale payloads.
Checkpoint 1 of 7· Check yourself
An agent pulled a 40,000-token query result at turn 3 and summarized it at turn 4. It is now on turn 20 and the result has not been referenced since. Why does that result still count against the budget?
Context is resent on every turn, so anything left in the transcript costs tokens on every later turn, whether or not the agent still needs it.
“Each turn re-sends the whole chat's context to the model, and an agentic task runs several turns to plan, act, and check its work.”Source: docs.databricks.com
2.Which raw outputs are clearing candidates
Age alone doesn't make an item a candidate. Ask four questions of each raw tool output. First, has it been consumed? The agent has already pulled what it needed and written the conclusion into its own reasoning or reply. Second, has it been superseded? A later call returned fresher or corrected data, or the call failed and a retry succeeded. Third, can it be re-fetched? A deterministic query or a document lookup can be run again if needed. Fourth, is it large compared with the information it still adds? An output that passes these tests is a strong clearing candidate.
Some things are not candidates even when they are old: the user's instructions and constraints, decisions the agent or user committed to, and any output whose facts the agent hasn't yet written down anywhere else. The most recent tool results are also not candidates, because the agent is probably still reasoning over them. Tool results with side effects need care too. The record that a refund was issued or a label was generated must survive in some form, or the agent may try the action again. Shrinking such a result to a one-line receipt is fine. Deleting every trace of it is not.
Checkpoint 2 of 7· Exam question
An agent invoked a Unity Catalog function that returned a 50,000-row raw query result. The agent has already extracted the three relevant rows and written a summary of its findings into its response earlier in the conversation. The context window is now approaching capacity. Which item in the message history is the best candidate for clearing?
Correct answer: A — The raw 50,000-row tool output, since its findings are already summarized in the response
- A. Correct. The raw output's useful content has already been extracted and preserved as a summary elsewhere in the context, so keeping the full 50,000-row payload adds token cost without adding retrievable information.
- B. Incorrect. The system prompt anchors the agent's role, tone, and constraints for the entire session; clearing it would degrade behavior on every subsequent turn.
- C. Incorrect. The most recent user question is still active context the agent needs to keep working on the current turn; it has not been superseded by anything.
- D. Incorrect. Tool schemas are needed for the agent to correctly invoke the tool again later and are typically small and reused, not a meaningful source of context bloat.
Checkpoint 3 of 7· Check yourself
To free space quickly, a teammate proposes dropping every tool result in the history, including the ones from the last two turns. What is the main risk?
Removing context without selection cuts out material the agent is still using. The agent keeps producing answers, but they get worse. Clearing has to be selective.
“quality may be reduced if important context is filtered out”Source: docs.databricks.com
3.Clear safely: distill first, then drop the payload
Clearing is safe only if what the task still needs survives the clearing. The usual pattern has two steps. First, make sure the useful content is written somewhere else: in the agent's own reply, in a short note that replaces the raw output, or, for facts that matter beyond this conversation, in long-term memory. Then replace the raw payload with a small placeholder that names the tool and the call, so the model knows the call happened and can run it again if it needs the detail. Databricks describes the same order of steps for sessions and memory: pull the durable facts out of a growing session first, and clear the session afterwards.
Checkpoint 4 of 7· Put it in order
Put these steps in the order Databricks describes for keeping what matters from a growing session.
- 1.The agent or application distills the durable facts out of it
- 2.The session is cleared or ages out while the memory persists
- 3.Those facts are written to memory
- 4.The session accumulates messages, tool calls and results
Facts are pulled out before anything is cleared, so clearing the transcript never throws away knowledge the agent still needs.
“As a session accumulates, an agent (or your application) distills the durable facts out of it and writes them to memory.”Source: docs.databricks.com
Who makes the clearing decision? Managed agent sessions store items as opaque values and give you operations such as popping the last item, clearing a session's items, or forking a conversation. They don't decide which tool output is stale. Your agent code or your framework's context-management logic makes that call. Clearing is also one of several tools and should be kept apart from the others. Compaction summarizes older turns. A new chat clears everything. Disabling unused MCP servers removes tool definitions, not tool outputs. Targeted output clearing sits between compaction and a new chat: it keeps the thread and removes only the bulky evidence.
Checkpoint 5 of 7· Exam question
While completing a task, an agent's MCP tool call failed with a transient network error. The agent retried, and the second call succeeded, returning the data it needed, which it then used in its next step. The failed call's error output still sits in the message history and the context window is nearly full. Which output should be cleared first?
Correct answer: A — The failed first call's error output, since the retry already produced the needed data
- A. Correct. Once a retry succeeds, the earlier failed attempt's error output is superseded and carries no information the agent still needs; it is a prime clearing candidate.
- B. Incorrect. Although this output was already consumed, it is the record of the data the agent actually acted on and is more useful to retain than a stale error from a failed retry.
- C. Incorrect. The original task instruction still frames what the agent is trying to accomplish and should stay available.
- D. Incorrect. A not-yet-executed plan is forward-looking and still needed to guide the agent's next action, so it should not be cleared.
Checkpoint 6 of 7· Check yourself
Which statement about context reduction in Genie Code matches the Databricks guidance?
Automatic compaction cuts context down but doesn't reset it. Only a new chat gives a fully empty window. Disabling MCP servers affects tool definitions, not results already in the transcript.
“Genie Code automatically summarizes, compacts, and truncates long context, but only a new chat clears it completely.”Source: docs.databricks.com
4.Worked evaluation: a support agent's long history
Take the call-center agent from the Databricks design-patterns page. A customer asks to return their last order. The agent queries the order database, reads the return-policy document, checks the return window, starts the return and generates a shipping label. Then the customer keeps going: a second order, a billing question, a change of address. By turn 25 the window is nearly full. The history holds the full order-query result, the full policy document, a failed lookup with a mistyped order ID followed by a successful retry, the label-generation response, and the latest billing lookup.
Clear: the full order-query rows, since the relevant order and its date are already in the agent's reasoning and the query can be re-run. Clear the full policy document once the return-window verdict is recorded; it can be retrieved again. Clear the failed lookup, which the retry superseded. Shrink the label-generation response to a one-line receipt (return started, label issued) so the agent doesn't repeat the action. Keep: the latest billing lookup, which the current question still needs, and the customer's own messages.
The reasoning behind each choice is the same four tests from earlier: consumed, superseded, re-fetchable, and large compared with what it still adds. Before clearing anything, the agent checks whether the conclusion survives somewhere else. Clearing also doesn't erase the evidence for debugging. If the agent is traced with MLflow, the trace records each tool invocation as a span, so you can still inspect what a tool returned after it has left the live context.
Checkpoint 7 of 7· Exam question
An agent is working through a multi-part data-cleaning task. It first called a tool to fetch a table's schema, used that schema to write and run a cleaning query, and confirmed the query executed successfully. The agent has now moved on to an unrelated formatting sub-task for a different table and will not need the earlier schema again. The context window is close to its limit. Which raw tool output is the strongest candidate for clearing?
Correct answer: A — The schema tool output from the completed cleaning sub-task, since it is no longer needed
- A. Correct. The schema was only relevant to the finished cleaning sub-task; with that sub-task closed and no dependency from the new sub-task, it is safe to clear.
- B. Incorrect. A brief success confirmation is cheap to retain and useful as a record of completed work; it is not the item consuming the most unnecessary context.
- C. Incorrect. Instructions for the sub-task currently in progress are actively needed and should not be cleared.
- D. Incorrect. This schema is being actively used for the agent's current formatting work, so it must stay in context.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Clear the oldest messages first. Age is what makes something a candidate.Why is that wrong?
Being consumed or superseded makes an output a candidate, not age. Old user instructions and unrecorded facts must stay, and removing context the agent still needs lowers quality.
Covered in Which raw outputs are clearing candidates
2.Drop the raw output right away and let the agent remember what was in it.Why is that wrong?
The model only knows what is in the context it is sent. The facts that still matter must be distilled and written down first; only then is the raw payload cleared.
Covered in Clear safely: distill first, then drop the payload
3.Disabling unused MCP servers clears the large tool results that are filling the history.Why is that wrong?
Disabling servers removes their tool definitions from context. Results already returned stay in the transcript until they are cleared or compacted.
Covered in Clear safely: distill first, then drop the payload
4.Once a tool output is cleared from context, there is no longer any record of what the tool returned.Why is that wrong?
Clearing removes the output from the live context only. MLflow traces still record each tool invocation for debugging, and re-fetchable outputs can be requested again.
Covered in Worked evaluation: a support agent's long history
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“the twentieth message in a chat costs more than the first”
↩︎ Why a deep history runs out of room“restating table names or earlier results in each prompt adds tokens without adding information”
↩︎ Which raw outputs are clearing candidates“Each connected MCP server adds its tools to what Genie Code carries in context.”
↩︎ Exam trap 3“Each turn re-sends the whole chat's context to the model, and an agentic task runs several turns to plan, act, and check its work.”
↩︎ Checkpoint“Genie Code automatically summarizes, compacts, and truncates long context, but only a new chat clears it completely.”
↩︎ Checkpoint - 2.
“Integrate tool outputs into the conversation.”
↩︎ Why a deep history runs out of room“The agent queries the order database to retrieve the relevant order and references a policy document.”
↩︎ Worked evaluation: a support agent's long history - 3.
“quality may be reduced if important context is filtered out”
↩︎ Which raw outputs are clearing candidates“quality may be reduced if important context is filtered out”
↩︎ Exam trap 1 - 4.
“The session is later cleared or ages out; the memory persists.”
↩︎ Clear safely: distill first, then drop the payload“Most commonly this is the conversation history (the ordered transcript of messages, tool calls, and results)”
↩︎ Key concept“As a session accumulates, an agent (or your application) distills the durable facts out of it and writes them to memory.”
↩︎ Exam trap 2“As a session accumulates, an agent (or your application) distills the durable facts out of it and writes them to memory.”
↩︎ Checkpoint - 5.
“The clients also support removing the most recent item, clearing a session's items, and forking a conversation into an independent copy”
↩︎ Clear safely: distill first, then drop the payload - 6.https://www.databricks.com/blog/ai-harnessSecondary source
“As conversations grow longer, the harness decides what stays active and what gets summarized, a process known as context compaction.”
↩︎ Clear safely: distill first, then drop the payload - 7.
“every intermediate step (LLM calls, retriever lookups, tool invocations)”
↩︎ Worked evaluation: a support agent's long history“every intermediate step (LLM calls, retriever lookups, tool invocations)”
↩︎ Exam trap 4