Outil de recherche d'outils

L'outil de recherche d'outils 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 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.

Le chargement initial de toutes les définitions d'outils entraîne deux problèmes à mesure qu'une bibliothèque d'outils s'agrandit :

• Surcharge du contexte : une configuration multi-serveurs typique (GitHub, Slack, Sentry, Grafana et Splunk) peut consommer environ 55 000 tokens en définitions avant même que Claude ne commence à travailler. La recherche d'outils réduit généralement cette consommation de plus de 85 %, en chargeant uniquement 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 charge uniquement un ensemble ciblé d'outils pertinents à la demande, la précision de la sélection reste élevée même avec des milliers d'outils.

La recherche d'outils est disponible en disponibilité générale sur l'API Claude. Pour les modèles pris en charge, 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 contient uniquement l'outil de recherche d'outils et tous les 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).
6. L'API développe automatiquement ces références en définitions d'outils complètes.
7. Claude sélectionne 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-4-8",
    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 indiqué dans Gérer les appels d'outils. La section Format de réponse montre les blocs que vous recevez et ce qu'il faut envoyer ensuite.



Définition de l'outil

L'outil de recherche d'outils a 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 sont chargés uniquement 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 avoir à effectuer de recherche au préalable.

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 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"
      }
    },
    {
      "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_....
• tool_search_tool_result : les résultats de la recherche, dans un objet imbriqué tool_search_tool_search_result. 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 tout au long de 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 correspond à rien 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. À la place, définissez-le 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, en utilisant des « embeddings » (plongements vectoriels) ou une 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, telles que 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



Mise en cache des prompts

Pour savoir comment defer_loading préserve la mise en cache des prompts, consultez Utilisation d'outils avec la 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 d'arrêt de cache sur un outil non différé.



Streaming

Lorsque le streaming est activé, vous recevrez les événements de recherche d'outils dans le cadre du 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
• 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 s'agrandit.
• Vous agrégez plusieurs serveurs MCP (plus de 200 outils).
• Votre bibliothèque d'outils s'agrandit au fil du temps.

L'appel d'outils standard, sans recherche d'outils, est plus adapté 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 nommage cohérent dans les noms d'outils : préfixez par service ou ressource (par exemple, github_, slack_) afin qu'une seule recherche corresponde à l'ensemble du 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 dans l'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 pour 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 pas de champ de recherche d'outils, et les définitions d'outils que la recherche charge dans le contexte sont comptabilisées comme des tokens d'entrée, comme toute autre définition d'outil.



Étapes suivantes