| name | agent-context-management |
| description | Manages AI agent context window usage - truncation rules, clear truncation markers, and tools for chunked reading or search. Use when building or modifying agent context, system prompts, user messages, or tools that inject large content into the LLM. |
| metadata | {"author":"caido-community"} |
Agent Context Management
Overview
AI agents operate within a fixed context window. System prompts, user messages, tool outputs, and injected context (HTTP requests, responses, skills, etc.) all consume tokens. Exceeding the limit causes failures or degraded behavior.
Core principle: Truncate when necessary, but never silently. Always make truncation visible and give the agent a path to access full data when needed.
What to Be Careful About
- System prompt: Keep instructions concise. Avoid redundant or verbose sections.
- Context blocks: HTTP requests, responses, learnings, payload blobs, environment variables.
- User messages: Long pasted content or multi-turn history.
- Tool outputs: Large strings returned from tools (responses, binary output, workflow results).
- Skills and agent instructions: Can grow unbounded if many are selected.
Truncation Rules
1. Always Add a Clear Truncation Marker
When truncating, append an explicit marker so the agent knows content was cut:
...[truncated]...
or with metadata:
[...truncated. 45000 characters remaining. Response ID: abc123]
Include:
- That truncation occurred
- How much was omitted (characters/bytes)
- Any identifier needed to fetch more (e.g. response ID, blob ID)
2. Prefer Head + Tail Over Head-Only
For long content, show both start and end so the agent sees structure:
[first N chars]...[truncated]...[last M chars]
This helps with HTTP requests (headers + body tail), JSON, and similar structured data.
3. Truncation Marker Template
const TRUNCATION_MARKER = "\n...[truncated]...\n";
function truncateContextValue(value: string, maxLength: number): string {
if (value.length <= maxLength) return value;
const remaining = maxLength - TRUNCATION_MARKER.length;
const headLength = Math.ceil(remaining / 2);
const tailLength = Math.max(0, remaining - headLength);
return `${value.slice(0, headLength)}${TRUNCATION_MARKER}${value.slice(value.length - tailLength)}`;
}
Provide Access to Full Data
If you truncate, the agent must be able to retrieve the rest. Implement one or more of:
Chunked Reading
Expose a tool that reads a range (offset, limit) of the full content:
RequestRangeRead(offset: number, limit: number) → content, totalLength, truncated
ResponseRangeRead(responseId, startIndex, endIndex) → content, truncated
Document in the system prompt that truncated content can be inspected via these tools.
Search
For large responses or logs, provide search so the agent can find relevant sections:
ResponseSearch(responseId, pattern) → [{ startIndex, endIndex, context }]
Then use chunked read around the matches.
Blob Storage
For generated content the agent needs to reference later (e.g. large payloads):
PayloadBlobCreate(content) → blobId
Store full content server-side; inject only blobId, length, and a short preview into context. The agent references §§§Blob§blobId§§§ in tool inputs to substitute the full content when needed.
System Prompt Guidance
When truncation is possible, add explicit instructions:
If the visible <current_http_request> appears truncated, use RequestRangeRead with offset and limit to inspect additional request chunks before applying precise raw edits.
For responses:
Responses may be truncated. Use ResponseSearch to find patterns, then ResponseRangeRead with startIndex/endIndex to read specific sections.
Checklist
Source: caido-community/shift — distributed by TomeVault.
