claude-code-best-practice/fr/reports/claude-advanced-tool-use.md

Patterns d'usage avancé des outils de Claude

Fonctionnalités au niveau API (désormais GA) qui réduisent la consommation de tokens, la latence et améliorent la précision des outils. Sorties avec Opus/Sonnet 4.6.

← Retour à Claude Code Best Practice

Table des matières

1. Vue d'ensemble
2. Appels d'outils programmatiques (PTC)
3. Filtrage dynamique pour Web Search/Fetch
4. Outil de recherche d'outils (Tool Search Tool)
5. Exemples d'usage d'outils (Tool Use Examples)
6. Pertinence pour Claude Code

---

Vue d'ensemble

Fonctionnalité	Problème résolu	Économie de tokens	Disponibilité
Appels d'outils programmatiques	Les boucles d'agent multi-étapes brûlent des tokens en allers-retours	~37% de réduction	API, Foundry (GA)
Filtrage dynamique	Les résultats de web search/fetch gonflent le contexte de contenu non pertinent	~24% de tokens d'entrée en moins	API, Foundry (GA)
Tool Search Tool	Trop de définitions d'outils gonflent le contexte	~85% de réduction	API, Foundry (GA)
Tool Use Examples	Le schéma seul ne peut exprimer les patterns d'usage	72% → 90% de précision	API, Foundry (GA)

Toutes les fonctionnalités sont disponibles en général (GA) depuis le 18 février 2026.

Empilement stratégique — commence par ton plus gros goulot d'étranglement :

• Gonflement du contexte par les définitions d'outils → Tool Search Tool
• Gros résultats intermédiaires → Appels d'outils programmatiques
• Bruit de web search → Filtrage dynamique
• Erreurs de paramètres → Tool Use Examples

---

Appels d'outils programmatiques (PTC)

Le changement de paradigme

Avant (appels d'outils traditionnels) :

Prompt utilisateur → Claude → Appel d'outil 1 → Réponse 1 → Claude → Appel d'outil 2 → Réponse 2 → Claude → Appel d'outil 3 → Réponse 3 → Claude → Réponse finale

Chaque appel d'outil requiert un aller-retour complet du modèle. 3 outils = 3 passes d'inférence.

Après (appels d'outils programmatiques) :

Prompt utilisateur → Claude → écrit un script Python → Le script appelle Outil 1, Outil 2, Outil 3 en interne → stdout → Claude → Réponse finale

Claude écrit du code qui orchestre tous les outils. Seul le stdout final entre dans la fenêtre de contexte. 3 outils = 1 passe d'inférence.

Comment ça fonctionne

1. Tu définis des outils avec allowed_callers: ["code_execution_20250825"]
2. Claude écrit du Python qui appelle ces outils comme des fonctions async dans un sandbox
3. Quand une fonction d'outil est appelée, le sandbox se met en pause et l'API renvoie un bloc tool_use
4. Tu fournis le résultat de l'outil — il va au code en cours d'exécution, pas au contexte de Claude
5. Le code reprend, traite les résultats, appelle d'autres outils si besoin
6. Seul le stdout de l'exécution finale atteint Claude

Configuration clé

{
  "tools": [
    {
      "type": "code_execution_20250825",
      "name": "code_execution"
    },
    {
      "name": "query_database",
      "description": "Execute a SQL query. Returns rows as JSON objects with fields: id (str), name (str), revenue (float).",
      "input_schema": {
        "type": "object",
        "properties": {
          "sql": { "type": "string", "description": "SQL query to execute" }
        },
        "required": ["sql"]
      },
      "allowed_callers": ["code_execution_20250825"]
    }
  ]
}

Le champ allowed_callers

Valeur	Comportement
["direct"]	Appels d'outils traditionnels uniquement (défaut si omis)
["code_execution_20250825"]	Appelable uniquement depuis le sandbox Python
["direct", "code_execution_20250825"]	Les deux modes disponibles

Recommandation : Choisis un seul mode par outil, pas les deux. Cela donne à Claude un guidage plus clair.

Le champ caller dans les réponses

Chaque bloc d'usage d'outil inclut un champ caller pour que tu saches comment il a été invoqué :

// Direct (traditionnel)
{ "caller": { "type": "direct" } }

// Programmatique (depuis l'exécution de code)
{ "caller": { "type": "code_execution_20250825", "tool_id": "srvtoolu_abc123" } }

Patterns avancés

Traitement par lots — traiter N éléments en 1 passe d'inférence :

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    data = await query_database(f"SELECT SUM(revenue) FROM sales WHERE region='{region}'")
    results[region] = data[0]["revenue"]

top = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top[0]} with ${top[1]:,}")

Terminaison anticipée — s'arrêter dès que les critères de succès sont remplis :

endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
    status = await check_health(endpoint)
    if status == "healthy":
        print(f"Found healthy endpoint: {endpoint}")
        break

Sélection conditionnelle d'outil :

file_info = await get_file_info(path)
if file_info["size"] < 10000:
    content = await read_full_file(path)
else:
    content = await read_file_summary(path)
print(content)

Filtrage de données — réduire ce que Claude voit :

logs = await fetch_logs(server_id)
errors = [log for log in logs if "ERROR" in log]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:
    print(error)

Compatibilité des modèles

Modèle	Supporté
Claude Opus 4.6	Oui
Claude Sonnet 4.6	Oui
Claude Sonnet 4.5	Oui
Claude Opus 4.5	Oui

Contraintes

Contrainte	Détail
Pas sur Bedrock/Vertex	API et Foundry uniquement
Pas d'outils MCP	Les outils de connecteur MCP ne peuvent être appelés programmatiquement
Pas de web search/fetch	Les outils web ne sont pas supportés en PTC
Pas de sorties structurées	Outils strict: true incompatibles
Pas de choix d'outil forcé	tool_choice ne peut forcer le PTC
Durée de vie du conteneur	~4,5 minutes avant expiration
ZDR	Non couvert par le Zero Data Retention
Résultats d'outils sous forme de chaînes	Valide les résultats externes contre les risques d'injection de code

Quand utiliser le PTC

Bons cas d'usage	Moins idéal
Traiter de grands jeux de données nécessitant des agrégats	Appels d'outil unique avec réponses simples
3+ appels d'outils dépendants en séquence	Outils nécessitant un retour utilisateur immédiat
Filtrer/transformer les résultats avant que Claude ne les voie	Opérations très rapides (surcoût > bénéfice)
Opérations parallèles sur de nombreux éléments
Logique conditionnelle basée sur des résultats intermédiaires

Efficacité en tokens

• Les résultats d'outils issus d'appels programmatiques ne sont pas ajoutés au contexte de Claude — seul le stdout final
• Le traitement intermédiaire se passe dans le code, pas en tokens de modèle
• 10 outils en programmatique ≈ 1/10ᵉ des tokens de 10 appels directs

---

Filtrage dynamique pour Web Search/Fetch

Le problème

Les outils de web search et fetch déversent des pages HTML complètes dans la fenêtre de contexte de Claude. La majeure partie de ce contenu est non pertinente — navigation, pubs, boilerplate. Claude raisonne ensuite sur tout cela, gaspillant des tokens et réduisant la précision.

La solution

Claude écrit et exécute désormais du code Python pour filtrer les résultats web avant qu'ils n'entrent dans la fenêtre de contexte. Au lieu de raisonner sur du HTML brut, Claude filtre, parse et extrait uniquement le contenu pertinent dans un sandbox.

Comment ça fonctionne

Avant :

Requête → Résultats de recherche → Récupérer le HTML complet × N pages → Tout le contenu entre en contexte → Claude raisonne sur tout

Après :

Requête → Résultats de recherche → Claude écrit du code de filtrage → Le code extrait uniquement le contenu pertinent → Les résultats filtrés entrent en contexte

Configuration API

Utilise des versions de type d'outil mises à jour avec un en-tête beta :

{
  "model": "claude-opus-4-6",
  "max_tokens": 4096,
  "tools": [
    {
      "type": "web_search_20260209",
      "name": "web_search"
    },
    {
      "type": "web_fetch_20260209",
      "name": "web_fetch"
    }
  ]
}

En-tête requis : anthropic-beta: code-execution-web-tools-2026-02-09

Activé par défaut en utilisant les nouvelles versions de type d'outil avec Sonnet 4.6 et Opus 4.6.

Résultats de benchmark

BrowseComp (trouver des informations spécifiques sur des sites web) :

Modèle	Sans filtrage	Avec filtrage	Amélioration
Sonnet 4.6	33,3%	46,6%	+13,3 pp
Opus 4.6	45,3%	61,6%	+16,3 pp

DeepsearchQA (recherche multi-étapes, score F1) :

Modèle	Sans filtrage	Avec filtrage	Amélioration
Sonnet 4.6	52,6%	59,4%	+6,8 pp
Opus 4.6	69,8%	77,3%	+7,5 pp

Efficacité en tokens : En moyenne 24% de tokens d'entrée en moins. Sonnet 4.6 voit une réduction de coût ; Opus 4.6 peut augmenter légèrement à cause d'un code de filtrage plus complexe.

Cas d'usage

• Passer au crible de la documentation technique
• Vérifier des citations sur plusieurs sources
• Recouper des résultats de recherche
• Requêtes de recherche multi-étapes
• Trouver des données spécifiques enfouies dans de grandes pages

---

Outil de recherche d'outils (Tool Search Tool)

Le problème

Charger toutes les définitions d'outils d'emblée gaspille du contexte. Si tu as 50 outils MCP à ~1,5K tokens chacun, c'est 75K tokens avant même que l'utilisateur ne pose une question.

La solution

Marque les outils peu utilisés avec defer_loading: true. Ils sont exclus du contexte initial. Claude les découvre à la demande via un Tool Search Tool.

Configuration

{
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "google-drive",
      "default_config": { "defer_loading": true },
      "configs": {
        "search_files": { "defer_loading": false }
      }
    }
  ]
}

Bonnes pratiques

• Garde les 3-5 outils les plus utilisés toujours chargés, diffère le reste
• Écris des noms et descriptions d'outils clairs et descriptifs (la recherche s'appuie dessus)
• Documente les capacités disponibles dans le system prompt

Quand l'utiliser

• Définitions d'outils consommant > 10K tokens
• 10+ outils disponibles
• Plusieurs serveurs MCP
• Problèmes de précision de sélection d'outil dus à trop d'options

Économie de tokens

~85% de réduction des tokens de définition d'outils (77K → 8,7K dans les benchmarks d'Anthropic).

Équivalent Claude Code

Claude Code dispose du mode auto de recherche d'outils MCP (activé par défaut depuis v2.1.7). Quand les descriptions d'outils MCP dépassent 10% du contexte, elles sont différées et découvertes via MCPSearch. Configure le seuil avec ENABLE_TOOL_SEARCH=auto:N où N est le pourcentage de contexte (0-100).

---

Exemples d'usage d'outils (Tool Use Examples)

Le problème

Les schémas JSON définissent la structure mais ne peuvent exprimer :

• Quand inclure des paramètres optionnels
• Quelles combinaisons de paramètres ont du sens
• Les conventions de format (formats de date, patterns d'ID)
• L'usage de structures imbriquées

La solution

Ajoute input_examples aux définitions d'outils — des patterns d'usage concrets au-delà du schéma.

Configuration

{
  "name": "create_ticket",
  "description": "Create a support ticket",
  "input_schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
      "assignee": { "type": "string" },
      "labels": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["title"]
  },
  "input_examples": [
    {
      "title": "Login page returns 500 error",
      "priority": "critical",
      "assignee": "oncall-team",
      "labels": ["bug", "auth", "production"]
    },
    {
      "title": "Add dark mode support",
      "priority": "low",
      "labels": ["feature-request", "ui"]
    },
    {
      "title": "Update API docs for v2 endpoints"
    }
  ]
}

Bonnes pratiques

• Utilise des données réalistes, pas des chaînes placeholder comme « example_value »
• Montre de la variété : spécifications minimale, partielle et complète
• Reste concis : 1-5 exemples par outil
• Concentre-toi sur la résolution d'ambiguïté — vise la clarté comportementale plutôt que la complétude du schéma
• Montre les corrélations de paramètres (par ex. priority: "critical" a tendance à avoir un assignee)

Résultats

72% → 90% de précision sur la gestion de paramètres complexes dans les benchmarks d'Anthropic.

---

Pertinence pour Claude Code

Ce qui s'applique directement aux utilisateurs de Claude Code

Fonctionnalité	Statut Claude Code	Action
Tool Search	Intégré depuis v2.1.7 comme mode auto MCPSearch	Règle ENABLE_TOOL_SEARCH=auto:N si tu as beaucoup d'outils MCP
Filtrage dynamique	Non disponible en CLI (outils web au niveau API)	Pertinent pour les utilisateurs de l'Agent SDK faisant de la recherche web
PTC	Non disponible en CLI	Pertinent pour les utilisateurs de l'Agent SDK construisant des agents personnalisés
Tool Use Examples	Non configurable en CLI	Pertinent pour les auteurs de serveurs MCP personnalisés

Pour les développeurs Agent SDK

Si tu construis des agents avec @anthropic-ai/claude-agent-sdk, le PTC est immédiatement actionnable :

1. Ajoute code_execution_20250825 à ton tableau d'outils
2. Définis allowed_callers sur les outils qui bénéficient du batching/filtrage
3. Implémente la boucle de résultat d'outil (pause → fournir le résultat → reprendre)
4. Renvoie des données structurées (JSON) depuis les outils pour un parsing programmatique plus facile

Pour les auteurs de serveurs MCP

Si tu construis des serveurs MCP personnalisés, les Tool Use Examples peuvent améliorer la façon dont Claude utilise tes outils :

• Ajoute input_examples aux schémas d'outils
• Documente clairement les formats de retour dans les descriptions (le PTC doit les parser)

---

Sources

• Anthropic Engineering: Advanced Tool Use
• Documentation Programmatic Tool Calling
• Documentation Code Execution Tool
• Improved Web Search with Dynamic Filtering