tools-only Context Window Optimization Rules
Rules for keeping agent context windows efficient. These apply when creating or modifying agent definitions, skills, and instruction files.
Agent Definition Rules
| Rule | Limit | Rationale |
|---|---|---|
| Tool list size | ≤ 30 tools | Each tool adds ~75 tokens to prompt |
| Agent body length | ≤ 300 lines | Body is always in context |
| Inline template size | ≤ 50 lines | Move larger templates to skills |
| Handoff count | ≤ 8 handoffs | Each adds ~40 tokens |
| Skill references in body | ≤ 5 "Read" lines | Progressive load, not bulk load |
Instruction File Rules
| Rule | Limit | Rationale |
|---|---|---|
| File size | ≤ 150 lines | Split into skill references/ |
applyTo specificity |
Narrow globs | **/*.ts not ** when possible |
Avoid applyTo: "**" |
Exceptional only | Loads for every single file match |
Good vs Bad applyTo
# Good: Loads only for TypeScript files
applyTo: "**/*.ts, **/*.tsx"
# Good: Loads only for Bicep
applyTo: "**/*.bicep"
# Bad: Loads for every file in the workspace
applyTo: "**"
# Only acceptable for truly universal rules (comments, golden principles)
Skill Rules
| Rule | Limit | Rationale |
|---|---|---|
| SKILL.md body | ≤ 500 lines | Per skill spec |
| Heavy content | → references/ |
Level 3: loaded only when needed |
| Prerequisites section | Required | Declare deps, don't surprise agent |
Hand-Off Decision Framework
Introduce a subagent hand-off when ANY of these conditions are true:
- Tool-heavy phase: Agent makes > 5 tool calls in sequence for one subtask
- Domain shift: Agent transitions between distinct domains (infra → app → docs)
- Context accumulation: Estimated context > 60% of model limit
- Latency signal: Turn latency exceeds 15s consistently
- Isolated validation: Task produces a structured PASS/FAIL result
Context Budget Template
When designing a new agent, budget the context:
Model limit: 200,000 tokens (Opus)
─ System overhead: -2,000 tokens
─ Tool schemas (25): -1,875 tokens
─ Agent body (200 ln): -1,500 tokens
─ Instructions (5): -3,000 tokens
─ Skill (1 SKILL.md): -2,000 tokens
─ Output headroom: -20,000 tokens
────────────────────────────────────
Available for conversation: ~169,625 tokens
Per-turn budget: ~169,625 / 20 turns = ~8,481 tokens/turn average
Adjust per model. GPT-5.3-Codex has 128K, so budget is tighter.
Anti-Patterns
| Pattern | Fix |
|---|---|
| "Read ALL skills before starting" | Read only the 2-3 needed skills |
| Large JSON embedded in agent body | Move to references/ or external file |
| Repeating instructions across agents | Single instruction file + applyTo glob |
| Reading entire files when grep works | Use grep_search for targeted extraction |
| No hand-offs in 30+ turn sessions | Split at logical boundaries with subagents |