`ingest_content`

Ingest user-uploaded content into the knowledge base.

Reference

Parameters

Name
content
Type
string · required
Description
Base64-encoded file data (for images/PDFs) or raw text content
Name
sourcePath
Type
string · required
Description
Filename or path identifier (e.g., "brand-guidelines.pdf")
Name
mimeType
Type
string · optional
Description
MIME type — auto-detected from extension if not provided
Name
title
Type
string · optional
Description
Human-readable title for the content
Name
idempotency_key
Type
string · optional
Description
Advisory key for retry replay caching — NOT load-bearing for dedup. Server-derived (sourcePath, document_hash) governs uniqueness. See tool description.
Name
allowShort
Type
boolean · optional
Description
Bypass the 200-char min-length floor for legitimately small content (e.g. a tiny config snippet). Does NOT bypass template-stub pattern checks. (default: false)

Returns

success

{
  success                 true
  stats                   { inserted, updated, reactivated, unchanged, deleted } — counts of how each chunk was handled
  objectCount             Total chunks produced from the input (PDFs and long markdown may produce multiple)
  hasMultimodalEmbedding  Whether Voyage multimodal embedding was generated
  mimeType                The MIME type used for processing (detected if not provided)
  sourcePath              Echoed back for caller verification
  summary                 Brief human-readable description of what was ingested
}

error

{
  error          true
  code           One of CONTENT_TOO_SHORT, CONTENT_TEMPLATE_STUB, DATABASE_ERROR, AUTHENTICATION_REQUIRED, UNKNOWN_ERROR
  message        Specific failure reason
  aiInstruction  Suggested next step for the caller
}

Description

Ingest user-uploaded content into the knowledge base.

Processes images, PDFs, and text documents — extracting content, generating embeddings (text + multimodal), and storing in the knowledge base for search. Re-ingestion at the same sourcePath is idempotent: chunks with unchanged content_hash are unchanged, soft-deleted chunks with matching hash are reactivated, changed chunks are updated, and missing chunks are soft-deleted.

USE THIS TOOL WHEN:

The user uploads a file (image, PDF, document) to add to the knowledge base
Brand guidelines, screenshots, or design specs need to be indexed
You need to add reference material that search_design_system can find later

Parameters:

content (required): Base64-encoded file data (for images/PDFs) or raw text
sourcePath (required): Filename or path identifier (e.g., "brand-guidelines.pdf")
mimeType (optional): MIME type — auto-detected from extension if not provided Supported: application/pdf, image/png, image/jpeg, image/webp, image/gif, image/svg+xml, text/markdown, text/plain, text/typescript, text/tsx, text/javascript, text/jsx, text/css, text/scss, application/json, text/json, application/yaml, text/yaml, application/x-yaml
title (optional): Human-readable title for the content
idempotency_key (optional): Unique key to prevent duplicate ingestion on retry; cached successful results are returned for repeated keys
allowShort (optional, default false): Bypass the 200-char min-length floor for legitimately small content (e.g. a tiny config snippet). Does NOT bypass template-stub pattern checks (PRE-936).

Content sanity guards (text-y content only — PDFs and image/* are exempt):

Content under 200 chars (after trim) is rejected with code CONTENT_TOO_SHORT. Bypassable via { allowShort: true }.
Known LLM placeholder shapes are rejected with code CONTENT_TEMPLATE_STUB. NOT bypassable — fix the content rather than overriding. Detected shapes include "› (...)" lead-ins, parenthesized meta-instructions like "(see body)" / "(full canonical doc content)" / "(to be filled in)", and bracket placeholders like "[placeholder]" / "<placeholder>".

Source

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

ingest_content

Copy link to sectionReference