search_knowledge

Outil MCP public

search_knowledge

Objectif

Lire du contenu autorisé de base de connaissances soit par requête classée sur les révisions actuelles publiées, soit par un élément/une révision exact avec pagination de contenu délimitée.

Quand l'utiliser

• Rechercher un sujet dans une base de connaissances autorisée lorsque le contenu publié actuel doit être classé par indices lexicaux, sémantiques, hybrides ou RRF.
• Lire un élément exact de Knowledge et soit sa révision actuelle, soit une révision immuable spécifiquement adressée.
• Utiliser une fenêtre de contenu délimitée avec offset et limit_chars lorsqu'une révision dépasse le budget de contexte de l'appelant.

Quand NE PAS l'utiliser

• Ne l'utilisez pas pour le rappel ordinaire de mémoires XMemo ; utilisez recall, search_memory ou recall_context pour la surface de mémoire.
• Ne l'utilisez pas pour créer, publier, mettre à jour ou archiver une base de connaissances ou un élément ; il s'agit d'opérations de service/REST distinctes.
• Ne mélangez pas query avec knowledge_item_id ou knowledge_revision_id ; choisissez une recherche par requête ou une lecture adressée pour chaque appel.
• Ne traitez pas une révision historique adressée comme le résultat actuel d'une recherche par requête ; la recherche par requête suit intentionnellement le current_revision_id de chaque élément publié.

Périmètre requis

• knowledge:read est requis ; l'outil est strictement en lecture seule et n'émet aucun événement d'audit Knowledge.
• TOOL_CATALOG classifie search_knowledge comme une surface avancée avec min_tier=free et hidden_but_callable=true ; il ne fait pas partie de la liste minimale d'outils d'application de marketplace publique.
• Le serveur résout le contexte authentifié du propriétaire ou lié à l'équipe et n'accepte pas de filtres de propriétaire ou de périmètre fournis par l'appelant.

Paramètres

Schéma de retour

La requête renvoie un texte JSON avec {"type":"knowledge_search","results":[...]} où chaque résultat comprend les ID d'élément/révision actuels de knowledge, le titre, un extrait délimité, la source/citation, la référence et les scores. La lecture adressée renvoie un texte JSON avec type='knowledge', owner/team/scope, les ID de base/élément/révision, le titre, le contenu délimité, le localisateur, la source, la référence, content_offset, content_limit, content_total_chars et content_truncated. L'outil ne renvoie aucune enveloppe d'audit.

Exemples

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

Erreurs

• knowledge_runtime_disabled : le commutateur d'exécution est désactivé et l'outil renvoie une enveloppe knowledge_unavailable ; il s'agit d'un état opérationnel et non d'un basculement vers une mémoire sans restriction.
• knowledge_invalid_request : query a été combiné avec des identifiants adressés, offset/limit_chars/max_results ont dépassé les limites, ou la forme de la requête est par ailleurs invalide.
• knowledge_query_required ou knowledge_item_required : ni une requête ni un élément adressé n'ont été fournis, ou knowledge_revision_id a été fourni sans knowledge_item_id.
• knowledge_resource_unavailable : la base, l'élément ou la révision adressé est absent, non autorisé, inactif ou n'est pas un élément publié.
• Échec d'autorisation ou de validation : l'appelant ne dispose pas de knowledge:read, la requête dépasse sa limite d'entrée, ou une valeur de limite est malformée.

Outils associés

• recall_context — Construire un pack de contexte délimité à partir de mémoires XMemo ordinaires plutôt que du contenu de base de connaissances.
• search_memory — Utiliser une récupération ciblée stricte sur la surface de mémoire ordinaire.
• remember — Persister un fait de mémoire durable explicitement demandé, et non une révision de connaissances.