Graph Slice Tools

Graph slices are the primary mechanism for building task-scoped context. Instead of reading files in the same directory, SDL-MCP follows the dependency graph: starting from relevant symbols, it traverses weighted edges and returns the most important symbols within a token budget.

"Fix the auth middleware"  →  slice.build
                                  │
                             BFS over graph
                                  │
         ┌──────────────────┤──────────────────┐
         │               │                  │
authenticate     validateToken          JwtConfig
    │                  │                  │
hashPassword       getUserById         envLoader
                                            │
                                         ◆ frontier (outside budget)

8 cards returned  ·  ~800 tokens
vs. reading 8 files  ·  ~16,000 tokens

sdl.slice.build

Builds a task-scoped dependency subgraph from entry symbols, returning the most relevant symbols for a given task within a token budget. Starting from one or more entry symbols (or a natural-language taskText for auto-discovery), performs a BFS/beam search across the dependency graph. Edges are weighted by type: call (1.0) > config (0.8) > import (0.6). The search expands outward, scoring each symbol by relevance, and stops when the token budget is reached or the confidence threshold drops below minConfidence. The result is a slice containing symbol cards, their interconnecting edges, a frontier of symbols just outside the slice boundary, and a handle for subsequent refresh operations.

taskText alone is sufficient to build a slice — it triggers auto-discovery of relevant symbols via hybrid retrieval (FTS + vector + RRF) or legacy full-text search. Adding entrySymbols improves precision.

Parameters

repoId

string

required

Repository identifier.

taskText

string

Natural language task description. Can be used alone (without entrySymbols) to auto-discover relevant symbols.

entrySymbols

string[]

Symbol IDs to start the BFS from. Maximum 100.

editedFiles

string[]

Recently edited file paths whose symbols (and callers) are forced into the slice. Maximum 100.

stackTrace

string

Stack trace to bias the slice toward call-path symbols.

failingTestPath

string

Path to a failing test file to bias toward code under test.

budget

object

Token and card budget constraints.

Show properties

maxCards

number

Maximum cards to include. Range: 1–500.

maxEstimatedTokens

number

Maximum estimated tokens. Range: 1–200,000.

minConfidence

number

Drop edges below this confidence threshold. Default: 0.5. Range: 0–1.

minCallConfidence

number

Filter call edges specifically below this confidence. Range: 0–1.

knownCardEtags

Record<string, string>

Map of symbolId → ETag. Matching cards return as cardRefs instead of full cards, reducing token cost.

cardDetail

'minimal' | 'signature' | 'deps' | 'compact' | 'full'

Detail level for cards in the slice. Leave unset for mixed adaptive detail.

adaptiveDetail

boolean

Let the system choose detail level per card based on relevance.

wireFormat

'standard' | 'compact'

Response encoding. Default: "compact".

wireFormatVersion

1 | 2 | 3

Compact format version. Default: 2. V2 deduplicates file paths and edge types into lookup tables; V3 adds grouped edge encoding.

includeResolutionMetadata

boolean

Include call resolution details on cards.

includeMemories

boolean

Include related development memories in the response.

memoryLimit

number

Maximum memories to include. Default: 5.

includeRetrievalEvidence

boolean

Include retrieval evidence showing how start-node seeds were discovered.

Response

sliceHandle

string

Handle for refresh and spillover operations.

ledgerVersion

string

The ledger version this slice is based on.

lease

object

Slice validity window: {expiresAt, minVersion, maxVersion}.

sliceEtag

object

{handle, version, sliceHash} for conditional refresh.

slice

object

The graph slice content.

Show properties

cards

array

Full symbol cards within the budget.

cardRefs

array

ETag-matched cards returned as references instead of full cards.

edges

array

Interconnecting edges between slice symbols.

frontier

array

Symbols just outside the budget boundary.

truncation

object

Truncation info including spilloverHandle for paging overflow.

symbolIndex

object

Index mapping symbol IDs to positions.

budget

object

Actual budget consumed.

startSymbols

string[]

The entry symbol IDs used to seed the BFS.

confidenceDistribution

object

Distribution of confidence scores across included edges.

retrievalEvidence

object

Present when includeRetrievalEvidence: true.

Show properties

mode

string

Retrieval mode used: "hybrid" or "legacy".

symptomType

string

Input classification: "taskText", "stackTrace", "failingTest", or "editedFiles".

candidateCountPerSource

object

Candidate counts from each source.

fusionLatencyMs

number

RRF fusion latency in milliseconds.

fallbackReason

string | null

Reason for falling back to legacy mode.

Token Guidance

Start with budget: {maxCards: 30, maxEstimatedTokens: 4000}
Use knownCardEtags on subsequent calls to avoid re-sending unchanged cards
Raise minConfidence to 0.8+ for precision-focused work; keep at 0.5 for broader recall
Use editedFiles to bias the slice toward recently changed code

Examples

{
  "repoId": "my-repo",
  "taskText": "trace auth token validation",
  "entrySymbols": ["<symbol-id>"],
  "budget": { "maxCards": 50, "maxEstimatedTokens": 4000 }
}

sdl.slice.refresh

Incrementally updates an existing slice handle, returning only the delta (changed symbols) since the last known version. If nothing changed, returns notModified: true. This avoids rebuilding the entire slice from scratch after code changes.

Always prefer slice.refresh over rebuilding when you already have a handle. It is dramatically cheaper.

Parameters

sliceHandle

string

required

Handle from a previous sdl.slice.build.

knownVersion

string

required

The ledger version your client last saw.

Response

sliceHandle

string

The same handle.

knownVersion

string

The version you sent.

currentVersion

string

The current ledger version.

notModified

boolean

True if nothing changed since knownVersion.

delta

object | null

A delta pack scoped to the slice’s symbols. Present when changes exist.

Show properties

changedSymbols

array

Symbols that changed since the known version.

blastRadius

array

Dependent symbols affected by the changes.

trimmedSet

array

Symbols trimmed from the slice to make room for new ones.

spilloverHandle

string | null

Handle for overflow if the delta exceeds the budget.

lease

object

Updated lease.

Example

{ "sliceHandle": "h_abc123", "knownVersion": "v1770600000000" }

sdl.slice.spillover.get

Fetches overflow symbols that didn’t fit within the slice’s token budget, via paginated access. When a slice is truncated, the truncation metadata includes a spilloverHandle. This tool uses that handle to page through the remaining symbols.

Parameters

spilloverHandle

string

required

Handle from sdl.slice.build truncation metadata.

cursor

string

Pagination cursor from the previous page.

pageSize

number

Number of symbols per page. Range: 1–100. Default: 20.

Response

spilloverHandle

string

Same handle.

cursor

string

Cursor for the next page.

hasMore

boolean

Whether more pages exist.

symbols

array

Array of full symbol cards.

Example

{ "spilloverHandle": "sp_abc123", "pageSize": 20 }

sdl.delta.get

Computes a semantic diff between two ledger versions, including blast radius analysis. Compares two versions of the ledger and returns all changed symbols with their signature diffs, invariant diffs, and side-effect diffs. For each changed symbol, computes a blast radius — the set of dependent symbols that may be affected, ranked by distance, fan-in, test proximity, and process participation.

Parameters

repoId

string

required

Repository identifier.

fromVersion

string

required

Starting version ID.

toVersion

string

required

Ending version ID.

budget

object

Constrain output size: {maxCards, maxEstimatedTokens}.

Response

delta

object

The delta pack.

Show properties

changedSymbols

array

Each changed symbol:

{symbolId, changeType: "added"|"removed"|"modified", signatureDiff: {before, after}, invariantDiff: {added, removed}, sideEffectDiff: {added, removed}}

blastRadius

array

Each blast radius entry:

{symbolId, reason, distance, rank, signal: "diagnostic"|"directDependent"|"graph"|"process", fanInTrend: {previous, current, growthRate, isAmplifier}}

diagnosticsSummary

object

Summary of diagnostic signals.

diagnosticSuspects

array

Symbols flagged as likely contributors to issues.

truncation

object

Truncation info if the delta exceeded the budget.

trimmedSet

array

Symbols trimmed to fit the budget.

spilloverHandle

string | null

Handle for overflow blast radius entries.

amplifiers

array

Symbols with rapidly growing fan-in: {symbolId, growthRate, previous, current}. These symbols amplify blast radius as more dependents accrue.

Example

{ "repoId": "my-repo", "fromVersion": "v1", "toVersion": "v2" }

sdl.context.summary

Generates a structured, token-bounded context briefing for any query against the codebase. Assembles a budget-constrained context package from four sections: key symbols, dependency graph, risk areas, and files touched. Results are cached by repoId + indexVersion + query. Scope is auto-detected from the query:

Contains /, \, or a file extension → "file"
Contains 3+ words or task-related words → "task"
Otherwise → "symbol"

Parameters

repoId

string

required

Repository identifier.

query

string

required

Natural-language query, file path, or symbol name.

budget

number

Token budget for the summary. Default: 2000.

format

'markdown' | 'json' | 'clipboard'

Output format. Default: "markdown".

scope

'symbol' | 'file' | 'task'

Query scope. Auto-detected if omitted.

Response

repoId

string

Repository identifier.

format

string

Output format used.

content

string

The rendered summary string (markdown or JSON).

summary

object

Structured summary data.

Show properties

keySymbols

array

Each: {symbolId, name, kind, signature, summary, cluster, processes}.

dependencyGraph

array

Each: {fromSymbolId, toSymbolIds: string[]}.

riskAreas

array

Each: {symbolId, name, reasons: string[]} — symbols with fan-in ≥ 15 or high churn.

filesTouched

array

Each: {file, symbolCount}, ranked by density.

metadata

object

{query, summaryTokens, budget, truncated, indexVersion}.

Example

{
  "repoId": "my-repo",
  "query": "auth middleware",
  "budget": 2000,
  "format": "markdown",
  "scope": "task"
}

sdl.pr.risk.analyze

Analyzes the risk of a code change between two versions, producing a scored risk assessment with findings, blast radius, and test recommendations. Computes a delta between two versions, then analyzes changes for risk patterns: high-fan-in symbol modifications, signature changes on widely-used interfaces, side-effect changes, missing test coverage, and more.

Parameters

repoId

string

required

Repository identifier.

fromVersion

string

required

Starting version ID.

toVersion

string

required

Ending version ID.

riskThreshold

number

Only return findings above this risk score. Range: 0–100.

Response

analysis

object

Risk analysis results.

Show properties

riskScore

number

Composite risk score from 0–100.

riskLevel

string

"low", "medium", or "high".

findings

array

Each: {type, severity: "low"|"medium"|"high", message, affectedSymbols, metadata}.

impactedSymbols

string[]

All symbols affected by the changes.

evidence

array

Each: {type, description, symbolId, data}.

recommendedTests

array

Each: {type, description, targetSymbols, priority: "high"|"medium"|"low"}.

changedSymbolsCount

number

Total changed symbols.

blastRadiusCount

number

Total symbols in the blast radius.

escalationRequired

boolean

Whether the risk level warrants review escalation.

policyDecision

object

{decision, deniedReasons, auditHash}.

Example

{
  "repoId": "my-repo",
  "fromVersion": "v1",
  "toVersion": "v2",
  "riskThreshold": 70
}

CLI

MCP Tools

Configuration

Graph Slice Tools

sdl.slice.build

Parameters

Response

Token Guidance

Examples

sdl.slice.refresh

Parameters

Response

Example

sdl.slice.spillover.get

Parameters

Response

Example

sdl.delta.get

Parameters

Response

Example

sdl.context.summary

Parameters

Response

Example

sdl.pr.risk.analyze

Parameters

Response

Example

Build docs developers (and LLMs) love

CLI

MCP Tools

Configuration

​sdl.slice.build

​Parameters

​Response

​Token Guidance

​Examples

​sdl.slice.refresh

​Parameters

​Response

​Example

​sdl.slice.spillover.get

​Parameters

​Response

​Example

​sdl.delta.get

​Parameters

​Response

​Example

​sdl.context.summary

​Parameters

​Response

​Example

​sdl.pr.risk.analyze

​Parameters

​Response

​Example

Build docs developers (and LLMs) love

sdl.slice.build

Parameters

Response

Token Guidance

Examples

sdl.slice.refresh

Parameters

Response

Example

sdl.slice.spillover.get

Parameters

Response

Example

sdl.delta.get

Parameters

Response

Example

sdl.context.summary

Parameters

Response

Example

sdl.pr.risk.analyze

Parameters

Response

Example