Outil de recherche d'outils

L'outil de recherche d'outils (« tool search tool ») permet à Claude de travailler avec des centaines ou des milliers d'outils en les découvrant et en les chargeant à la demande. Au lieu de charger toutes les définitions d'outils dans la « context window » (fenêtre de contexte) dès le départ, Claude recherche dans votre catalogue d'outils (y compris les noms d'outils, les descriptions, les noms d'arguments et les descriptions d'arguments) et charge uniquement les outils dont il a besoin.

Charger chaque définition d'outil dès le départ pose deux problèmes à mesure qu'une bibliothèque d'outils grandit :

• Encombrement du contexte : une configuration multiserveur typique (GitHub, Slack, Sentry, Grafana et Splunk) peut consommer environ 55 000 tokens en définitions avant que Claude n'effectue le moindre travail. La recherche d'outils réduit généralement ce chiffre de plus de 85 pour cent, en ne chargeant que les 3 à 5 outils dont Claude a besoin pour une requête donnée.
• Précision de la sélection d'outils : la capacité de Claude à choisir le bon outil se dégrade dès que vous dépassez 30 à 50 outils disponibles. Comme la recherche d'outils ne charge à la demande qu'un ensemble ciblé d'outils pertinents, la précision de la sélection reste élevée même parmi des milliers d'outils.

Pour connaître les modèles qui prennent en charge la recherche d'outils, consultez Compatibilité des modèles.

La recherche d'outils s'exécute en tant qu'outil côté serveur, mais vous pouvez également implémenter votre propre recherche d'outils côté client. Consultez Implémentation personnalisée de la recherche d'outils pour plus de détails.

Compatibilité des modèles

Les deux variantes de recherche d'outils sont disponibles sur les modèles suivants :

Claude Opus 4.1 et les modèles antérieurs ne prennent pas en charge l'outil de recherche d'outils.

Fonctionnement de la recherche d'outils

Il existe deux variantes de recherche d'outils :

• Regex (tool_search_tool_regex_20251119) : Claude construit des motifs regex pour rechercher des outils.
• BM25 (tool_search_tool_bm25_20251119) : Claude utilise des requêtes en langage naturel pour rechercher des outils.

Lorsque vous activez l'outil de recherche d'outils :

1. Vous incluez un outil de recherche d'outils (par exemple, tool_search_tool_regex_20251119 ou tool_search_tool_bm25_20251119) dans votre liste tools.
2. Vous fournissez chaque définition d'outil dans le tableau tools et définissez defer_loading: true sur les outils qui ne doivent pas être chargés dès le départ. Au moins un outil, normalement l'outil de recherche d'outils lui-même, doit rester non différé.
3. Initialement, le contexte de Claude ne contient que l'outil de recherche d'outils et les éventuels outils non différés.
4. Lorsque Claude a besoin d'outils supplémentaires, il effectue une recherche à l'aide d'un outil de recherche d'outils.
5. L'API exécute la recherche et renvoie les outils correspondants sous forme de blocs tool_reference (jusqu'à 5 par défaut ; Claude peut définir une limit dans son entrée de recherche).
6. L'API développe automatiquement ces références en définitions d'outils complètes.
7. Claude choisit parmi les outils découverts et les appelle.

Démarrage rapide

L'exemple suivant inclut l'outil de recherche d'outils et deux outils différés :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get the weather at a specific location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
            "defer_loading": True,
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "file_types": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["query"],
            },
            "defer_loading": True,
        },
    ],
)

print(response)

Claude recherche dans le catalogue, découvre get_weather et l'appelle. La réponse se termine par stop_reason: "tool_use". Exécutez l'outil découvert et renvoyez un tool_result comme dans Gérer les appels d'outils. La section Format de réponse montre les blocs que vous recevez en retour et ce qu'il faut envoyer ensuite.

Définition de l'outil

L'outil de recherche d'outils possède deux variantes :

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}

Chargement différé des outils

Marquez les outils pour un chargement à la demande en ajoutant defer_loading: true :

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

defer_loading contrôle ce qui entre dans la fenêtre de contexte, et non ce que vous envoyez dans la requête :

• Vous envoyez toujours la définition complète de chaque outil dans le tableau tools à chaque requête, y compris les outils différés. L'API en a besoin côté serveur pour exécuter la recherche et développer les blocs tool_reference.
• Les outils sans defer_loading sont chargés immédiatement dans le contexte.
• Les outils avec defer_loading: true ne sont chargés que lorsque Claude les découvre via la recherche.
• Ne définissez jamais defer_loading: true sur l'outil de recherche d'outils lui-même.
• Gardez vos 3 à 5 outils les plus fréquemment utilisés non différés afin que Claude puisse les appeler sans effectuer de recherche préalable.

Les ensembles d'outils d'utilisation de l'ordinateur et d'utilisation du navigateur (computer_toolset_20260801 et browser_toolset_20260801) acceptent defer_loading par outil membre à l'intérieur de l'objet configs de l'entrée, et non sur l'entrée elle-même ; une requête qui le définit au niveau de l'entrée est rejetée. Comme un ensemble d'outils est différé et développé en tant qu'unité, defer_loading doit se résoudre à la même valeur pour chaque membre activé, et lorsque Claude découvre l'ensemble d'outils via la recherche, tous les membres activés sont chargés en même temps. Consultez Ensembles d'outils client pour le format de configs.

Les deux variantes de recherche d'outils (regex et bm25) recherchent dans les noms d'outils, les descriptions, les noms d'arguments et les descriptions d'arguments.

En interne, l'API exclut les outils différés du préfixe de l'invite système. Lorsque Claude découvre un outil différé via la recherche d'outils, l'API ajoute un bloc tool_reference en ligne dans la conversation, puis le développe en définition d'outil complète avant de le transmettre à Claude. Le préfixe reste intact, de sorte que la « prompt caching » (mise en cache des prompts) est préservée. La grammaire du mode strict (les règles qui contraignent la sortie des appels d'outils à correspondre à vos schémas) est construite à partir de l'ensemble complet des outils, de sorte que defer_loading et le mode strict se combinent sans recompilation de la grammaire.

Format de réponse

Lorsque Claude utilise l'outil de recherche d'outils, la réponse inclut les types de blocs suivants :

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll search for tools to help with the weather information."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01ABC123",
      "name": "tool_search_tool_regex",
      "input": {
        "pattern": "weather",
        "limit": 10
      }
    },
    {
      "type": "tool_search_tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": {
        "type": "tool_search_tool_search_result",
        "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
      }
    },
    {
      "type": "text",
      "text": "I found a weather tool. Let me get the weather for San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01XYZ789",
      "name": "get_weather",
      "input": { "location": "San Francisco", "unit": "fahrenheit" }
    }
  ],
  "stop_reason": "tool_use"
}

Comprendre la réponse

• server_tool_use : l'appel de Claude à l'outil de recherche d'outils. La recherche s'exécute sur les serveurs d'Anthropic. Ne renvoyez jamais de tool_result pour son ID srvtoolu_.... Le champ input contient la recherche (pattern pour la variante regex, query pour BM25) et peut inclure une limit facultative, un entier de 1 à 10 000 qui plafonne le nombre d'outils correspondants renvoyés par la recherche (par défaut : 5).
• tool_search_tool_result : les résultats de la recherche, dans un objet tool_search_tool_search_result imbriqué. Conservez-le tel quel dans l'historique des messages.
• tool_references : un tableau d'objets tool_reference pointant vers les outils découverts. L'API les développe pour Claude. Vous ne les développez jamais vous-même.
• tool_use : l'appel de Claude à un outil découvert. Exécutez-le et renvoyez un tool_result exactement comme dans l'utilisation d'outils standard.

L'API développe automatiquement les blocs tool_reference en définitions d'outils complètes avant de les montrer à Claude. Vous n'avez pas besoin de gérer ce développement vous-même, tant que vous fournissez toutes les définitions d'outils correspondantes dans le paramètre tools.

Poursuivre la conversation

Lors de la requête suivante, renvoyez le contenu de l'assistant sans modification, y compris les blocs server_tool_use et tool_search_tool_result. Ajoutez votre tool_result pour l'outil découvert dans un message utilisateur, et envoyez le même tableau tools : l'outil de recherche plus chaque définition différée. Ne renvoyez pas de tool_result pour l'ID srvtoolu_... : l'API rejette la requête. L'API développe les blocs tool_reference dans tout l'historique de la conversation, de sorte que Claude peut réutiliser les outils découverts lors des tours suivants sans effectuer de nouvelle recherche. Une recherche qui ne trouve aucune correspondance renvoie un tool_search_tool_search_result avec un tableau tool_references vide, et non une erreur.

Intégration MCP

Si vos outils proviennent de serveurs MCP via le connecteur MCP, vous ne définissez pas defer_loading sur les définitions d'outils individuelles. Définissez-le plutôt une seule fois dans le default_config de l'entrée mcp_toolset pour l'ensemble du serveur, ou par outil dans ses configs. Consultez Configuration de l'ensemble d'outils MCP.

Implémentation personnalisée de la recherche d'outils

Vous pouvez implémenter votre propre logique de recherche d'outils (par exemple, à l'aide d'embeddings ou de recherche sémantique) en renvoyant des blocs tool_reference depuis un outil personnalisé. Lorsque Claude appelle votre outil de recherche personnalisé, renvoyez un tool_result standard avec des blocs tool_reference dans le tableau de contenu :

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

Chaque outil référencé doit avoir une définition d'outil correspondante dans le paramètre tools de niveau supérieur, normalement avec defer_loading: true. Cela vous permet d'utiliser des méthodes de recherche que les variantes intégrées ne fournissent pas, comme la récupération basée sur les embeddings, et l'API développe les blocs tool_reference renvoyés de la même manière.

Pour un exemple complet utilisant des embeddings, consultez la recette recherche d'outils avec embeddings.

Gestion des erreurs

Erreurs HTTP (statut 400)

Ces erreurs empêchent l'API de traiter la requête :

Tous les outils sont différés :

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}

Définition d'outil manquante :

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}

Erreurs de résultat d'outil (statut 200)

Lorsqu'une opération de recherche d'outils échoue pendant l'exécution, l'API renvoie une réponse 200 avec l'erreur dans le corps :

{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}

Le champ error_code a quatre valeurs possibles :

• invalid_tool_input : l'entrée de recherche était invalide, par exemple un motif regex mal formé ou un motif dépassant la limite de 200 caractères
• unavailable : la recherche n'a pas pu s'exécuter, par exemple parce qu'elle a expiré ou que le service était indisponible
• too_many_requests : limite de débit dépassée pour les opérations de recherche d'outils
• execution_time_exceeded : la recherche a dépassé sa limite de temps d'exécution

Erreurs courantes

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "name": "my_tool",
  "description": "Full description here",
  "input_schema": {
    "type": "object"
  },
  "defer_loading": true
}

Mise en cache des prompts

Pour savoir comment defer_loading préserve la mise en cache des prompts, consultez Utilisation d'outils avec mise en cache des prompts.

Un outil avec defer_loading: true ne peut pas également porter cache_control : l'API renvoie une erreur 400. Placez le point de rupture du cache sur un outil non différé.

Streaming

Avec le streaming activé, vous recevrez les événements de recherche d'outils dans le flux :

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}

// Search pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}

// Claude continues with discovered tools

Requêtes par lots

Vous pouvez inclure l'outil de recherche d'outils dans l'API Messages Batches.

Limites et bonnes pratiques

Limites

• Nombre maximal d'outils différés : 10 000 outils avec defer_loading: true par requête
• Résultats de recherche : chaque recherche renvoie jusqu'à 5 outils correspondants par défaut ; Claude peut définir limit dans son entrée de recherche sur n'importe quel entier de 1 à 10 000
• Longueur des motifs et des requêtes : maximum 200 caractères pour les motifs regex et 500 caractères pour les requêtes BM25
• Prise en charge des modèles : consultez Compatibilité des modèles

Quand utiliser la recherche d'outils

Utilisez la recherche d'outils lorsque l'une des conditions suivantes s'applique :

• Vous disposez de 10 outils ou plus.
• Vos définitions d'outils consomment plus de 10 000 tokens.
• La précision de la sélection d'outils diminue à mesure que votre ensemble d'outils grandit.
• Vous agrégez plusieurs serveurs MCP (plus de 200 outils).
• Votre bibliothèque d'outils grandit au fil du temps.

L'appel d'outils standard, sans recherche d'outils, convient mieux lorsque vous avez moins de 10 outils, que chaque outil est utilisé dans chaque requête, ou que vos définitions d'outils sont petites (moins de 100 tokens au total).

Conseils d'optimisation

• Gardez vos 3 à 5 outils les plus fréquemment utilisés non différés.
• Rédigez des noms et des descriptions d'outils clairs et descriptifs.
• Utilisez un espace de noms cohérent dans les noms d'outils : préfixez par service ou ressource (par exemple, github_, slack_) afin qu'une seule recherche corresponde à tout le groupe.
• Utilisez dans les descriptions des mots-clés qui correspondent à la façon dont les utilisateurs décrivent les tâches.
• Ajoutez une section d'invite système décrivant les catégories d'outils disponibles : « Vous pouvez rechercher des outils pour interagir avec Slack, GitHub et Jira. »
• Surveillez les outils que Claude découvre afin d'affiner vos descriptions.

Utilisation

La recherche d'outils n'est pas comptabilisée comme un outil serveur distinct. L'objet usage.server_tool_use de la réponse ne comporte aucun champ de recherche d'outils, et les définitions d'outils que la recherche charge dans le contexte comptent comme des tokens d'entrée, comme toute autre définition d'outil.

Étapes suivantes