[FEATURE] Large Content Aliasing for Tool Results

[dbschmigelski]

Priority: Low

Problem Statement

When tools return large content (documents, images, long API responses), the entire result is inlined into the context window. This consumes context capacity and can push agents into overflow. Users frequently ask "the returned item is large, what do I do?"

Proposed Solution

Introduce an OversizedToolResult subclass that stores a representation of large results with the ability to access the full content on demand. Rather than inlining large content, alias it so the agent can navigate into it when needed.

class OversizedToolResult(ToolResult):
    """ToolResult storing representation of large result and ability to access as needed."""
    ...

The agent sees a summary/preview in context and can explicitly request the full content when relevant, keeping the context window clean by default.

Use Case

• Tools returning large API responses, file contents, or database query results
• Document and image handling without consuming full context window
• Complements the MemGPT-inspired tiered memory approach

Additional Context

Part of the Context Management epic, Track 1: Conversation Context. Builds on #1296 (Large Tool Result Externalization).