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 dynamiquement à 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 ne charge que les outils dont il a besoin.

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

• 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 environ 55 000 tokens en définitions avant que Claude n'effectue un quelconque travail réel. La recherche d'outils réduit généralement cela de plus de 85 %, en ne chargeant que les 3 à 5 outils dont Claude a réellement besoin pour une requête donnée.
• Précision de sélection d'outils : La capacité de Claude à choisir correctement le bon outil se dégrade significativement dès 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. Voir Implémentation personnalisée de recherche d'outils pour plus de détails.

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

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 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 ne voit initialement que l'outil de recherche d'outils et 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 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 conservant une haute précision de sélection d'outils.

Démarrage rapide

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ]
    }'

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
}

Points clés :

• 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
• L'outil de recherche d'outils lui-même ne doit 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 dans les noms d'outils, les descriptions, les noms d'arguments et les descriptions d'arguments.

Fonctionnement interne du différé : Les outils différés ne sont pas inclus dans le préfixe du prompt 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 intact, de sorte que la mise en cache des prompts est préservée. La grammaire pour le mode strict est construite à partir de l'ensemble complet des outils, donc defer_loading et le mode strict se composent sans recompilation de la 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 la 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 présentés à Claude. Vous n'avez pas besoin de gérer cette expansion vous-même. Elle se produit 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, voir Connecteur MCP.

Implémentation personnalisée de recherche d'outils

Vous pouvez implémenter votre propre logique de recherche d'outils (par exemple, en utilisant des embeddings ou la recherche sémantique) en retournant des blocs tool_reference depuis un outil personnalisé. Lorsque Claude appelle votre outil de recherche personnalisé, retournez 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, voir le cookbook de recherche d'outils avec embeddings.

Gestion des erreurs

Erreurs HTTP (statut 400)

Ces erreurs empêchent le traitement de la requête :

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 de l'outil retournent une réponse 200 avec des 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 malformé
• 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 prompts

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

Le système développe automatiquement les blocs tool_reference dans l'ensemble de l'historique de conversation, de sorte que Claude peut réutiliser les outils découverts lors des tours suivants sans effectuer de nouvelle recherche.

Streaming

Avec le streaming activé, vous recevrez des é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"}}

// Requête de recherche diffusée en continu
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pause pendant l'exécution de la recherche

// Résultats de recherche diffusés en continu
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 continue avec les outils découverts

Requêtes par lots

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 tarifées de la même manière que celles des requêtes 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, voir API et conservation des données.

Limites et bonnes pratiques

Limites

• Nombre maximum d'outils : 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 des modèles : Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ uniquement (pas Haiku)

Quand utiliser la recherche d'outils

Bons cas d'utilisation :

• 10+ outils disponibles dans votre système
• Définitions d'outils consommant plus de 10 000 tokens
• 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)
• Bibliothèque d'outils en croissance au fil du temps

Quand l'appel d'outils traditionnel pourrait être préférable :

• Moins de 10 outils au total
• Tous les outils sont fréquemment utilisés dans chaque requête
• Définitions d'outils très petites (<100 tokens au total)

Conseils d'optimisation

• Gardez 3 à 5 outils les plus fréquemment utilisés comme non différés
• Rédigez des noms et 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 que les requêtes de recherche fassent naturellement remonter le 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 prompt système décrivant les catégories d'outils disponibles : "Vous pouvez rechercher des outils pour interagir avec Slack, GitHub et Jira"
• Surveillez quels outils 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
    }
  }
}

Prochaines étapes