Accueil › Glossaire › Function Schema

Function Schema

Le function schema est la description formelle en JSON Schema des paramètres d’entrée d’une fonction (outil) que le LLM peut appeler via le mécanisme de function calling. Il définit le nom, la description, les types de paramètres et les contraintes de chaque outil mis à disposition du modèle.

À quoi sert un function schema

Quand vous mettez un outil à disposition d’un LLM (une fonction de recherche, un accès base de données, un appel API externe), le modèle a besoin de savoir trois choses : quand utiliser cet outil (sa description), quels paramètres lui fournir (le schéma), et quels sont les types et contraintes de chaque paramètre. Le function schema fournit ces informations de manière formelle et parsable.

Le LLM ne « comprend » pas votre code. Il ne voit que le nom de la fonction, sa description en langage naturel, et le schéma JSON de ses paramètres. C’est à partir de ces seules informations qu’il décide quand appeler l’outil et quels arguments générer. La qualité du function schema est donc le facteur le plus déterminant pour la fiabilité du function calling.

Anatomie d’un function schema

Un function schema se compose de quatre éléments principaux :

Syntaxe par provider

OpenAI

Chez OpenAI, les outils sont définis dans le tableau tools avec "type": "function". Le schéma des paramètres est dans la clé parameters :

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_products",
        "description": "Recherche des produits dans le catalogue par mots-clés et filtres. Utiliser quand l'utilisateur cherche un produit spécifique ou veut explorer le catalogue.",
        "strict": true,
        "parameters": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Termes de recherche (ex: 'chaussures running homme')"
            },
            "category": {
              "type": "string",
              "enum": ["electronics", "clothing", "home", "sports"],
              "description": "Catégorie de produit pour filtrer les résultats"
            },
            "max_price": {
              "type": "number",
              "description": "Prix maximum en euros (optionnel)"
            },
            "in_stock": {
              "type": "boolean",
              "description": "Filtrer uniquement les produits en stock"
            }
          },
          "required": ["query"],
          "additionalProperties": false
        }
      }
    }
  ]
}

Anthropic

Chez Anthropic, la structure est similaire mais les clés diffèrent. Le schéma utilise input_schema au lieu de parameters, et les outils ne sont pas encapsulés dans un objet function :

{
  "tools": [
    {
      "name": "search_products",
      "description": "Recherche des produits dans le catalogue par mots-clés et filtres. Utiliser quand l'utilisateur cherche un produit spécifique ou veut explorer le catalogue.",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Termes de recherche (ex: 'chaussures running homme')"
          },
          "category": {
            "type": "string",
            "enum": ["electronics", "clothing", "home", "sports"],
            "description": "Catégorie de produit pour filtrer les résultats"
          },
          "max_price": {
            "type": "number",
            "description": "Prix maximum en euros (optionnel)"
          },
          "in_stock": {
            "type": "boolean",
            "description": "Filtrer uniquement les produits en stock"
          }
        },
        "required": ["query"],
        "additionalProperties": false
      }
    }
  ]
}

La description : l’élément le plus important

C’est le point que la plupart des développeurs sous-estiment : la description en langage naturel de la fonction est plus déterminante que la complexité du schéma pour la fiabilité du tool calling. Le LLM utilise la description pour décider quand appeler l’outil. Une description vague ("Fait des trucs avec les produits") conduit à des appels incorrects ou manqués. Une description précise ("Recherche des produits dans le catalogue par mots-clés. Utiliser uniquement quand l'utilisateur veut trouver ou explorer des produits. Ne pas utiliser pour des questions générales sur la politique de retour.") produit un comportement fiable.

Les mêmes principes s’appliquent aux descriptions de paramètres. Chaque propriété du schéma devrait inclure une description qui explique ce que le paramètre représente, son format attendu, et idéalement un exemple. Le modèle utilise ces descriptions pour remplir les paramètres correctement. Sans description, il devine à partir du nom de la propriété, ce qui est fragile.

Types JSON Schema supportés

Les function schemas utilisent un sous-ensemble de JSON Schema. Les types couramment supportés par les providers LLM sont :

Les restrictions varient par provider. En strict mode chez OpenAI, les schémas récursifs ne sont pas supportés, additionalProperties doit être false, et la profondeur maximale est de 5 niveaux d’imbrication. Chez Anthropic, les contraintes sont similaires mais la profondeur est moins restrictive. Consultez la documentation de chaque provider pour les restrictions exactes.

Strict mode : quand et pourquoi

Le strict mode ("strict": true) force le modèle à générer des arguments qui respectent exactement le schéma, sans paramètres inventés ni types incorrects. Sans strict mode, le modèle peut halluciner des paramètres qui n’existent pas dans le schéma (par exemple, ajouter un champ language alors qu’il n’est pas défini). Avec strict mode, cette hallucination est physiquement impossible.

Activez toujours le strict mode en production. La seule raison de ne pas l’utiliser est si votre schéma utilise des fonctionnalités JSON Schema non supportées en strict mode (comme les schémas récursifs ou certains patrons oneOf/anyOf). Dans ce cas, simplifiez votre schéma pour le rendre compatible avec le strict mode plutôt que de désactiver la contrainte.

Relation avec la tool definition

Le function schema est un composant de la tool definition. La tool definition englobe le function schema (paramètres) mais aussi des métadonnées supplémentaires selon le provider : le type d’outil (function, server tool, computer use), les configurations de cache, et les options de comportement. Le function schema se concentre spécifiquement sur la description des paramètres d’entrée de l’outil.

Dans le contexte du protocole MCP (Model Context Protocol), les function schemas sont standardisés : un serveur MCP expose ses outils avec des schémas JSON Schema que n’importe quel client MCP compatible peut consommer, indépendamment du provider LLM utilisé. C’est l’un des avantages clés de MCP : un seul schéma d’outil fonctionne avec Claude, GPT-5.4, Gemini ou tout autre modèle compatible.

Génération automatique de schemas

Écrire des function schemas à la main est fastidieux et source d’erreurs. Plusieurs approches permettent de les générer automatiquement :

Depuis les types Python (Pydantic). Définissez un modèle Pydantic et utilisez .model_json_schema() pour générer le JSON Schema correspondant. C’est l’approche recommandée par OpenAI dans son SDK Python. L’Anthropic Agents SDK et l’OpenAI Agents SDK utilisent la même technique avec leur méthode function_schema().

Depuis les types TypeScript (Zod). Définissez un schéma Zod et convertissez-le en JSON Schema avec zodToJsonSchema(). La bibliothèque Schema Forge offre une conversion directe de classes TypeScript vers les formats OpenAI, Anthropic et Gemini.

Depuis les docstrings Python. L’OpenAI Agents SDK peut extraire automatiquement le nom, la description et les paramètres d’une fonction Python à partir de sa signature et de sa docstring, sans écrire de JSON Schema manuellement.

Patterns de conception pour les function schemas

Pattern : fonctions spécifiques vs génériques

Préférez plusieurs fonctions spécifiques à une seule fonction générique. Un outil manage_database avec un paramètre action: "read"|"write"|"delete"|"update" est plus difficile à utiliser correctement pour le modèle qu’un ensemble de fonctions dédiées : read_record, write_record, delete_record, update_record. Chaque fonction spécifique a une description ciblée, un schéma de paramètres adapté, et des contraintes propres. Le modèle sélectionne la bonne fonction plus facilement.

Pattern : utiliser les enums généreusement

Chaque paramètre qui accepte un ensemble fini de valeurs devrait être typé enum. Au lieu de "sort_order": {"type": "string"} (le modèle peut inventer « ascending », « asc », « up », « ASC »), utilisez "sort_order": {"type": "string", "enum": ["asc", "desc"]}. L’enum contraint physiquement la sortie aux valeurs autorisées, éliminant les erreurs de valeur. En strict mode, cette contrainte est garantie à 100 %.

Pattern : descriptions orientées usage

Rédigez les descriptions comme si vous expliquiez l’outil à un nouveau développeur. Incluez : quand utiliser la fonction, quand NE PAS l’utiliser, et un exemple d’appel. Exemple : « Recherche des tickets de support par mots-clés. Utiliser quand l’utilisateur demande l’historique d’un problème ou veut retrouver un ticket. Ne PAS utiliser pour créer un nouveau ticket (utiliser create_ticket à la place). Exemple : search_tickets(query=’problème de connexion VPN’, status=’open’) ».

Pattern : paramètres optionnels explicites

Pour les paramètres optionnels, ne vous contentez pas de les exclure du tableau required. Ajoutez dans la description que le paramètre est optionnel et précisez le comportement par défaut quand il est absent. Exemple : "max_results": {"type": "integer", "description": "Nombre maximum de résultats (optionnel, défaut: 10, max: 100)"}. Cela aide le modèle à décider quand inclure ou omettre le paramètre.

Function schemas et MCP

Le protocole MCP (Model Context Protocol) standardise la façon dont les outils sont exposés aux LLM. Un serveur MCP publie ses outils avec des function schemas JSON Schema standard, et n’importe quel client MCP (Claude Code, Cursor, des applications custom) peut les consommer. La force du MCP est l’interopérabilité : vous écrivez un function schema une seule fois, et il fonctionne avec n’importe quel LLM compatible MCP.

En pratique, les function schemas MCP suivent le même format JSON Schema que les schemas Anthropic (input_schema). Si vous avez déjà des schemas pour l’API Anthropic, ils sont directement compatibles MCP. La documentation de chaque serveur MCP inclut les schemas de ses outils, que vous pouvez inspecter pour comprendre les paramètres attendus et les adapter à vos besoins.

Des bibliothèques comme Schema Forge (TypeScript) permettent de générer des schemas compatibles simultanément avec OpenAI, Anthropic, Gemini et MCP depuis une source unique (classes TypeScript ou JSON Schema). C’est l’approche recommandée quand votre application doit fonctionner avec plusieurs providers ou protocoles.

Erreurs courantes

Les échecs de tool calling les plus fréquents sont liés à la qualité du function schema, pas à la capacité du modèle. Les descriptions vagues ou absentes conduisent le modèle à appeler le mauvais outil ou à ne pas reconnaître quand un outil est pertinent. Les paramètres sans description sont remplis par le modèle en devinant à partir du nom, ce qui est fragile. Les schémas trop complexes (15+ paramètres, imbrications profondes) confusent le modèle et augmentent le taux d’erreur. L’absence de required laisse le modèle libre d’omettre des paramètres essentiels. L’absence d’enum sur les paramètres à valeurs prédéfinies permet au modèle d’inventer des valeurs non supportées.

Verdict

Le function schema est le contrat entre votre code et le LLM. Sa qualité détermine la fiabilité de vos outils. Investissez dans des descriptions précises (fonction et paramètres), utilisez le strict mode, limitez la complexité (5 à 8 paramètres maximum par fonction), et générez vos schemas automatiquement depuis vos types Python/TypeScript. Un outil avec un function schema bien documenté sera correctement appelé par le modèle dans 99 % des cas. Un outil avec un schéma vague sera une source permanente de bugs.