search_knowledge

Public MCP tool

search_knowledge

Purpose

Read authorized Knowledge Base content either by ranked query over published current revisions or by one exact item/revision with bounded content pagination.

When to use

• Search for a topic across an authorized Knowledge Base when current published content should be ranked by lexical, semantic, hybrid, or RRF evidence.
• Read one exact Knowledge item and either its current revision or a specifically addressed immutable revision.
• Use a bounded content window with offset and limit_chars when a revision is larger than the caller's context budget.

When NOT to use

• Do not use it for ordinary XMemo memory recall; use recall, search_memory, or recall_context for the memory surface.
• Do not use it to create, publish, update, or archive a Knowledge Base or item; those are separate REST/service operations.
• Do not mix query with knowledge_item_id or knowledge_revision_id; choose query search or addressed read for each call.
• Do not treat an addressed historical revision as the current query-search result; query search intentionally follows each published item's current_revision_id.

Required scope

• knowledge:read is required; the tool is strictly read-only and emits no Knowledge audit event.
• TOOL_CATALOG classifies search_knowledge as an advanced surface with min_tier=free and hidden_but_callable=true; it is not part of the minimal public marketplace-app tool list.
• The server resolves the authenticated owner or team-bound context and does not accept caller-supplied owner or scope filters.

Parameters

Return schema

Query returns JSON text with {"type":"knowledge_search","results":[...]} where each result includes the current knowledge item/revision IDs, title, bounded excerpt, source/citation, reference, and scores. Addressed read returns JSON text with type='knowledge', owner/team/scope, base/item/revision IDs, title, bounded content, locator, source, reference, content_offset, content_limit, content_total_chars, and content_truncated. The tool returns no audit envelope.

Examples

search_knowledge({
  query: "deployment runbook",
  knowledge_base_id: "<knowledge-base-id>",
  mode: "hybrid",
  alpha: 0.5,
  max_results: 10
})

search_knowledge({
  knowledge_item_id: "<knowledge-item-id>",
  knowledge_revision_id: "<immutable-revision-id>",
  offset: 0,
  limit_chars: 4000
})

Errors

• knowledge_runtime_disabled: the runtime switch is off and the tool returns a knowledge_unavailable envelope; this is an operational state, not a fallback to unrestricted memory.
• knowledge_invalid_request: query was mixed with addressed IDs, offset/limit_chars/max_results exceeded bounds, or the request shape is otherwise invalid.
• knowledge_query_required or knowledge_item_required: neither a query nor an addressed item was supplied, or knowledge_revision_id was supplied without knowledge_item_id.
• knowledge_resource_unavailable: the addressed base, item, or revision is absent, unauthorized, inactive, or not a published item.
• Authorization or validation failure: the caller lacks knowledge:read, the query exceeds its input limit, or a boundary value is malformed.

Related tools

• recall_context — Build a bounded context pack from ordinary XMemo memories rather than Knowledge Base content.
• search_memory — Use strict targeted retrieval on the ordinary memory surface.
• remember — Persist an explicitly requested durable memory fact, not a Knowledge revision.