Outil de recherche d'outils

L'outil de recherche d'outils permet à Claude de travailler avec des centaines ou des milliers d'outils en découvrant et chargeant dynamiquement les outils à 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 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.

Cette approche résout deux problèmes qui s'aggravent rapidement à mesure que les bibliothèques d'outils se développent :

• Surcharge de contexte : Les définitions d'outils consomment rapidement votre budget de contexte. Une configuration multi-serveurs typique (GitHub, Slack, Sentry, Grafana, Splunk) peut consommer ~55k tokens en définitions avant que Claude ne fasse un travail réel. La recherche d'outils réduit généralement cela de plus de 85 %, en chargeant uniquement les 3-5 outils que Claude utilise réellement pour une demande donnée.
• Précision de la sélection d'outils : La capacité de Claude à choisir correctement le bon outil se dégrade considérablement une fois que vous dépassez 30-50 outils disponibles. En présentant un ensemble ciblé d'outils pertinents à la demande, la recherche d'outils maintient une haute précision de sélection même sur des milliers d'outils.

Bien que cela soit fourni comme un outil côté serveur, vous pouvez également implémenter votre propre fonctionnalité de recherche d'outils côté client. Consultez Custom tool search implementation pour plus de détails.

Vous pouvez également implémenter la recherche d'outils côté client en renvoyant des blocs tool_reference de votre propre implémentation de recherche.

Comment fonctionne 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 d'outils
2. Vous fournissez toutes les définitions d'outils avec defer_loading: true pour les outils qui ne doivent pas être chargés immédiatement
3. Claude voit uniquement l'outil de recherche d'outils et tous les outils non différés initialement
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 retourne 3-5 blocs tool_reference les plus pertinents
6. Ces références sont automatiquement développées en définitions d'outils complètes
7. Claude sélectionne parmi les outils découverts et les invoque

Cela maintient votre fenêtre de contexte efficace tout en maintenant une haute précision de sélection d'outils.

Démarrage rapide

Voici un exemple simple avec des outils différés :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

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 d'outils différé

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
}

Points clés :

• Les outils sans defer_loading sont chargés dans le contexte immédiatement
• Les outils avec defer_loading: true ne sont chargés que lorsque Claude les découvre via la recherche
• L'outil de recherche d'outils lui-même ne devrait jamais avoir defer_loading: true
• Gardez vos 3-5 outils les plus fréquemment utilisés comme non différés pour des performances optimales

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

Comment fonctionne le report en interne : Les outils différés ne sont pas inclus dans le préfixe du message système. Lorsque le modèle découvre un outil différé via la recherche d'outils, la définition de l'outil est ajoutée en ligne sous forme de bloc tool_reference dans la conversation. Le préfixe reste inchangé, donc la mise en cache des messages est préservée. La grammaire pour le mode strict se construit à partir de l'ensemble complet des outils, donc defer_loading et le mode strict se composent sans recompilation de grammaire.

Format de réponse

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

{
  "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": {
        "query": "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 : Indique que Claude invoque l'outil de recherche d'outils
• tool_search_tool_result : Contient les résultats de recherche avec un objet tool_search_tool_search_result imbriqué
• tool_references : Tableau d'objets tool_reference pointant vers les outils découverts
• tool_use : Claude invoquant l'outil découvert

Les blocs tool_reference sont automatiquement développés en définitions d'outils complètes avant d'être affichés à Claude. Vous n'avez pas besoin de gérer cette expansion vous-même. Cela se fait automatiquement dans l'API tant que vous fournissez toutes les définitions d'outils correspondantes dans le paramètre tools.

Intégration MCP

Pour configurer mcp_toolset avec defer_loading, consultez MCP connector.

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 ou une recherche sémantique) en renvoyant des blocs tool_reference à partir d'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 avec defer_loading: true. Cette approche vous permet d'utiliser des algorithmes de recherche plus sophistiqués tout en maintenant la compatibilité avec le système de recherche d'outils.

Pour un exemple complet utilisant des embeddings, consultez le cookbook de recherche d'outils avec embeddings.

Gestion des erreurs

Erreurs HTTP (statut 400)

Ces erreurs empêchent le traitement de la demande :

Tous les outils différés :

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

Définition d'outil manquante :

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

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

Les erreurs lors de l'exécution d'outils retournent une réponse 200 avec les informations d'erreur dans le corps :

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

Codes d'erreur :

• too_many_requests : Limite de débit dépassée pour les opérations de recherche d'outils
• invalid_pattern : Motif regex mal formé
• pattern_too_long : Le motif dépasse la limite de 200 caractères
• unavailable : Service de recherche d'outils temporairement indisponible

Erreurs courantes

Mise en cache des messages

Pour savoir comment defer_loading préserve la mise en cache des messages, consultez Tool use with prompt caching.

Le système développe automatiquement les blocs tool_reference dans tout l'historique de conversation, afin que Claude puisse réutiliser les outils découverts dans les tours suivants sans faire de recherche à nouveau.

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 query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"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

Demandes par lot

Vous pouvez inclure l'outil de recherche d'outils dans l'API Messages Batches. Les opérations de recherche d'outils via l'API Messages Batches sont facturées de la même manière que celles dans les demandes d'API Messages régulières.

Conservation des données

La recherche d'outils côté serveur (outil tool_search) indexe et stocke les données du catalogue d'outils (noms d'outils, descriptions et métadonnées d'arguments) au-delà de la réponse API immédiate ; ces données de catalogue sont conservées conformément à la politique de conservation standard d'Anthropic. Les implémentations personnalisées de recherche d'outils côté client qui utilisent l'API Messages standard sont entièrement éligibles à ZDR.

Pour l'éligibilité ZDR sur toutes les fonctionnalités, consultez API and data retention.

Limites et meilleures pratiques

Limites

• Outils maximum : 10 000 outils dans votre catalogue
• Résultats de recherche : Retourne 3-5 outils les plus pertinents par recherche
• Longueur du motif : Maximum 200 caractères pour les motifs regex
• Support du modèle : Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ uniquement (pas Haiku)

Quand utiliser la recherche d'outils

Bons cas d'usage :

• 10+ outils disponibles dans votre système
• Les définitions d'outils consomment >10k tokens
• Vous rencontrez des problèmes de précision de sélection d'outils avec de grands ensembles d'outils
• Construction de systèmes alimentés par MCP avec plusieurs serveurs (200+ outils)
• La bibliothèque d'outils se développe au fil du temps

Quand l'appel d'outils traditionnel pourrait être meilleur :

• Moins de 10 outils au total
• Tous les outils sont fréquemment utilisés dans chaque demande
• Très petites définitions d'outils (<100 tokens au total)

Conseils d'optimisation

• Gardez 3-5 outils les plus fréquemment utilisés comme non différés
• Écrivez des noms et 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 que les requêtes de recherche fassent naturellement surface au bon groupe d'outils
• Utilisez des mots-clés sémantiques dans les descriptions qui correspondent à la façon dont les utilisateurs décrivent les tâches
• Ajoutez une section de message 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 les descriptions

Utilisation

L'utilisation de l'outil de recherche d'outils est suivie dans l'objet d'utilisation de la réponse :

{
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "server_tool_use": {
      "tool_search_requests": 2
    }
  }
}

Étapes suivantes