Orchata Skills

This document describes how to effectively use Orchata, a RAG (Retrieval-Augmented Generation) platform with tree-based document indexing. Load this into your context to interact with Orchata knowledge bases.

What is Orchata?

Orchata is a knowledge management platform that:

• Organizes documents into Spaces - Logical containers for related content
• Uses tree-based indexing - Documents are parsed into hierarchical structures with sections, summaries, and page ranges
• Provides semantic search - Find relevant content using natural language queries
• Exposes MCP tools - AI assistants can directly manage and query knowledge bases

Core Concepts

Spaces

A Space is a container for related documents. Think of it as a folder with semantic search capabilities.

• Each space has a name, description, and optional icon
• Descriptions are used by smart_query to recommend relevant spaces
• Spaces can be archived (soft-deleted)

Documents

A Document is content within a space. Supported formats include:

• PDF (text-based and scanned with OCR)
• Word documents (.docx)
• Excel spreadsheets (.xlsx)
• PowerPoint presentations (.pptx)
• Markdown files (.md)
• Plain text files (.txt)
• Images (PNG, JPG, etc.)

Document Status:

Status	Description
PENDING	Uploaded, waiting for processing
PROCESSING	Being parsed and indexed
COMPLETED	Ready for queries
FAILED	Processing error occurred

Important: Only query documents with status: "COMPLETED". Other statuses won't return results.

Document Trees

Documents are indexed into hierarchical tree structures:

• Each tree has nodes representing sections/chapters
• Nodes contain: title, summary, startPage, endPage, textContent
• Trees enable precise navigation of large documents

Queries

Two types of queries are available:

1. query_spaces - Search document content using tree-based reasoning
2. smart_query - Discover which spaces are relevant for a query

---

MCP Tools Reference

Space Management

list_spaces

List all knowledge spaces in the organization.

list_spaces
list_spaces with status="active"
list_spaces with page=1 pageSize=20

Parameters:

• page (number, optional): Page number (default: 1)
• pageSize (number, optional): Items per page (default: 10)
• status (string, optional): Filter by active, archived, or all

---

manage_space

Create, get, update, or delete a space.

manage_space with action="create" name="Product Docs" description="Technical documentation"
manage_space with action="create" name="Legal" description="Case files" icon="briefcase"
manage_space with action="get" id="space_abc123"
manage_space with action="update" id="space_abc123" description="Updated description"
manage_space with action="delete" id="space_abc123"

Parameters:

• action (string, required): create, get, update, or delete
• id (string): Space ID (required for get/update/delete)
• name (string): Space name (required for create)
• description (string, optional): Space description
• icon (string, optional): Icon name. Defaults to "folder"
• slug (string, optional): URL-friendly identifier
• isArchived (boolean, optional): Archive status (for update)

Valid Icons: folder, book, file-text, database, package, archive, briefcase, inbox, layers, box

If an invalid icon is provided, the tool returns an error with the list of valid options.

---

Document Management

list_documents

List documents in a space.

list_documents with spaceId="space_abc123"
list_documents with spaceId="space_abc123" status="completed"
list_documents with spaceId="space_abc123" status="all"

Parameters:

• spaceId (string, required): Space ID
• page (number, optional): Page number
• pageSize (number, optional): Items per page (max: 100)
• status (string, optional): Filter by status. Values: pending, processing, completed, failed, or all. Omitting returns all documents.

Note: Status values are case-insensitive (completed and COMPLETED both work).

---

save_document

Upload or upsert documents (single or batch).

Single document:

save_document with spaceId="space_abc123" filename="guide.md" content="# Guide\n\nContent here..."

Batch upload:

save_document with spaceId="space_abc123" documents=[{"filename": "doc1.md", "content": "..."}, {"filename": "doc2.md", "content": "..."}]

Parameters:

• spaceId (string, required): Space ID
• filename (string): Filename (required for single)
• content (string): Content (required for single)
• documents (array, optional): Array of {filename, content, metadata} for batch
• metadata (object, optional): Custom key-value pairs

---

get_document

Get document content by ID or filename. Returns processed markdown text.

get_document with spaceId="space_abc123" id="doc_xyz789"
get_document with spaceId="space_abc123" filename="guide.md"
get_document with spaceId="*" filename="guide.md"

Parameters:

• spaceId (string, required): Space ID, or * to search all spaces (requires filename)
• id (string, optional): Document ID
• filename (string, optional): Filename

Notes:

• Either id or filename is required
• Use spaceId="*" to search all spaces when you know the filename but not the space
• For completed documents, returns the extracted markdown text (not raw PDF binary)
• When using *, the response includes the spaceId where the document was found

---

update_document

Update document content or metadata.

update_document with spaceId="space_abc123" id="doc_xyz789" content="New content..."
update_document with spaceId="space_abc123" id="doc_xyz789" append=true content="Additional content"

Parameters:

• spaceId (string, required): Space ID
• id (string, required): Document ID
• content (string, optional): New content
• metadata (object, optional): New metadata
• append (boolean, optional): Append instead of replace
• separator (string, optional): Separator for append mode

---

delete_document

Permanently delete a document.

delete_document with spaceId="space_abc123" id="doc_xyz789"

Parameters:

• spaceId (string, required): Space ID
• id (string, required): Document ID

---

Query Tools

query_spaces

Search documents across one or more spaces using tree-based reasoning.

query_spaces with query="How do I authenticate API requests?"
query_spaces with query="installation guide" spaceIds="space_abc123"
query_spaces with query="error handling" spaceIds=["space_abc", "space_def"] topK=10

Parameters:

• query (string, required): Natural language search query
• spaceIds (string or array, optional): Space ID(s) to search. Omit or use * for all spaces
• topK (number, optional): Maximum results (default: 10)
• compact (boolean, optional): Use compact format (default: false). See When to Use Compact below.

When to Use Compact:

Mode	When to use	What you get
compact=false (default)	Most queries. Any time you need actual data, facts, numbers, dates, or details from documents.	Full results with document metadata, tree context, page ranges, and complete content.
compact=true	Broad discovery queries where you only need to know which documents are relevant, not their content.	Minimal results: just content snippet, source filename, and score.

Rule of thumb: Default to compact=false. Only use compact=true when you're browsing/surveying and don't need the actual content yet.

Response (compact=true format):

{
  "results": [
    {
      "content": "Relevant text content...",
      "source": "filename.pdf",
      "score": 0.95
    }
  ],
  "total": 5
}

---

smart_query

Discover which spaces are relevant for a query using LLM reasoning.

smart_query with query="How do I install the SDK?"
smart_query with query="billing questions" maxSpaces=3

Parameters:

• query (string, required): Query to find relevant spaces for
• maxSpaces (number, optional): Maximum spaces to return (default: 5)

Response:

{
  "query": "How do I install the SDK?",
  "relevantSpaces": [
    {"spaceId": "space_abc123", "relevance": "Contains SDK installation guides"},
    {"spaceId": "space_def456", "relevance": "Has developer tutorials"}
  ],
  "totalFound": 2
}

Use case: When you don't know which space to search, use smart_query first to discover relevant spaces, then use query_spaces with those space IDs.

---

Tree Visibility Tools

These tools let you explore the hierarchical structure of indexed documents.

get_document_tree

Get the tree structure of a document showing sections, summaries, and page ranges.

get_document_tree with spaceId="space_abc123" documentId="doc_xyz789"

Parameters:

• spaceId (string, required): Space ID
• documentId (string, required): Document ID

Response:

{
  "documentId": "doc_xyz789",
  "totalPages": 45,
  "totalNodes": 12,
  "nodes": [
    {
      "nodeId": "0001",
      "title": "Introduction",
      "summary": "Overview of the system architecture...",
      "pages": "1-5",
      "depth": 0
    },
    {
      "nodeId": "0002",
      "title": "Installation",
      "summary": "Step-by-step installation guide...",
      "pages": "6-12",
      "depth": 0
    }
  ]
}

Use case: Use this to understand a document's structure before drilling into specific sections.

---

get_tree_node

Get the full text content of a specific tree node/section.

get_tree_node with documentId="doc_xyz789" nodeId="0002"

Parameters:

• documentId (string, required): Document ID
• nodeId (string, required): Node ID from the tree structure

Response:

{
  "documentId": "doc_xyz789",
  "filename": "manual.pdf",
  "nodeId": "0002",
  "title": "Installation",
  "summary": "Step-by-step installation guide...",
  "pages": "6-12",
  "depth": 0,
  "content": "## Installation\n\nTo install the software, follow these steps:\n\n1. Download the installer...\n\n..."
}

Use case: After viewing the tree structure, use this to read the full content of a specific section.

---

Workflow Patterns

Pattern 1: Search for Information (Default Approach)

For most questions, a single query_spaces call is all you need. Start here before trying multi-step workflows.

query_spaces with query="your question"

This searches all spaces with full details (compact=false by default). One call, done.

If you want to narrow to specific spaces:

query_spaces with query="your question" spaceIds="known_space_id"

If you truly don't know which spaces exist:

smart_query with query="your question"
# Then use the returned spaceIds:
query_spaces with query="your question" spaceIds=["returned_space_id"]

Avoid over-searching. The multi-step workflow (smart_query -> query_spaces -> get_document_tree -> get_tree_node) is rarely necessary. For most questions, a single query_spaces call returns the answer directly. Only escalate to tree browsing if results are insufficient.

Pattern 2: Look Up Specific Data

When looking for specific facts, numbers, dates, names, or details:

Just query directly -- one call:

query_spaces with query="total amount on invoice #1234"

The default compact=false returns full content with document metadata, so you get the actual data you need in one step. Do not use compact=true for data lookups -- it strips the detail you need.

Pattern 3: Browse a Large Document

When you need to navigate a large document's structure:

1. Get the document structure:

   get_document_tree with spaceId="space_id" documentId="doc_id"
   

2. Identify relevant sections from the node titles and summaries

3. Read specific sections:

   get_tree_node with documentId="doc_id" nodeId="relevant_node_id"
   

Pattern 4: Add New Content

When adding documents to a knowledge base:

1. Find or create the appropriate space:

   list_spaces
   # or
   manage_space with action="create" name="New Space" description="..."
   

2. Upload the content:

   save_document with spaceId="space_id" filename="document.md" content="..."
   

3. Wait for processing (status will change from PENDING -> PROCESSING -> COMPLETED)

4. Verify it's ready:

   list_documents with spaceId="space_id" status="COMPLETED"
   

---

manage_space - Valid Icons

When creating or updating a space, use one of these icon values:

• folder (default)
• book
• file-text
• database
• package
• archive
• briefcase
• inbox
• layers
• box

Invalid icons will return a helpful error message with the list of valid options.

---

list_documents - Status Parameter

The status parameter accepts the following values (case-insensitive):

• "all" - Returns documents in any status (COMPLETED, FAILED, PENDING, PROCESSING)
• "completed" - Returns only successfully processed documents
• "failed" - Returns only documents that failed processing (includes errorMessage field)
• "pending" - Returns documents waiting to be processed
• "processing" - Returns documents currently being processed

Documents with status="FAILED" will include an errorMessage field explaining what went wrong during processing.

---

save_document - Processing Workflow

Documents are processed asynchronously:

1. save_document returns immediately with status="PROCESSING"
2. Background job generates embeddings and indexes the document (typically 1-3 seconds)
3. Status changes to "COMPLETED" when ready
4. Document becomes searchable via query_spaces

To check completion status:

• Use get_document to check a specific document's status
• Use list_documents with status="processing" to see all processing documents
• Use list_documents with status="failed" to see any failures

Example:

// Save document
const result = await save_document({...});
// result.document.status === "PROCESSING"

// Check status after a moment
const doc = await get_document({id: result.document.id});
// doc.status === "COMPLETED" (when ready)

---

get_tree_node - Content Availability

get_tree_node may return "(No text content cached for this node)" for certain nodes. This occurs for:

• Structural/organizational nodes without associated text content
• Nodes that serve as section headers in the tree hierarchy

This is expected behavior.

To read actual document content:

• Use get_document to retrieve the full processed markdown
• Use query_spaces to search and retrieve relevant content chunks

The tree structure (via get_document_tree) is always available and shows document organization, summaries, and page ranges.

---

Best Practices

DO

• Start with a single query_spaces call - it usually has the answer in one step
• Use compact=false (the default) for most queries - you get full content and context
• Check document status before querying - only COMPLETED documents are searchable
• Use descriptive queries - natural language works best
• Use tree tools for large documents - navigate structure instead of reading everything
• Write good space descriptions - they're used by smart_query for discovery

DON'T

• Don't over-search - avoid multi-step workflows (smart_query -> query_spaces -> get_document_tree -> get_tree_node) when a single query_spaces call suffices
• Don't use compact=true for data lookups - it strips the content you need; only use it for broad discovery
• Don't query PENDING/PROCESSING documents - they won't return results
• Don't use very short queries - more context = better results
• Don't forget to check processing status after uploading new documents

---

Error Handling

Common errors and solutions:

Error	Cause	Solution
"Document not found"	Wrong ID or no access	Verify the document ID with list_documents
"Space not found"	Wrong ID or archived	Use list_spaces to find valid space IDs
Empty search results	Document not COMPLETED or no matches	Check document status; try broader query
"Tree not found"	Document uses vector indexing or not processed	Check if document status is COMPLETED
"Invalid icon"	Icon name not in allowed list	Use one of: folder, book, file-text, database, package, archive, briefcase, inbox, layers, box
"No text content cached"	Tree node content not cached	This is normal for structural nodes; use get_document for full content

Troubleshooting Tips

If save_document fails:

1. Verify the space exists with manage_space with action="get" id="..."
2. Ensure content is valid text/markdown
3. Check that the space is not archived

If list_documents returns 0 results:

1. Try status="all" or omit the status parameter entirely
2. Verify the spaceId is correct with list_spaces
3. Check if documents are still processing (status="processing")

If get_tree_node returns no content:

• Some nodes are structural and don't have cached text content
• Use get_document to get the full processed document text instead
• Or use query_spaces to search for specific content

---

Quick Reference

Task	Tool	Example
List all spaces	list_spaces	list_spaces with status="active"
Create a space	manage_space	manage_space with action="create" name="Docs"
List documents	list_documents	list_documents with spaceId="..."
Upload content	save_document	save_document with spaceId="..." content="..."
Get document text	get_document	get_document with spaceId="..." id="..."
Search content	query_spaces	query_spaces with query="..."
Find relevant spaces	smart_query	smart_query with query="..."
View doc structure	get_document_tree	get_document_tree with spaceId="..." documentId="..."
Read a section	get_tree_node	get_tree_node with documentId="..." nodeId="..."