Outils

Outil de recherche d'outils

Permettez à Claude de découvrir et charger dynamiquement des outils à la demande pour travailler avec des centaines ou des milliers 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 charge uniquement les outils dont il a besoin.

Cette approche résout deux défis critiques à mesure que les bibliothèques d'outils se développent :

Efficacité du contexte : Les définitions d'outils peuvent consommer des portions massives de votre fenêtre de contexte (50 outils ≈ 10-20K tokens), laissant moins de place pour le travail réel
Précision de la sélection d'outils : La capacité de Claude à sélectionner correctement les outils se dégrade considérablement avec plus de 30-50 outils disponibles conventionnellement

Bien que ceci 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 la recherche d'outils pour plus de détails.

L'outil de recherche d'outils est actuellement en bêta publique.

Pour utiliser cette fonctionnalité, ajoutez l'en-tête bêta "advanced-tool-use-2025-11-20" beta header à vos requêtes API.

Veuillez nous contacter via notre formulaire de retours pour partager votre expérience avec l'outil de recherche d'outils.

Support des plateformes et des modèles

Plateforme	Modèles supportés
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

Sur Amazon Bedrock, la recherche d'outils côté serveur est disponible uniquement via l'API invoke, pas l'API converse.

Vous pouvez également implémenter la recherche d'outils côté client en retournant 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 :

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
Vous fournissez toutes les définitions d'outils avec defer_loading: true pour les outils qui ne doivent pas être chargés immédiatement
Claude voit uniquement l'outil de recherche d'outils et tous les outils non différés initialement
Lorsque Claude a besoin d'outils supplémentaires, il effectue une recherche en utilisant un outil de recherche d'outils
L'API retourne 3-5 blocs tool_reference les plus pertinents
Ces références sont automatiquement développées en définitions d'outils complètes
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 :

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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 :

JSON

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

JSON

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

Format de requête de la variante Regex : Expression régulière Python, PAS langage naturel

Lors de l'utilisation de tool_search_tool_regex_20251119, Claude construit des motifs regex en utilisant la syntaxe re.search() de Python, pas des requêtes en langage naturel. Motifs courants :

"weather" - correspond aux noms/descriptions d'outils contenant "weather"
"get_.*_data" - correspond aux outils comme get_user_data, get_weather_data
"database.*query|query.*database" - motifs OR pour la flexibilité
"(?i)slack" - recherche insensible à la casse

Longueur maximale de la requête : 200 caractères

Format de requête de la variante BM25 : Langage naturel

Lors de l'utilisation de tool_search_tool_bm25_20251119, Claude utilise des requêtes en langage naturel pour rechercher des outils.

Chargement différé des outils

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

JSON

{
  "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 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 les noms d'outils, les descriptions, les noms d'arguments et les descriptions d'arguments.

Format de réponse

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

JSON

{
  "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_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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_result avec tool_reference : Les résultats de recherche contenant des références aux 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

L'outil de recherche d'outils fonctionne avec les serveurs MCP. Ajoutez l'en-tête bêta "mcp-client-2025-11-20" beta header à votre requête API, puis utilisez mcp_tool_set avec default_configs pour différer le chargement des outils MCP :

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

Options de configuration MCP :

default_configs.defer_loading : Définir la valeur par défaut pour tous les outils du serveur MCP
configs : Remplacer les valeurs par défaut pour des outils spécifiques par nom
Combinez plusieurs serveurs MCP avec la recherche d'outils pour des bibliothèques d'outils massives

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 la recherche sémantique) en retournant des blocs tool_reference à partir d'un outil personnalisé :

JSON

{
  "type": "tool_result",
  "tool_use_id": "toolu_custom_search",
  "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 notre cookbook de recherche d'outils avec embeddings.

Gestion des erreurs

L'outil de recherche d'outils n'est pas compatible avec les exemples d'utilisation d'outils. Si vous avez besoin de fournir des exemples d'utilisation d'outils, utilisez l'appel d'outils standard sans recherche d'outils.

Erreurs HTTP (statut 400)

Ces erreurs empêchent la requête d'être traitée :

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 :

JSON

{
  "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 invites

La recherche d'outils fonctionne avec la mise en cache des invites. Ajoutez des points de rupture cache_control pour optimiser les conversations multi-tours :

Python

import anthropic

client = anthropic.Anthropic()

# First request with tool search
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Add Claude's response to conversation
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Second request with cache breakpoint
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

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

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_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude continues with discovered tools

Requêtes 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 des requêtes API Messages régulières.

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 des modèles : 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)
Bibliothèque d'outils croissante 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 requête
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 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 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 pour affiner les descriptions

Utilisation et tarification

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

JSON

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

Pour les informations de tarification actuelles, consultez la page de tarification.

Outils

Outil de recherche d'outils

Permettez à Claude de découvrir et charger dynamiquement des outils à la demande pour travailler avec des centaines ou des milliers d'outils.

Cette approche résout deux défis critiques à mesure que les bibliothèques d'outils se développent :

Efficacité du contexte : Les définitions d'outils peuvent consommer des portions massives de votre fenêtre de contexte (50 outils ≈ 10-20K tokens), laissant moins de place pour le travail réel
Précision de la sélection d'outils : La capacité de Claude à sélectionner correctement les outils se dégrade considérablement avec plus de 30-50 outils disponibles conventionnellement

L'outil de recherche d'outils est actuellement en bêta publique.

Pour utiliser cette fonctionnalité, ajoutez l'en-tête bêta "advanced-tool-use-2025-11-20" beta header à vos requêtes API.

Veuillez nous contacter via notre formulaire de retours pour partager votre expérience avec l'outil de recherche d'outils.

Support des plateformes et des modèles

Plateforme	Modèles supportés
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

Sur Amazon Bedrock, la recherche d'outils côté serveur est disponible uniquement via l'API invoke, pas l'API converse.

Vous pouvez également implémenter la recherche d'outils côté client en retournant 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 :

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
Vous fournissez toutes les définitions d'outils avec defer_loading: true pour les outils qui ne doivent pas être chargés immédiatement
Claude voit uniquement l'outil de recherche d'outils et tous les outils non différés initialement
Lorsque Claude a besoin d'outils supplémentaires, il effectue une recherche en utilisant un outil de recherche d'outils
L'API retourne 3-5 blocs tool_reference les plus pertinents
Ces références sont automatiquement développées en définitions d'outils complètes
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 :

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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 :

JSON

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

JSON

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

Format de requête de la variante Regex : Expression régulière Python, PAS langage naturel

Lors de l'utilisation de tool_search_tool_regex_20251119, Claude construit des motifs regex en utilisant la syntaxe re.search() de Python, pas des requêtes en langage naturel. Motifs courants :

"weather" - correspond aux noms/descriptions d'outils contenant "weather"
"get_.*_data" - correspond aux outils comme get_user_data, get_weather_data
"database.*query|query.*database" - motifs OR pour la flexibilité
"(?i)slack" - recherche insensible à la casse

Longueur maximale de la requête : 200 caractères

Format de requête de la variante BM25 : Langage naturel

Lors de l'utilisation de tool_search_tool_bm25_20251119, Claude utilise des requêtes en langage naturel pour rechercher des outils.

Chargement différé des outils

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

JSON

{
  "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 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 les noms d'outils, les descriptions, les noms d'arguments et les descriptions d'arguments.

Format de réponse

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

JSON

{
  "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_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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_result avec tool_reference : Les résultats de recherche contenant des références aux outils découverts
tool_use : Claude invoquant l'outil découvert

Intégration MCP

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

Options de configuration MCP :

default_configs.defer_loading : Définir la valeur par défaut pour tous les outils du serveur MCP
configs : Remplacer les valeurs par défaut pour des outils spécifiques par nom
Combinez plusieurs serveurs MCP avec la recherche d'outils pour des bibliothèques d'outils massives

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

JSON

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

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

Gestion des erreurs

Erreurs HTTP (statut 400)

Ces erreurs empêchent la requête d'être traitée :

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 :

JSON

{
  "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 invites

La recherche d'outils fonctionne avec la mise en cache des invites. Ajoutez des points de rupture cache_control pour optimiser les conversations multi-tours :

Python

import anthropic

client = anthropic.Anthropic()

# First request with tool search
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Add Claude's response to conversation
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Second request with cache breakpoint
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

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_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude continues with discovered tools

Requêtes par lot

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 des modèles : 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)
Bibliothèque d'outils croissante 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 requête
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 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 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 pour affiner les descriptions

Utilisation et tarification

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

JSON

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

Pour les informations de tarification actuelles, consultez la page de tarification.

Support des plateformes et des modèles

Comment fonctionne la recherche d'outils

Démarrage rapide

Définition de l'outil

Chargement différé des outils

Format de réponse

Comprendre la réponse

Intégration MCP

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

Gestion des erreurs

Erreurs HTTP (statut 400)

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

Erreurs courantes

Erreur 400 : Tous les outils sont différés

Erreur 400 : Définition d'outil manquante

Claude ne trouve pas les outils attendus

Mise en cache des invites

Streaming

Requêtes par lot

Limites et meilleures pratiques

Limites

Quand utiliser la recherche d'outils

Conseils d'optimisation

Utilisation et tarification

Support des plateformes et des modèles

Comment fonctionne la recherche d'outils

Démarrage rapide

Définition de l'outil

Chargement différé des outils

Format de réponse

Comprendre la réponse

Intégration MCP

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

Gestion des erreurs

Erreurs HTTP (statut 400)

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

Erreurs courantes

Erreur 400 : Tous les outils sont différés

Erreur 400 : Définition d'outil manquante

Claude ne trouve pas les outils attendus

Mise en cache des invites

Streaming

Requêtes par lot

Limites et meilleures pratiques

Limites

Quand utiliser la recherche d'outils

Conseils d'optimisation

Utilisation et tarification