1# Context Components: Technical Reference
2 
3This document provides detailed technical reference for each context component in agent systems.
4 
5## System Prompt Engineering
6 
7### Section Structure
8 
9Organize system prompts into distinct sections with clear boundaries. A recommended structure:
10 
11```
12<BACKGROUND_INFORMATION>
13Context about the domain, user preferences, or project-specific details
14</BACKGROUND_INFORMATION>
15 
16<INSTRUCTIONS>
17Core behavioral guidelines and task instructions
18</INSTRUCTIONS>
19 
20<TOOL_GUIDANCE>
21When and how to use available tools
22</TOOL_GUIDANCE>
23 
24<OUTPUT_DESCRIPTION>
25Expected output format and quality standards
26</OUTPUT_DESCRIPTION>
27```
28 
29This structure allows agents to locate relevant information quickly and enables selective context loading in advanced implementations.
30 
31### Altitude Calibration
32 
33The "altitude" of instructions refers to the level of abstraction. Consider these examples:
34 
35**Too Low (Brittle):**
36```
37If the user asks about pricing, check the pricing table in docs/pricing.md.
38If the table shows USD, convert to EUR using the exchange rate in
39config/exchange_rates.json. If the user is in the EU, add VAT at the
40applicable rate from config/vat_rates.json. Format the response with
41the currency symbol, two decimal places, and a note about VAT.
42```
43 
44**Too High (Vague):**
45```
46Help users with pricing questions. Be helpful and accurate.
47```
48 
49**Optimal (Heuristic-Driven):**
50```
51For pricing inquiries:
521. Retrieve current rates from docs/pricing.md
532. Apply user location adjustments (see config/location_defaults.json)
543. Format with appropriate currency and tax considerations
55 
56Prefer exact figures over estimates. When rates are unavailable,
57say so explicitly rather than projecting.
58```
59 
60The optimal altitude provides clear steps while allowing flexibility in execution.
61 
62## Tool Definition Specification
63 
64### Schema Structure
65 
66Each tool should define:
67 
68```python
69{
70    "name": "tool_function_name",
71    "description": "Clear description of what the tool does and when to use it",
72    "parameters": {
73        "type": "object",
74        "properties": {
75            "param_name": {
76                "type": "string",
77                "description": "What this parameter controls",
78                "default": "reasonable_default_value"
79            }
80        },
81        "required": ["param_name"]
82    },
83    "returns": {
84        "type": "object",
85        "description": "What the tool returns and its structure"
86    }
87}
88```
89 
90### Description Engineering
91 
92Tool descriptions should answer: what the tool does, when to use it, and what it produces. Include usage context, examples, and edge cases.
93 
94**Weak Description:**
95```
96Search the database for customer information.
97```
98 
99**Strong Description:**
100```
101Retrieve customer information by ID or email.
102 
103Use when:
104- User asks about a specific customer's details, history, or status
105- User provides a customer identifier and needs related information
106 
107Returns customer object with:
108- Basic info (name, email, account status)
109- Order history summary
110- Support ticket count
111 
112Returns null if customer not found. Returns error if database unreachable.
113```
114 
115## Retrieved Document Management
116 
117### Identifier Design
118 
119Design identifiers that convey meaning and enable efficient retrieval:
120 
121**Poor identifiers:**
122- `data/file1.json`
123- `ref/ref.md`
124- `2024/q3/report`
125 
126**Strong identifiers:**
127- `customer_pricing_rates.json`
128- `engineering_onboarding_checklist.md`
129- `2024_q3_revenue_report.pdf`
130 
131Strong identifiers allow agents to locate relevant files even without search tools.
132 
133### Document Chunking Strategy
134 
135For large documents, chunk strategically to preserve semantic coherence:
136 
137```python
138# Pseudocode for semantic chunking
139def chunk_document(content):
140    """Split document at natural semantic boundaries."""
141    boundaries = find_section_headers(content)
142    boundaries += find_paragraph_breaks(content)
143    boundaries += find_logical_breaks(content)
144    
145    chunks = []
146    for i in range(len(boundaries) - 1):
147        chunk = content[boundaries[i]:boundaries[i+1]]
148        if len(chunk) > MIN_CHUNK_SIZE and len(chunk) < MAX_CHUNK_SIZE:
149            chunks.append(chunk)
150    
151    return chunks
152```
153 
154Avoid arbitrary character limits that split mid-sentence or mid-concept.
155 
156## Message History Management
157 
158### Turn Representation
159 
160Structure message history to preserve key information:
161 
162```python
163{
164    "role": "user" | "assistant" | "tool",
165    "content": "message text",
166    "reasoning": "optional chain-of-thought",
167    "tool_calls": [list if role="assistant"],
168    "tool_output": "output if role="tool"",
169    "summary": "compact summary if conversation is long"
170}
171```
172 
173### Summary Injection Pattern
174 
175For long conversations, inject summaries at intervals:
176 
177```python
178def inject_summaries(messages, summary_interval=20):
179    """Inject summaries at regular intervals to preserve context."""
180    summarized = []
181    for i, msg in enumerate(messages):
182        summarized.append(msg)
183        if i > 0 and i % summary_interval == 0:
184            summary = generate_summary(summarized[-summary_interval:])
185            summarized.append({
186                "role": "system",
187                "content": f"Conversation summary: {summary}",
188                "is_summary": True
189            })
190    return summarized
191```
192 
193## Tool Output Optimization
194 
195### Response Formats
196 
197Provide response format options to control token usage:
198 
199```python
200def get_customer_response_format():
201    return {
202        "format": "concise | detailed",
203        "fields": ["id", "name", "email", "status", "history_summary"]
204    }
205```
206 
207The concise format returns essential fields only; detailed returns complete objects.
208 
209### Observation Masking
210 
211For verbose tool outputs, consider masking patterns:
212 
213```python
214def mask_observation(output, max_length=500):
215    """Replace long observations with compact references."""
216    if len(output) <= max_length:
217        return output
218    
219    reference_id = store_observation(output)
220    return f"[Previous observation elided. Full content stored at reference {reference_id}]"
221```
222 
223This preserves information access while reducing token usage.
224 
225## Context Budget Estimation
226 
227### Token Counting Approximation
228 
229For planning purposes, estimate tokens at approximately 4 characters per token for English text:
230 
231```
2321000 words ≈ 7500 characters ≈ 1800-2000 tokens
233```
234 
235This is a rough approximation; actual tokenization varies by model and content type.
236 
237### Context Budget Allocation
238 
239Allocate context budget across components:
240 
241| Component | Typical Range | Notes |
242|-----------|---------------|-------|
243| System prompt | 500-2000 tokens | Stable across session |
244| Tool definitions | 100-500 per tool | Grows with tool count |
245| Retrieved documents | Variable | Often largest consumer |
246| Message history | Variable | Grows with conversation |
247| Tool outputs | Variable | Can dominate context |
248 
249Monitor actual usage during development to establish baseline allocations.
250 
251## Progressive Disclosure Implementation
252 
253### Skill Activation Pattern
254 
255```python
256def activate_skill_context(skill_name, task_description):
257    """Load skill context when task matches skill description."""
258    skill_metadata = load_all_skill_metadata()
259    
260    relevant_skills = []
261    for skill in skill_metadata:
262        if skill_matches_task(skill, task_description):
263            relevant_skills.append(skill)
264    
265    # Load full content only for most relevant skills
266    for skill in relevant_skills[:MAX_CONCURRENT_SKILLS]:
267        skill_context = load_skill_content(skill)
268        inject_into_context(skill_context)
269```
270 
271### Reference Loading Pattern
272 
273```python
274def get_reference(file_reference):
275    """Load reference file only when explicitly needed."""
276    if not file_reference.is_loaded:
277        file_reference.content = read_file(file_reference.path)
278        file_reference.is_loaded = True
279    return file_reference.content
280```
281 
282This pattern ensures files are loaded once and cached for the session.
283 
284