search_knowledge

Ferramenta MCP pública

search_knowledge

Finalidade

Leia conteúdo autorizado da Knowledge Base por uma consulta classificada sobre revisões atuais publicadas ou por um item/revisão exatos, com paginação de conteúdo limitada.

Quando usar

• Pesquise um tópico em uma Knowledge Base autorizada quando o conteúdo publicado atual precisar ser classificado por evidências lexicais, semânticas, híbridas ou RRF.
• Leia um item exato da Knowledge e sua revisão atual ou uma revisão imutável especificamente endereçada.
• Use uma janela de conteúdo limitada com offset e limit_chars quando uma revisão for maior que o orçamento de contexto do chamador.

Quando NÃO usar

• Não use para recuperar memória comum do XMemo; use recall, search_memory ou recall_context na superfície de memória.
• Não use para criar, publicar, atualizar ou arquivar uma Knowledge Base ou item; essas são operações separadas de REST/serviço.
• Não combine query com knowledge_item_id ou knowledge_revision_id; escolha busca por query ou leitura endereçada em cada chamada.
• Não trate uma revisão histórica endereçada como o resultado atual da busca por query; a busca por query segue intencionalmente o current_revision_id de cada item publicado.

Escopo necessário

• knowledge:read é obrigatório; a ferramenta é estritamente somente leitura e não emite evento de auditoria da Knowledge.
• TOOL_CATALOG classifica search_knowledge como uma superfície avançada com min_tier=free e hidden_but_callable=true; ela não faz parte da lista mínima de ferramentas do aplicativo de marketplace público.
• O servidor resolve o contexto de owner autenticado ou vinculado à equipe e não aceita filtros de owner ou scope fornecidos pelo chamador.

Parâmetros

Esquema de retorno

A consulta retorna texto JSON com {"type":"knowledge_search","results":[...]} em que cada resultado inclui os IDs atuais do item/revisão da Knowledge, título, trecho limitado, fonte/citação, referência e pontuações. A leitura endereçada retorna texto JSON com type='knowledge', owner/team/scope, IDs de base/item/revisão, título, conteúdo limitado, locator, source, reference, content_offset, content_limit, content_total_chars e content_truncated. A ferramenta não retorna envelope de auditoria.

Exemplos

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
})

Erros

• knowledge_runtime_disabled: a chave de runtime está desligada e a ferramenta retorna um envelope knowledge_unavailable; isso é um estado operacional, não um fallback para memória sem restrições.
• knowledge_invalid_request: query foi combinado com IDs endereçados, offset/limit_chars/max_results ultrapassou os limites ou o formato da solicitação é inválido.
• knowledge_query_required ou knowledge_item_required: não foi fornecida uma query nem um item endereçado, ou knowledge_revision_id foi fornecido sem knowledge_item_id.
• knowledge_resource_unavailable: a base, o item ou a revisão endereçada está ausente, não autorizada, inativa ou não é um item publicado.
• Falha de autorização ou validação: o chamador não possui knowledge:read, a query excede seu limite de entrada ou um valor de limite está malformado.

Ferramentas relacionadas

• recall_context — Monte um pacote de contexto limitado a partir das memórias comuns do XMemo, não de conteúdo da Knowledge Base.
• search_memory — Use recuperação estritamente direcionada na superfície de memória comum.
• remember — Persista um fato de memória duradouro explicitamente solicitado, não uma revisão da Knowledge.