Accueil / L'API Claude pour ceux qui construisent

Les outils, Claude propose, le code dispose

Un outil se déclare par un schéma nommé input_schema ; Claude ne l'exécute jamais lui même, il renvoie une demande d'usage que le code exécute avant de renvoyer le résultat pour que la conversation continue.

Claude n'exécute jamais un outil lui même. Il renvoie une demande d'usage, le code du développeur l'exécute réellement, puis renvoie le résultat pour que la conversation continue. Ce cycle repose sur un seul contrat : le schéma déclaré par le champ input_schema.

La déclaration d'un outil

Un outil se déclare par trois champs de premier niveau : name, description et input_schema, ce dernier décrivant la forme attendue des arguments. Un quatrième champ, strict, se place aux côtés des trois premiers et non sur le choix d'outil : passé à true, il garantit que l'appel produit par Claude correspond exactement au schéma déclaré, à condition que ce schéma porte aussi additionalProperties à false aux côtés de required, la forme que la documentation officielle applique dans tous ses exemples.

// Déclaration d'un outil, avec validation stricte du schéma
{
  "name": "verifier_stock",
  "description": "Renvoie la quantité disponible pour une référence produit.",
  "input_schema": {
    "type": "object",
    "properties": {
      "reference": { "type": "string" }
    },
    "required": ["reference"],
    "additionalProperties": false
  },
  "strict": true
}

Le cycle complet, de la demande au résultat

Quand Claude choisit d'utiliser un outil, il renvoie un stop_reason de valeur tool_use, accompagné d'un ou plusieurs blocs tool_use qui portent les arguments choisis. Le code exécute alors l'appel réel décrit par ce bloc, puis renvoie le résultat dans un bloc tool_result, placé à l'intérieur d'un message de rôle user. Quand plusieurs outils sont demandés dans le même tour, ce qui arrive par défaut puisque les appels parallèles sont actifs, tous leurs blocs tool_result reviennent ensemble dans ce seul message.

// Demande d'usage renvoyée par Claude
{
  "stop_reason": "tool_use",
  "content": [
    { "type": "tool_use", "id": "toolu_01", "name": "verifier_stock",
      "input": { "reference": "REF-042" } }
  ]
}

// Résultat renvoyé par le code dans le tour suivant
{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 unités disponibles" }
  ]
}

Le champ tool_choice pilote quel outil Claude peut choisir : auto par défaut laisse Claude décider, any force l'usage d'un outil sans en imposer le nom, tool impose un outil précis, et none l'empêche d'en utiliser un. Choisir none sans déclarer aucun outil n'ajoute aucun jeton de système supplémentaire à la requête. Le bloc tool_result renvoyé ici suit la même structure de message que la requête de base, avec un tableau messages qui continue d'alterner les rôles.