Symbol Tools

Symbol tools are the primary entry point for code understanding. Start here to find symbols, then use cards to understand what they do before escalating to code access.

A Symbol Card costs ~50–150 tokens. Reading the full file typically costs ~2,000 tokens. Always try cards before requesting code.

sdl.symbol.search

Searches the symbol graph by name, with optional semantic reranking or hybrid retrieval. Performs a text search across all symbol names in the repository. When semantic: true is specified, the retrieval path depends on configuration: with semantic.retrieval.mode: "hybrid", results are found via FTS + vector search fused with Reciprocal Rank Fusion (RRF); with legacy mode, results are reranked using embedding similarity. Falls back to legacy automatically if hybrid indexes are unavailable. The tool also triggers predictive prefetch of cards for the top 5 results, anticipating follow-up getCard calls.

Parameters

repoId

string

required

Repository identifier.

query

string

required

Search query matched against symbol names.

kinds

string[]

Filter by symbol kind. Valid values: function, class, interface, type, module, method, constructor, variable.

limit

number

Maximum results to return. Range: 1–1000. Default: 50.

semantic

boolean

Enable semantic reranking or hybrid retrieval.

includeRetrievalEvidence

boolean

Include retrieval evidence in the response: sources used, candidate counts, fusion latency, and fallback reason.

Response

results

array

Array of matching symbols.

Show properties

symbolId

string

Unique symbol identifier (SHA-256 hash).

name

string

Symbol name.

file

string

Relative file path.

kind

string

Symbol kind: function, class, interface, type, module, method, constructor, or variable.

retrievalMode

string

Which retrieval path was used: "hybrid" or "legacy".

retrievalEvidence

object

Present when includeRetrievalEvidence: true.

Show properties

mode

string

Retrieval mode used.

ftsAvailable

boolean

Whether full-text search was available.

vectorAvailable

boolean

Whether vector search was available.

candidateCountPerSource

object

Candidate counts from each source.

fusionLatencyMs

number

RRF fusion latency in milliseconds.

fallbackReason

string | null

Reason for falling back to legacy mode, if applicable.

truncation

object

Present if results were truncated.

Show properties

truncated

boolean

Whether results were truncated.

droppedCount

number

Number of results dropped.

howToResume

string

Guidance for getting more results.

Examples

{ "repoId": "my-repo", "query": "parseConfig", "limit": 20 }

sdl.symbol.getCard

Retrieves a single symbol card — the core unit of code understanding in SDL-MCP. Returns the full metadata record for a symbol: identity, file location, line range, kind, export status, visibility, parsed signature (with parameter names, types, return type, generics, overloads), a 1–2 line semantic summary, invariants, side effects, dependency edges (imports and calls with labels), metrics (fan-in, fan-out, 30-day churn, test references, canonical test mapping), cluster membership, and process participation. Supports ETag-based conditional requests via ifNoneMatch — if the symbol hasn’t changed, a notModified response is returned with zero data transfer. Provide exactly one of symbolId or symbolRef.

Parameters

repoId

string

required

Repository identifier.

symbolId

string

Symbol identifier (SHA-256 hash). Provide either this or symbolRef.

symbolRef

object

Natural symbol reference. Provide either this or symbolId.

Show properties

name

string

required

Symbol name to look up.

file

string

Narrow the lookup to a specific file path.

kind

string

Narrow by symbol kind.

exportedOnly

boolean

Only match exported symbols.

ifNoneMatch

string

ETag from a previous card response. Returns notModified if the symbol hasn’t changed.

minCallConfidence

number

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

includeResolutionMetadata

boolean

Include full call resolution details: resolver ID, resolution phase, and reason.

Response (full card)

symbolId

string

Unique symbol identifier.

repoId

string

Repository identifier.

file

string

Relative file path.

range

object

{startLine, startCol, endLine, endCol}.

kind

string

function, class, interface, type, module, method, constructor, or variable.

name

string

Symbol name.

exported

boolean

Whether the symbol is exported.

visibility

string

public, protected, private, exported, or internal.

signature

object

Parsed signature.

Show properties

name

string

Symbol name.

params

array

Array of {name, type} parameter objects.

returns

string

Return type.

generics

string[]

Generic type parameters.

overloads

array

Overload signatures if present.

summary

string

1–2 line semantic summary of what the symbol does.

invariants

string[]

Known invariants, e.g., "returns non-null".

sideEffects

string[]

Known side effects, e.g., "writes to disk".

deps

object

Human-readable dependency labels.

Show properties

imports

string[]

Import dependency labels.

calls

string[]

Call dependency labels.

metrics

object

Usage metrics.

Show properties

fanIn

number

Number of symbols that depend on this one.

fanOut

number

Number of symbols this one depends on.

churn30d

number

Number of modifications in the last 30 days.

testRefs

string[]

Test file references.

canonicalTest

object

{file, symbolId, distance, proximity} — the nearest associated test.

cluster

object

Community detection result: {clusterId, label, memberCount}.

processes

array

Call-chain participation: {processId, label, role: "entry"|"intermediate"|"exit", depth}.

etag

string

Content hash for conditional requests.

version

object

{ledgerVersion, astFingerprint}.

Response (not modified)

{
  "notModified": true,
  "etag": "abc123...",
  "ledgerVersion": "v42"
}

Examples

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

sdl.symbol.getCards

Batch-fetches multiple symbol cards in a single round trip. Identical to getCard but accepts an array of up to 100 symbol IDs or natural references. Each symbol is resolved independently, with per-symbol ETag support via knownEtags. Symbols whose ETags match return notModified instead of the full card. Provide exactly one of symbolIds or symbolRefs.

Parameters

repoId

string

required

Repository identifier.

symbolIds

string[]

Array of symbol IDs to fetch. Range: 1–100. Provide either this or symbolRefs.

symbolRefs

object[]

Array of natural symbol references. Range: 1–100. Provide either this or symbolIds. Each object: {name, file?, kind?, exportedOnly?}.

knownEtags

Record<string, string>

Map of symbolId → ETag for conditional fetching. Matching symbols return notModified instead of the full card.

minCallConfidence

number

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

includeResolutionMetadata

boolean

Include full call resolution details.

Response

{
  "cards": [
    { "symbolId": "...", "name": "...", "..." : "..." },
    { "notModified": true, "etag": "...", "ledgerVersion": "..." }
  ],
  "partial": true,
  "succeeded": ["sym-1"],
  "failed": ["missingNode"],
  "failures": [
    {
      "input": "missingNode",
      "classification": "not_found",
      "fallbackTools": ["sdl.symbol.search"]
    }
  ]
}

Examples

{
  "repoId": "my-repo",
  "symbolIds": ["<id1>", "<id2>", "<id3>"],
  "knownEtags": { "<id1>": "<etag1>" }
}

Live Editor Buffer Tools

These three tools enable real-time indexing of unsaved editor content. They are primarily consumed by IDE integrations (such as the VSCode extension) to keep symbol search, cards, and slices current with the latest edits before files are saved.

sdl.buffer.push

Pushes an editor buffer event to the live-index overlay. Accepts full buffer content along with metadata (cursor position, selections, dirty state). The overlay store tracks the buffer and schedules a background parse. On save events, the overlay is checkpointed into the durable graph database.

Parameters

repoId

string

required

Repository identifier.

eventType

'open' | 'change' | 'save' | 'close' | 'checkpoint'

required

Type of editor buffer lifecycle event.

filePath

string

required

Relative file path within the repo. Must not contain ...

content

string

required

Full file content. Maximum 5 MB.

version

number

required

Editor buffer version number (monotonically increasing).

dirty

boolean

required

Whether the buffer has unsaved changes.

timestamp

string

required

ISO timestamp of the event.

language

string

Language identifier, e.g., "typescript".

cursor

object

Current cursor position: {line, col}.

selections

array

Active text selections: array of {startLine, startCol, endLine, endCol}.

Response

accepted

boolean

Whether the event was accepted.

repoId

string

Repository identifier.

overlayVersion

number

Current overlay version.

parseScheduled

boolean

Whether a background parse was queued.

checkpointScheduled

boolean

Whether a checkpoint was queued.

warnings

string[]

Any warnings, e.g., max draft files exceeded.

Example

{
  "repoId": "my-repo",
  "eventType": "change",
  "filePath": "src/auth/token.ts",
  "content": "export function validateToken() {}",
  "language": "typescript",
  "version": 12,
  "dirty": true,
  "timestamp": "2026-03-07T12:00:00.000Z"
}

sdl.buffer.checkpoint

Requests a manual checkpoint of all pending live draft buffers to the durable graph database. Forces the overlay store to write all pending buffer parses immediately, rather than waiting for the idle checkpoint timer.

Parameters

repoId

string

required

Repository identifier.

reason

string

Optional reason for the checkpoint.

Response

repoId

string

Repository identifier.

requested

boolean

Whether the checkpoint was initiated.

checkpointId

string

Unique checkpoint identifier.

pendingBuffers

number

Buffers pending at time of request.

checkpointedFiles

number

Files successfully checkpointed.

failedFiles

number

Files that failed to checkpoint.

lastCheckpointAt

string | null

ISO timestamp of last successful checkpoint.

Example

{ "repoId": "my-repo", "reason": "manual" }

sdl.buffer.status

Returns the current state of the live editor buffer system for a repository. A diagnostic tool for IDE integrations.

Parameters

repoId

string

required

Repository identifier.

Response

repoId

string

Repository identifier.

enabled

boolean

Whether live indexing is active.

pendingBuffers

number

Buffers awaiting processing.

dirtyBuffers

number

Buffers with unsaved changes.

parseQueueDepth

number

Background parse queue size.

checkpointPending

boolean

Whether a checkpoint is queued.

lastBufferEventAt

string | null

ISO timestamp of last buffer event.

lastCheckpointAt

string | null

ISO timestamp of last checkpoint.

lastCheckpointResult

string | null

"success", "partial", "failed", or null.

lastCheckpointError

string | null

Error message if last checkpoint failed.

reconcileQueueDepth

number

Pending reconciliation tasks.

reconcileInflight

boolean

Whether reconciliation is currently running.

Example

{ "repoId": "my-repo" }

CLI

MCP Tools

Configuration

sdl.symbol.search

Parameters

Response

Examples

sdl.symbol.getCard

Parameters

Response (full card)

Response (not modified)

Examples

sdl.symbol.getCards

Parameters

Response

Examples

Live Editor Buffer Tools

sdl.buffer.push

Parameters

Response

Example

sdl.buffer.checkpoint

Parameters

Response

Example

sdl.buffer.status

Parameters

Response

Example

Build docs developers (and LLMs) love

CLI

MCP Tools

Configuration

​sdl.symbol.search

​Parameters

​Response

​Examples

​sdl.symbol.getCard

​Parameters

​Response (full card)

​Response (not modified)

​Examples

​sdl.symbol.getCards

​Parameters

​Response

​Examples

​Live Editor Buffer Tools

​sdl.buffer.push

​Parameters

​Response

​Example

​sdl.buffer.checkpoint

​Parameters

​Response

​Example

​sdl.buffer.status

​Parameters

​Response

​Example

Build docs developers (and LLMs) love

sdl.symbol.search

Parameters

Response

Examples

sdl.symbol.getCard

Parameters

Response (full card)

Response (not modified)

Examples

sdl.symbol.getCards

Parameters

Response

Examples

Live Editor Buffer Tools

sdl.buffer.push

Parameters

Response

Example

sdl.buffer.checkpoint

Parameters

Response

Example

sdl.buffer.status

Parameters

Response

Example