list_chunks

Enumerate knowledge-base chunks under a source-path prefix.

Copy link to sectionReference

Parameters

Returns

success

{
  success    true
  entries    Array of { source_path, chunk_count, active_count, last_synced_at, content_hash, identity_id }
    chunk_count     total chunks at this source_path (or active-only if includeDeprecated is false)
    active_count    chunks with is_active = true
    last_synced_at  most recent timestamp across chunks (ISO 8601)
    content_hash    document-level SHA-256 over per-chunk hashes ordered by chunk_index — stable per-content fingerprint
    identity_id     artifact_id from the identity layer (PRE-783) when present, else null
  total      total source_paths matching the prefix (pre-limit)
  truncated  true when total > limit
  prefix     echoed for verification
  summary    human-readable count
}

error

{
  error          true
  code           DATABASE_ERROR or UNKNOWN_ERROR
  message        Specific failure reason
  aiInstruction  Suggested next step for the caller
}

Description

Enumerate knowledge-base chunks under a source-path prefix.

Use this to answer "what's in the KB under prefix X?" — returns one row per source_path with chunk count, last sync time, document-level hash, and artifact_id (when available). The default verification surface after sync_knowledge_docs or ingest_content: confirm the docs landed without fishing through semantic search.

USE THIS TOOL WHEN:

• You just ran sync_knowledge_docs or ingest_content and want to verify the docs landed
• You need to audit "what's in the KB under prefix X?" without semantic search games
• You want a stable document fingerprint (content_hash) to detect drift

Parameters:

• prefix (required): Source-path prefix to enumerate (e.g., "docs/design-patterns/"). LIKE wildcards (% _) in the prefix are escaped.
• limit (optional, default 100): Max source_paths to return; truncated flag set if more exist.
• includeDeprecated (optional, default false): Include soft-deleted (is_active = false) chunks. Default matches search retrieval policy.

Copy link to sectionSource

Defined in packages/mcp/src/tools.ts. The request handler lives alongside its registration in packages/mcp/src/tools/.