Knowledge Base MCP Tools -- Complete Guide

The WorkingAgents knowledge base gives AI agents scoped access to internal documents – policies, procedures, guides, runbooks, product info – through MCP tools. Documents are chunked, embedded for semantic search, and indexed for full-text keyword search. Access is controlled by scope-based permissions so agents only see documents they’re authorized to read.

This guide covers every tool, what it does, and how to use it.

Tools at a Glance

Tool	Purpose
`knowledge_search`	Semantic search using vector embeddings
`knowledge_search_text`	Full-text keyword search (FTS5, instant)
`knowledge_add`	Add a new document
`knowledge_import`	Import a markdown file (title extracted from heading)
`knowledge_update`	Update document metadata (tags, scope, visibility, status)
`knowledge_list`	List documents you have permission to see
`knowledge_get`	Get a full document by ID
`knowledge_delete`	Soft-delete a document

Core Concepts

Scopes

Every document belongs to a scope. Your permissions determine which scopes you can access.

Scope	Who sees it
`general`	Everyone with Knowledge permission
`sales`	Sales team
`hr`	HR team
`engineering`	Engineering team
`finance`	Finance team
`executive`	Executive team

An agent with engineering scope permissions can search, list, and read engineering and general documents but not HR or finance documents.

Visibility

Within a scope, documents can be:

shared (default) – visible to everyone who has the scope permission
private – visible only to the user who created the document

Tool Reference

knowledge_search

Semantic search across document chunks using vector embeddings. Best for natural language questions where exact keywords may not match.

Parameters:

query (string, required) – natural language search query
k (number, optional) – number of results to return (default 5, max 20)
tags (array of strings, optional) – filter by tags (AND logic)

Returns: List of chunk results with doc_id, doc_title, text, distance (lower is more similar), chunk_index

Examples:

# Find documents about onboarding procedures
knowledge_search(query: "how do we onboard new employees")

# Search engineering docs about deployment
knowledge_search(query: "deployment process for production", tags: ["devops"])

# Get more results
knowledge_search(query: "pricing strategy", k: 15)

# Search with multiple tag filters
knowledge_search(query: "agent permissions", tags: ["mcp", "security"])

Tips:

Results are chunks (~2000 chars), not full documents. If a chunk looks relevant but incomplete, use knowledge_get with the doc_id to retrieve the full document.
Semantic search understands meaning – “how to fire someone” will match docs about “termination procedures” even if those exact words don’t appear.

knowledge_search_text

Full-text keyword search using FTS5. Instant, no embedding needed. Best for exact terms, names, or phrases.

Parameters:

query (string, required) – keyword or phrase search query
k (number, optional) – number of results to return (default 10, max 50)
tags (array of strings, optional) – filter by tags (AND logic)

Returns: List of chunk results with doc_id, doc_title, text, rank, chunk_index

Examples:

# Search for a specific term
knowledge_search_text(query: "HIPAA compliance")

# Find mentions of a person
knowledge_search_text(query: "Santiago Pastorino")

# Search within tagged documents only
knowledge_search_text(query: "API endpoint", tags: ["engineering"])

# Get more results for a broad search
knowledge_search_text(query: "quarterly report", k: 30)

Tips:

Use this when you know the exact terms. It’s faster than semantic search and doesn’t require an embedding API call.
Supports standard FTS5 query syntax – phrases in quotes, prefix matching with *.

knowledge_add

Add a new document to the knowledge base. The document is automatically chunked, embedded, and indexed for both semantic and keyword search.

Parameters:

title (string, required) – document title
content (string, required) – document content (plain text or markdown)
scope (string, required) – one of: general, sales, hr, engineering, finance, executive
visibility (string, optional) – “shared” (default) or “private”
tags (array of strings, optional) – tags for categorization

Returns: {id, status: "added", visibility, tags}

Examples:

# Add a general company policy
knowledge_add(
  title: "Remote Work Policy",
  content: "## Remote Work Guidelines\n\nAll employees may work remotely...",
  scope: "general"
)

# Add an engineering runbook with tags
knowledge_add(
  title: "Database Migration Runbook",
  content: "## Steps for running database migrations in production...",
  scope: "engineering",
  tags: ["devops", "database", "runbook"]
)

# Add a private sales note
knowledge_add(
  title: "Q1 Pipeline Notes",
  content: "Key deals in progress...",
  scope: "sales",
  visibility: "private"
)

# Add an HR document with multiple tags
knowledge_add(
  title: "Interview Process Guide",
  content: "## How to conduct technical interviews...",
  scope: "hr",
  tags: ["hiring", "interviews", "guide"]
)

knowledge_import

Import a markdown file into the knowledge base. The title is automatically extracted from the first # heading in the content. Useful for bulk importing existing documentation.

Parameters:

filename (string, required) – original filename (e.g., “pricing-guide.md”)
content (string, required) – markdown file content
scope (string, required) – one of: general, sales, hr, engineering, finance, executive
visibility (string, optional) – “shared” (default) or “private”
tags (array of strings, optional) – tags for categorization

Returns: {id, status: "imported", visibility, tags}

Examples:

# Import a guide with tags
knowledge_import(
  filename: "mcp-setup-guide.md",
  content: "# MCP Server Setup Guide\n\nThis guide covers...",
  scope: "engineering",
  tags: ["mcp", "setup", "guide"]
)

# Import a sales playbook
knowledge_import(
  filename: "enterprise-playbook.md",
  content: "# Enterprise Sales Playbook\n\n## Qualification...",
  scope: "sales",
  tags: ["playbook", "enterprise"]
)

knowledge_update

Update a document’s metadata without changing its content. Use this to add or change tags, move documents between scopes, change visibility, or archive documents.

Parameters:

id (number, required) – document ID
tags (array of strings, optional) – new tags (replaces all existing tags)
scope (string, optional) – new scope
visibility (string, optional) – “shared” or “private”
status (string, optional) – “active” or “archived”

Returns: {id, status: "updated", changes}

Examples:

# Add tags to an existing document
knowledge_update(id: 42, tags: ["mcp", "security", "guide"])

# Move a document to a different scope
knowledge_update(id: 42, scope: "engineering")

# Make a document private
knowledge_update(id: 42, visibility: "private")

# Archive a document (keeps it in the database but hides from search/list)
knowledge_update(id: 42, status: "archived")

# Update multiple fields at once
knowledge_update(id: 42, tags: ["deprecated"], scope: "general", status: "archived")

# Clear all tags from a document
knowledge_update(id: 42, tags: [])

knowledge_list

List documents you have permission to see, optionally filtered by tags.

Parameters:

limit (number, optional) – max results (default 50)
tags (array of strings, optional) – filter by tags (AND logic)

Returns: List of document metadata (id, title, scope, visibility, tags, chunk_count, status)

Examples:

# List all documents you can see
knowledge_list()

# List only documents tagged as guides
knowledge_list(tags: ["guide"])

# List documents tagged with both "mcp" and "security"
knowledge_list(tags: ["mcp", "security"])

# Limit results
knowledge_list(limit: 10)

knowledge_get

Get a full document by ID, including its complete content. Use this after search returns a relevant chunk and you need the full document.

Parameters:

id (number, required) – document ID

Returns: Full document with all fields (id, title, content, scope, visibility, tags, chunk_count, etc.)

Examples:

# Get a specific document
knowledge_get(id: 42)

# Typical workflow: search, then get the full document
# 1. Search returns a chunk from doc_id 42
knowledge_search(query: "deployment checklist")
# 2. Get the full document
knowledge_get(id: 42)

knowledge_delete

Soft-delete a document by ID. The document is marked as deleted but remains in the database. It will no longer appear in search results or listings.

Parameters:

id (number, required) – document ID

Returns: {deleted: true}

Examples:

# Delete an outdated document
knowledge_delete(id: 42)

Common Workflows

Search-first protocol

When an agent receives a question that might be answered by internal documents, always search the knowledge base first:

Try knowledge_search with a natural language query
If results are sparse, try knowledge_search_text with specific keywords
If a chunk looks relevant but incomplete, use knowledge_get with the doc_id
Cite the document title when referencing results
If no relevant results are found, say so and answer from general knowledge

Tagging strategy

Tags work best when they follow a consistent convention:

Type tags: guide, runbook, policy, playbook, reference
Domain tags: mcp, security, devops, sales, onboarding
Status tags: draft, reviewed, deprecated

Use knowledge_update to add tags to existing documents. Use knowledge_list(tags: [...]) to find documents by category.

Bulk tagging by filename pattern

To tag documents based on filename patterns, list all documents and update tags for matches:

knowledge_list() to get all documents with their IDs and filenames
For each document matching your pattern, call knowledge_update(id: ..., tags: [...])

Archiving instead of deleting

Prefer archiving over deleting. Archived documents don’t appear in search or listings but can be restored:

# Archive instead of delete
knowledge_update(id: 42, status: "archived")

# To restore later (if needed via direct DB access)
# Update status back to "active"