Reference

search_knowledge

Search published current Knowledge revisions or read one exact authorized item and immutable revision with bounded pagination.

Pick the read shape before calling

Use query for ranked search or knowledge_item_id for an addressed read. Add knowledge_revision_id only when the exact immutable revision is part of the request.

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

Name	Type	Description
`query`	string · default: empty	Natural-language query for ranked search; required when using query mode and mutually exclusive with addressed identifiers.
`knowledge_base_id`	string · default: empty	Optional exact Knowledge Base ID to narrow query search or validate an addressed item.
`knowledge_item_id`	string · default: empty	Exact authorized item ID for addressed read.
`knowledge_revision_id`	string · default: empty	Optional exact immutable revision ID for the addressed item; it requires knowledge_item_id.
`offset`	integer · default: 0	Zero-based character offset for addressed content.
`limit_chars`	integer · default: 4000	Addressed-read content window from 1 to 10000 characters at the MCP boundary.
`max_results`	integer · default: 10	Maximum query results from 1 to 50.
`mode`	string · default: hybrid	Query scoring mode: hybrid, lexical, semantic, or rrf. Unrecognized text is normalized to hybrid by the MCP handler.
`alpha`	number · default: 0.5	Hybrid lexical weight, clamped to 0.0 through 1.0; the semantic weight is 1-alpha.

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 current published knowledge

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

Read one pinned revision in chunks

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.

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.

Source: Knowledge Bases