The Problem It Solves
When an AI coding agent needs to understand a function, the default approach is to read the entire file. A 500-line file consumes roughly 2,000 tokens — even if the answer is in a 3-line signature. Across a debugging session touching 20 files, that’s 40,000+ tokens burned on context gathering alone, most of it noise. The Iris Gate Ladder eliminates this waste by providing four levels of context access, each appropriate for a different class of question. Agents start at the lowest rung and escalate only when the current rung can’t answer the question.The Four Rungs
| Token Cost | Rung | What You Get | Typical Question |
|---|---|---|---|
| ~100 | 1 — Symbol Card | Name, signature, summary, deps, metrics | ”What does this function do?” |
| ~300 | 2 — Skeleton IR | Signatures + control flow, bodies elided | ”What’s the shape of this class?” |
| ~600 | 3 — Hot-Path Excerpt | Lines matching specific identifiers + context | ”Where is this.cache initialized?” |
| ~2,000 | 4 — Raw Code Window | Full source code, policy-gated | ”I need to rewrite this error handler” |
Rung 1: Symbol Cards (sdl.symbol.getCard)
The atom of SDL-MCP. A symbol card is a compact metadata record containing everything an agent needs to understand a symbol without reading its code:
- Identity — name, kind (function/class/interface/etc.), file, line range
- Signature — parameter names and types, return type, generics, overloads
- Summary — 1–2 line semantic description (LLM-generated or extracted)
- Dependencies — what it imports and calls (with confidence-scored resolution)
- Metrics — fan-in (who calls me), fan-out (who I call), 30-day churn, test references
- Architecture — cluster membership (community detection), process participation (call-chain role)
- Versioning — content-addressed ETag for conditional requests
buildSlice do?” “What does handleAuth depend on?” “Is parseConfig exported?” All answered by a card, at ~100 tokens.
Rung 2: Skeleton IR (sdl.code.getSkeleton)
When you need to understand the shape of a file or class without reading every line. Skeletons include all function and method signatures, control flow structures (if, for, while, try/catch), and implementation bodies replaced with /* ... */.
Think of it as an interactive table of contents. You can also filter with exportedOnly: true for large library files.
Rung 3: Hot-Path Excerpt (sdl.code.getHotPath)
When you know what you’re looking for. Provide a list of identifiers — for example, ["errorCode", "retryCount"] — and get back only the lines where they appear, plus a configurable number of context lines above and below. Everything else is skipped.
This is surgically precise: you see exactly the code you need and nothing more.
Rung 4: Raw Code Window (sdl.code.needWindow)
The last resort. Full source code access, but with guardrails:
- Justification required — agents must explain why they need raw code
- Identifier hints — what specific identifiers they expect to find
- Line and token limits — enforced by the policy engine
- Audit logging — every raw access is recorded
- Denial guidance — if denied, the response suggests an alternative (e.g., “try
getHotPathwith these identifiers instead”)
Policy-gated raw access ensures agents prove they actually need full source. Denied requests always include an actionable next-best-action suggestion.
Token Savings in Practice
| Scenario | Reading the File | Using the Ladder | Savings |
|---|---|---|---|
”What does parseConfig accept?” | ~2,000 tokens | ~100 (card) | 20x |
”Show me the structure of AuthService” | ~4,000 tokens | ~300 (skeleton) | 13x |
”Where is this.cache set?” | ~2,000 tokens | ~500 (hot-path) | 4x |
”Debug the retry logic in fetchWithBackoff” | ~2,000 tokens | ~2,000 (window) | 1x (but audited) |
The Escalation Path
Agents navigate the ladder by starting at Rung 1 and climbing only when the current rung cannot answer the question. Each rung is a complete tool call with its own response:Ask the Symbol Card
Call
sdl.symbol.getCard with the symbol’s ID. The card contains signature, summary, dependencies, and metrics — enough to answer most questions about what a symbol does and what it calls.Escalate to Skeleton IR
If the card answers identity and dependencies but you need to understand the structure of the file or class, call
sdl.code.getSkeleton. Bodies are elided — you see the control flow and all signatures without the implementation noise.Escalate to Hot-Path Excerpt
If you need specific lines — where a variable is assigned, where a condition branches — call
sdl.code.getHotPath with the identifiers you’re tracking. Only the matching lines and their context are returned.Request Raw Code Window (Policy-Gated)
Only if you need to read or rewrite the full implementation, call
sdl.code.needWindow. Provide a reason, the identifiers you expect to find, and your expected line count. The policy engine validates the request and either approves it or returns a denial with an alternative suggestion.MCP Tool Mapping
| Rung | MCP Tool | When to Use |
|---|---|---|
| 1 | sdl.symbol.getCard / sdl.symbol.getCards | Understanding what a symbol does, its deps, its metrics |
| 2 | sdl.code.getSkeleton | Understanding the shape of a file or class |
| 3 | sdl.code.getHotPath | Finding where specific identifiers appear |
| 4 | sdl.code.needWindow | Reading or rewriting a full implementation |