Accueil › Glossaire › Tool Definition

Tool Definition

La tool definition (définition d’outil) est la déclaration complète d’un outil mis à disposition d’un LLM dans une requête API, incluant son nom, sa description, son schéma de paramètres (function schema), et ses métadonnées de configuration. C’est l’objet que vous passez dans le tableau tools de l’API pour rendre un outil accessible au modèle.

Rôle de la tool definition

La tool definition est ce qui transforme un LLM de générateur de texte en agent capable d’agir. Sans tool definitions, le modèle ne peut que produire du texte. Avec des tool definitions, il peut décider d’appeler une API externe, interroger une base de données, effectuer un calcul, lancer une recherche web, ou piloter une interface utilisateur.

Concrètement, les tool definitions sont envoyées dans la requête API via le tableau tools. Le modèle lit ces définitions, comprend quels outils sont disponibles, et décide au moment de la génération s’il a besoin d’en utiliser un pour répondre à la question de l’utilisateur. S’il décide d’utiliser un outil, il génère un assistant message contenant un bloc tool_use avec le nom de l’outil et les arguments, conformes au function schema défini.

Types d’outils

Les providers LLM supportent plusieurs types d’outils, qui se distinguent par leur mode d’exécution :

Client tools (outils personnalisés)

Ce sont les outils que vous définissez vous-même. Le modèle génère un appel structuré (nom + arguments), votre code exécute la fonction côté client/serveur, et vous renvoyez le résultat au modèle. C’est le type d’outil le plus courant et le plus flexible.

Exemples : interroger votre API métier, accéder à une base de données interne, envoyer un e-mail, créer un ticket, calculer un prix, manipuler un fichier. Tout ce que votre code peut faire peut être exposé comme client tool.

// Client tool : recherche dans une base de connaissances
{
  "name": "search_knowledge_base",
  "description": "Recherche dans la base de connaissances interne de l'entreprise. Utiliser quand l'utilisateur pose une question sur les procédures, politiques ou documentation interne.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Requête de recherche en langage naturel"
      },
      "department": {
        "type": "string",
        "enum": ["hr", "engineering", "sales", "legal", "finance"],
        "description": "Département pour filtrer les résultats (optionnel)"
      }
    },
    "required": ["query"],
    "additionalProperties": false
  }
}

Server tools (outils côté serveur)

Chez Anthropic, les server tools sont des outils exécutés automatiquement côté serveur d’Anthropic, sans que votre code ait à gérer le cycle tool_use/tool_result. Le modèle appelle l’outil, Anthropic l’exécute, et le résultat est automatiquement intégré dans la réponse.

Les principaux server tools d’Anthropic en mars 2026 sont :

Les server tools utilisent des types versionnés (comme web_search_20250305) pour garantir la compatibilité entre les versions de l’API. Ils sont déclarés dans le tableau tools mais avec une structure différente des client tools :

// Server tool : recherche web (Anthropic)
{
  "tools": [
    {
      "type": "web_search_20250305",
      "name": "web_search"
    }
  ]
}

Le serveur d’Anthropic exécute ces outils dans une boucle interne (limite par défaut : 10 itérations). Votre code n’a pas besoin de gérer le cycle d’appel manuellement.

Computer use tools

Les outils de « computer use » permettent au LLM de piloter un écran d’ordinateur : prendre des captures d’écran, cliquer, taper du texte, faire défiler. Chez Anthropic et OpenAI, ces outils sont déclarés comme des tool definitions spécifiques. GPT-5.4 et Claude Opus 4.6 supportent nativement le computer use, principalement utilisé dans les systèmes agentiques comme Claude Cowork ou ChatGPT Operator.

Structure complète par provider

OpenAI

Chez OpenAI, chaque tool definition est un objet avec "type": "function" et un objet function contenant le nom, la description et les paramètres :

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Récupère le statut d'une commande par son numéro.",
        "strict": true,
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "Numéro de commande (format: ORD-XXXXX)"
            }
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      }
    }
  ]
}

Anthropic

Chez Anthropic, la structure est plus plate : pas d’enveloppe "type": "function", et les paramètres utilisent la clé input_schema :

{
  "tools": [
    {
      "name": "get_order_status",
      "description": "Récupère le statut d'une commande par son numéro.",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "Numéro de commande (format: ORD-XXXXX)"
          }
        },
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  ]
}

Contrôler la sélection d’outils

Le paramètre tool_choice contrôle comment le modèle utilise les outils définis :

Le mode auto est recommandé dans la plupart des cas. Utilisez any/required quand l’outil doit toujours être appelé (par exemple, un outil de classification obligatoire). Utilisez le forçage d’un outil spécifique principalement pour le workaround structured output (forcer le modèle à « appeler » un outil fictif pour obtenir du JSON structuré).

Impact des tool definitions sur les tokens

Les tool definitions sont comptées dans les tokens d’entrée à chaque requête. Un outil avec une description détaillée et un schéma complexe peut facilement consommer 200 à 500 tokens. Si vous définissez 10 outils, c’est 2 000 à 5 000 tokens d’entrée juste pour les définitions d’outils, avant même d’ajouter le system prompt et l’historique.

Le prompt caching est particulièrement bénéfique pour les tool definitions, car elles sont identiques d’une requête à l’autre. Chez Anthropic, placez les tool definitions et le system prompt en début de requête (ils constituent le préfixe stable) pour maximiser les cache hits. Chez Anthropic, vous pouvez aussi ajouter un cache_control explicite sur les outils pour contrôler le caching.

Tool definitions et MCP

Le protocole MCP (Model Context Protocol) standardise les tool definitions à travers les providers et les plateformes. Un serveur MCP expose ses outils via un endpoint standardisé, et n’importe quel client MCP (Claude Code, Cursor, applications custom) peut les consommer automatiquement.

L’avantage majeur est l’interopérabilité : un serveur MCP pour Slack, par exemple, expose les mêmes tool definitions que vous utilisez avec Claude, GPT-5.4, ou n’importe quel autre LLM compatible. Vous n’avez pas à réécrire vos tool definitions pour chaque provider. Le format des tool definitions MCP est aligné sur le format Anthropic (input_schema), ce qui facilite la transition.

En mars 2026, l’écosystème MCP compte des centaines de serveurs pour des services populaires (Slack, Jira, Google Drive, Salesforce, GitHub, etc.), chacun exposant ses propres tool definitions standardisées. Les plateformes comme Claude.ai, Claude Code et Cursor intègrent nativement ces serveurs MCP, rendant les outils disponibles sans configuration manuelle des tool definitions.

Évolution des tool definitions : 2023 à 2026

Le concept de tool definition a considérablement évolué en trois ans. En juin 2023, OpenAI lance le « function calling » avec GPT-3.5 et GPT-4. Les tool definitions sont alors limitées à des fonctions custom avec un schéma JSON simple. Le modèle génère un appel structuré, mais sans garantie de conformité au schéma (pas de strict mode).

En 2024, Anthropic introduit le tool use pour Claude 3, avec une syntaxe légèrement différente (input_schema au lieu de parameters) mais un fonctionnement similaire. Les deux providers ajoutent le strict mode, qui garantit que les arguments générés respectent exactement le schéma. OpenAI lance les structured outputs (août 2024), qui étendent le concept de conformité schéma aux réponses textuelles, pas seulement aux appels d’outils.

En 2025, l’écosystème s’enrichit considérablement. Anthropic lance les server tools (recherche web, code execution) qui s’exécutent côté serveur sans intervention du développeur. Le protocole MCP standardise les tool definitions pour l’interopérabilité cross-provider. Les frameworks agentiques (Anthropic Agents SDK, OpenAI Agents SDK) introduisent la génération automatique de tool definitions depuis les signatures de fonctions Python.

En mars 2026, les tool definitions sont au cœur de l’architecture agentique. Claude Opus 4.6 supporte le computer use natif (l’écran comme outil), les Agent Teams (coordination de sous-agents comme outils), et le prompt caching optimisé pour les tool definitions volumineuses. GPT-5.4 unifie toutes ses capacités (code, outils, computer use) dans un modèle unique. La tendance est claire : les tool definitions deviennent le « code source » des agents IA, aussi importantes que le system prompt pour définir le comportement du système.

Considérations de sécurité

Les tool definitions ouvrent une surface d’attaque spécifique. Le modèle décide quand et comment appeler vos outils sur la base de l’entrée utilisateur. Un utilisateur malveillant peut tenter de manipuler le modèle pour qu’il appelle un outil de manière non prévue (exfiltration de données via un outil de recherche, modification non autorisée via un outil d’écriture).

Les mesures d’atténuation sont essentielles. Premièrement, validez toujours les arguments côté serveur avant d’exécuter l’outil. Ne faites pas confiance aux arguments générés par le modèle, même avec le strict mode (qui garantit la structure, pas la légitimité). Deuxièmement, implémentez des contrôles d’autorisation : vérifiez que l’utilisateur actuel a le droit d’exécuter l’action demandée. Le modèle ne gère pas l’authentification ni l’autorisation. Troisièmement, limitez la portée des outils au minimum nécessaire. Un outil execute_sql qui accepte n’importe quelle requête SQL est un risque de sécurité majeur. Préférez des outils spécialisés (get_user_orders) avec des paramètres contrôlés.

Quatrièmement, ajoutez des rate limits sur les appels d’outils pour empêcher les boucles infinies. Le modèle peut parfois entrer dans une boucle d’appels d’outils répétitifs. Définissez un nombre maximum d’appels d’outils par conversation (10 à 20 est un seuil raisonnable) et interrompez la génération si ce seuil est atteint.

Bonnes pratiques

Limitez le nombre d’outils. Plus vous définissez d’outils, plus le modèle doit « réfléchir » à lequel utiliser, et plus le risque de sélection incorrecte augmente. Visez 5 à 15 outils maximum par requête. Si votre application en nécessite plus, utilisez un système de routage qui sélectionne dynamiquement les outils pertinents pour chaque requête.

Documentez comme pour un développeur junior. Rédigez les descriptions de tool definitions comme si vous les expliquiez à un nouveau développeur qui ne connaît pas votre système. Incluez : quand utiliser l’outil, quand NE PAS l’utiliser, un exemple d’appel typique, et le format des résultats attendus.

Activez le strict mode. Sauf contrainte technique, activez "strict": true sur toutes vos tool definitions. Cela empêche le modèle d’inventer des paramètres qui n’existent pas dans votre schéma, éliminant une catégorie entière de bugs.

Validez les arguments avant exécution. Même avec le strict mode, validez les arguments côté serveur avant d’exécuter l’outil. Le strict mode garantit la structure (bons champs, bons types), mais pas la validité sémantique (un order_id structurellement correct peut ne pas exister dans votre base).

Renvoyez des erreurs exploitables. Quand un outil échoue, renvoyez un message d’erreur clair dans le tool_result que le modèle peut comprendre et communiquer à l’utilisateur. « Erreur : commande ORD-12345 introuvable. Vérifiez le numéro de commande. » est nettement plus utile que « Error 404 ». Chez Anthropic, ajoutez "is_error": true au bloc tool_result pour signaler explicitement une erreur.

Verdict

La tool definition est la brique fondamentale du function calling et de l’architecture agentique. Elle transforme un LLM de générateur de texte en agent capable d’agir sur le monde. La qualité de vos tool definitions (descriptions précises, schémas stricts, nombre maîtrisé) détermine directement la fiabilité de votre système. Avec la standardisation MCP, l’écosystème d’outils est de plus en plus riche et interopérable. C’est le moment d’investir dans des tool definitions de qualité production : elles sont le code source de vos agents IA.