Trim results before they enter context

Learning objective

Trim verbose tool outputs to task-relevant fields before accumulating them in context.

Core idea

A tool can return a correct response that is poorly suited to model context. An order lookup designed for several backend consumers may include warehouse metadata, image variants, and audit detail when a return decision needs only the order, purchased items, paid amount, delivery date, and eligibility evidence.

Anthropic’s tool-design guidance recommends returning high-signal information and prioritizing contextual relevance. The deciding boundary is before the result reaches Claude. Once your application appends a verbose result to replayed history, later requests can keep carrying that same bulk.

See 1.5.2 for general output normalization and hook shape preservation. This lesson applies those mechanisms to context volume: reduce the payload without deleting the facts required to make or verify the next decision.

How it works

Define the fields the decision needs

Start with the tool’s purpose and the downstream action. A return investigation and a delivery investigation can need different views of the same order. Define an explicit result projection for each purpose instead of treating the backend’s complete object as the natural model response.

For a return investigation, a useful view might retain:

These are application-defined fields, not an Anthropic order schema. The exam guide’s example contrasts a lookup with more than forty fields against roughly five relevant fields; those counts illustrate disproportionate context use, not a universal field-count limit.

Retain qualifications that affect interpretation. An unknown delivery date is different from a date outside the return window. An estimated date is different from confirmed delivery. A trimmed response should preserve those differences rather than converting every missing or uncertain value into a reassuring sentence.

Prefer a task-shaped tool response

If you own the tool, implement the projection there. Your backend can retain a full operational record while the tool returns the compact view needed by the agent. This prevents irrelevant data from becoming model context in the first place.

Anthropic’s engineering article gives a response_format enum as an example tool parameter for choosing "concise" or "detailed" responses. This is a parameter you define in your tool, not the Messages API’s native JSON-output configuration. Describe when each view is appropriate in the tool contract, so a follow-up step can request details when it genuinely needs them.

Concise output must still support the workflow. The article notes that technical identifiers can be needed for downstream calls even when a natural-language response is easier to read. Do not remove the order ID because it is less readable than the item name if the next tool requires that ID.

For direct Messages client tools, construct the trimmed payload in the result’s content before appending the user tool_result to messages. Preserve tool_use_id and the required tool-exchange ordering. Set is_error: true when execution produced an error; removing diagnostic clutter must not make failure appear to be success.

Replace output when you cannot change the tool

Both Agent SDKs support PostToolUse hooks. A synchronous callback can return hookSpecificOutput with hookEventName: "PostToolUse" and updatedToolOutput to replace the tool output before Claude sees it. Register the callback under the hooks option and use matcher to target the relevant tool names.

The distinction between replacement and addition is load-bearing. additionalContext adds information alongside a result; it does not remove the verbose original. updatedMCPToolOutput is restricted to MCP tools, while the documented updatedToolOutput field works for any tool in both SDKs. See 1.5.2 for the broader normalization treatment.

Match the replacement to the tool’s output shape. The hooks reference warns that built-in tool replacements with an invalid schema are ignored and the original output is used. For example, trimming a built-in tool to a plain sentence when it expects a structured object can fail to reduce context at all.

PostToolUse also runs after execution. Replacement changes what Claude receives, not actions the tool already performed. It cannot cancel a payment or undo a file write. Likewise, asynchronous hook output cannot modify or inject context after the agent has moved on; use a synchronous callback for this replacement boundary.

Key distinctions and trade-offs

Trimming versus summarizing later: Projection removes irrelevant fields before accumulation. Later summarization spends context on the bulk first and then introduces another lossy transformation.

Projection versus server-side clearing: The Messages API context-editing strategy clear_tool_uses_20250919, configured in context_management.edits, clears older tool results when context exceeds a configured threshold. It clears the oldest first and substitutes placeholder text. This feature is in beta and requires anthropic-beta: context-management-2025-06-27. Clearing manages results that have already accumulated; projection keeps irrelevant fields out from the start.

Replacement versus annotation: updatedToolOutput replaces; additionalContext appends. A concise annotation next to an unchanged large response is not a context-volume fix.

Signal versus smallest payload: The shortest response can omit a required ID, error, or eligibility reason. Optimize for the smallest sufficient result rather than a field count alone.

Concise versus detailed views: A concise view supports the ordinary decision. A detailed view supports a specifically identified follow-up need. Their distinction belongs in the custom tool contract.

Architecture / decision scenario

A support agent makes three order lookups during a return investigation. Each returns a broad backend object, which the application stores unchanged in Messages history. The relevant refund evidence becomes difficult to find among carrier settings, warehouse codes, and image metadata.

Change the owned lookup tool to return a return-focused record with identifiers, item information, amount and currency, delivery evidence, and eligibility reason. Preserve those fields in tool_result.content; retain the call’s tool_use_id. If an eligibility lookup fails, return the failure as an error rather than a normal record with missing fields.

For a shared SDK tool whose implementation cannot change, register a synchronous PostToolUse projection and return updatedToolOutput in the supported shape. Do not return only additionalContext: "Relevant fields follow", because the original bulk would remain available to Claude.

When the customer later asks about a carrier-specific delay, request the detailed or delivery-focused view instead of guessing from fields the return view intentionally omitted. The compact ordinary path reduces accumulation while the explicit follow-up path preserves access to necessary evidence.

Common exam traps

• Trimming only after large responses have entered replayed context.
• Treating threshold-triggered beta tool-result clearing as projection before accumulation.
• Dropping identifiers needed by a later tool or issue-state update.
• Treating the example response_format enum as a built-in API feature.
• Using additionalContext when the requirement is replacement.
• Returning an unsupported output shape and assuming the hook succeeded.
• Stripping failure evidence or expecting a post-execution hook to undo actions.

What to remember

Return a task-shaped payload before it accumulates. Use a custom tool projection or synchronous PostToolUse replacement, preserve required shape and evidence, and request extra detail only when the downstream task needs it.

Knowledge check

References

• Anthropic, Writing effective tools for agents — with agents
• Anthropic, Handle tool calls
• Anthropic, Intercept and control agent behavior with hooks
• Anthropic, Hooks reference
• Anthropic, Claude Certified Architect – Foundations Exam Guide
• Anthropic, Context editing