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.

<table width="100%">
<tr>
<td><a href="../">← Retour à Claude Code Best Practice</a></td>
<td align="right"><img src="../../!/claude-jumping.svg" alt="Claude" width="60" /></td>
</tr>
</table>

## Table des matières

1. [Vue d'ensemble](#vue-densemble)
2. [Appels d'outils programmatiques (PTC)](#appels-doutils-programmatiques-ptc)
3. [Filtrage dynamique pour Web Search/Fetch](#filtrage-dynamique-pour-web-searchfetch)
4. [Outil de recherche d'outils (Tool Search Tool)](#outil-de-recherche-doutils-tool-search-tool)
5. [Exemples d'usage d'outils (Tool Use Examples)](#exemples-dusage-doutils-tool-use-examples)
6. [Pertinence pour Claude Code](#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)

<img src="../../reports/assets/programmatic-tool-calling-diagram.svg" alt="Diagramme PTC — Appels d'outils traditionnels vs programmatiques" width="100%" />

### 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é

```json
{
  "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é :

```json
// 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 :
```python
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 :
```python
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 :**
```python
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 :
```python
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 :

```json
{
  "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

```json
{
  "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

```json
{
  "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](https://www.anthropic.com/engineering/advanced-tool-use)
- [Documentation Programmatic Tool Calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)
- [Documentation Code Execution Tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)
- [Improved Web Search with Dynamic Filtering](https://claude.com/blog/improved-web-search-with-dynamic-filtering)