Code Access Tools (Iris Gate Ladder)

The code access tools form Rungs 2–4 of the Iris Gate Ladder — SDL-MCP’s controlled escalation path for reading source code. Use them in order: skeleton first, then hot-path, then raw window only when the first two are insufficient.

Token Cost    What the Agent Sees
              ────────────────────────────────────────────────
     ~100     RUNG 1 ▸ Symbol Card (sdl.symbol.getCard)
              Name, signature, summary, dependencies, metrics

     ~300     RUNG 2 ▸ Skeleton IR (sdl.code.getSkeleton)
              Signatures + control flow, bodies replaced with /* ... */

     ~600     RUNG 3 ▸ Hot-Path Excerpt (sdl.code.getHotPath)
              Only lines matching specific identifiers + context

   ~2,000     RUNG 4 ▸ Raw Code Window  ⚠️  Policy-gated
              Full source code, requires justification

Most questions are answered at Rungs 1–2 without ever reading raw code. Always try a Symbol Card (sdl.symbol.getCard) first — it costs ~50–150 tokens versus ~2,000 for a raw file.

sdl.code.getSkeleton

Rung 2. Returns a deterministic “table of contents” for a symbol or file — signatures and control flow structures with implementation bodies elided. Parses the source file and produces a skeleton view that includes function/method signatures, class declarations, and control flow structures (if, for, while, try), but replaces implementation bodies with /* ... */. This lets agents understand the shape of the code without reading every line. Provide exactly one of symbolId or file.

Parameters

repoId

string

required

Repository identifier.

symbolId

string

Symbol to skeletonize. Provide either this or file.

file

string

File path to skeletonize. Provide either this or symbolId.

exportedOnly

boolean

Only include exported symbols. Useful in file mode to reduce noise in large library files.

maxLines

number

Maximum lines to return.

maxTokens

number

Maximum tokens to return.

identifiersToFind

string[]

Highlight specific identifiers in the skeleton. Maximum 50.

skeletonOffset

number

Resume from a previous truncation point (line offset for pagination). Minimum: 0.

Response

skeleton

string

The skeleton IR text with bodies elided.

file

string

File path.

range

object

{startLine, startCol, endLine, endCol}.

estimatedTokens

number

Token count of the skeleton.

originalLines

number

Line count of the original source.

truncated

boolean

Whether the skeleton was truncated.

truncation

object

Truncation details if applicable, including a resume offset.

Examples

{ "repoId": "my-repo", "symbolId": "<symbol-id>" }

sdl.code.getHotPath

Rung 3. Extracts only the lines containing specific identifiers, plus surrounding context lines, from a symbol’s source code. Given a symbol and a list of identifiers to find, scans the source code for occurrences of those identifiers and returns a minimal excerpt containing just those lines plus a configurable number of context lines above and below. Irrelevant code between matches is skipped. This is the most efficient way to answer targeted questions like “where is this.cache initialized?” or “how is errorCode used?”

Parameters

repoId

string

required

Repository identifier.

symbolId

string

required

Symbol to search within.

identifiersToFind

string[]

required

Identifiers to locate in the source. Range: 1–50.

contextLines

number

Lines of context above and below each match. Default: 3. Minimum: 0.

maxLines

number

Maximum total lines to return.

maxTokens

number

Maximum tokens to return.

Response

excerpt

string

The hot-path excerpt text.

file

string

File path.

range

object

{startLine, startCol, endLine, endCol}.

estimatedTokens

number

Token count of the excerpt.

matchedIdentifiers

string[]

Which of the requested identifiers were actually found in the AST.

matchedLineNumbers

number[]

Line numbers where matches occurred.

truncated

boolean

Whether the excerpt was truncated.

Example

{
  "repoId": "my-repo",
  "symbolId": "<symbol-id>",
  "identifiersToFind": ["validate", "token"],
  "contextLines": 3
}

sdl.code.needWindow

Rung 4. Requests raw source code for a symbol. This is the most expensive rung of the Iris Gate Ladder and is policy-gated.

This tool requires justification and is the last resort after trying Symbol Cards (Rung 1), Skeleton IR (Rung 2), and Hot-Path excerpts (Rung 3). Requests that don’t meet policy are denied with actionable next-best-action guidance. Every access is audit-logged.

Returns the full source code for a symbol’s line range. The request must include a justification (reason), expected line count, and identifiers the agent expects to find in the code. The policy engine evaluates whether the request should be approved, denied, or downgraded. Approval criteria include:

The requested identifiers exist in the range
The symbol is in a current slice or frontier
The scorer utility exceeds the threshold
The agent invokes break-glass with audit logging

If denied, the response includes whyDenied reasons and a nextBestAction suggesting an alternative tool and arguments.

Parameters

repoId

string

required

Repository identifier.

symbolId

string

required

Symbol to read.

reason

string

required

Justification for why raw code is needed. Must be non-empty.

expectedLines

number

required

How many lines the agent expects to need. Clamped to the policy maximum (default: 180).

identifiersToFind

string[]

required

Identifiers the agent expects to find in the code. Required by policy. Maximum 50.

granularity

'symbol' | 'block' | 'fileWindow'

Scope of the code window.

maxTokens

number

Maximum tokens. Clamped to the policy maximum (default: 1,400).

sliceContext

object

Task context for policy evaluation. Providing this improves approval scoring.

Show properties

taskText

string

Task description (required within sliceContext).

stackTrace

string

Stack trace for debugging tasks.

failingTestPath

string

Path to a failing test.

editedFiles

string[]

Recently edited files.

entrySymbols

string[]

Entry symbol IDs.

budget

object

Token budget constraints.

Response (approved)

approved

boolean

Always true when approved.

symbolId

string

Symbol identifier.

file

string

File path.

range

object

{startLine, startCol, endLine, endCol}.

code

string

The raw source code.

whyApproved

string[]

Reasons for approval.

estimatedTokens

number

Token count.

downgradedFrom

string

Set if the request was downgraded (e.g., to skeleton).

matchedIdentifiers

string[]

Which identifiers were found.

matchedLineNumbers

number[]

Line numbers of matches.

Response (denied)

approved

boolean

Always false when denied.

whyDenied

string[]

Reasons the request was denied.

suggestedNextRequest

object

Modified request parameters that might be approved.

nextBestAction

object

{tool, args, rationale} — the alternative tool to try instead.

Example

{
  "repoId": "my-repo",
  "symbolId": "<symbol-id>",
  "reason": "Need exact branch logic for debugging auth timeout",
  "expectedLines": 80,
  "identifiersToFind": ["if", "catch", "tokenExpiry"]
}

Policy Tools

Policy tools control the gate conditions for sdl.code.needWindow. Policy is per-repository and persists across sessions.

sdl.policy.get

Retrieves the current policy configuration for a repository.

Parameters

repoId

string

required

Repository identifier.

Response

{
  "policy": {
    "maxWindowLines": 180,
    "maxWindowTokens": 1400,
    "requireIdentifiers": true,
    "allowBreakGlass": false
  }
}

Example

{ "repoId": "my-repo" }

sdl.policy.set

Updates policy settings for a repository. Accepts a partial patch — only the fields provided are updated; omitted fields retain their current values.

Parameters

repoId

string

required

Repository identifier.

policyPatch

object

required

Partial policy to apply. All fields are optional.

Show properties

maxWindowLines

number

Max lines per code window. Default: 180.

maxWindowTokens

number

Max tokens per code window. Default: 1400.

requireIdentifiers

boolean

Require identifiersToFind in needWindow requests. Default: true.

allowBreakGlass

boolean

Allow break-glass override for denied requests (audit-logged). Default: false.

Response

{ "ok": true, "repoId": "my-repo" }

Example

{
  "repoId": "my-repo",
  "policyPatch": {
    "maxWindowLines": 220,
    "maxWindowTokens": 1800,
    "requireIdentifiers": true,
    "allowBreakGlass": true
  }
}

CLI

MCP Tools

Configuration

Code Access Tools (Iris Gate Ladder)

sdl.code.getSkeleton

Parameters

Response

Examples

sdl.code.getHotPath

Parameters

Response

Example

sdl.code.needWindow

Parameters

Response (approved)

Response (denied)

Example

Policy Tools

sdl.policy.get

Parameters

Response

Example

sdl.policy.set

Parameters

Response

Example

Build docs developers (and LLMs) love

CLI

MCP Tools

Configuration

​sdl.code.getSkeleton

​Parameters

​Response

​Examples

​sdl.code.getHotPath

​Parameters

​Response

​Example

​sdl.code.needWindow

​Parameters

​Response (approved)

​Response (denied)

​Example

​Policy Tools

​sdl.policy.get

​Parameters

​Response

​Example

​sdl.policy.set

​Parameters

​Response

​Example

Build docs developers (and LLMs) love

sdl.code.getSkeleton

Parameters

Response

Examples

sdl.code.getHotPath

Parameters

Response

Example

sdl.code.needWindow

Parameters

Response (approved)

Response (denied)

Example

Policy Tools

sdl.policy.get

Parameters

Response

Example

sdl.policy.set

Parameters

Response

Example