tool-calling-architect

Tool Calling Architect

Critères de décision : quel pattern choisir ?

Situation	Pattern recommandé
Outil ponctuel dans un seul agent	Function calling inline (JSON schema dans le prompt)
Outil partagé entre plusieurs agents	MCP Server (stdio ou HTTP+SSE)
Enchaînement prévisible de 3+ étapes	Pipeline déterministe, pas tool chaining LLM
Actions parallèles indépendantes	Parallel tool calling natif (OpenAI/Anthropic)
Outil exposé à des LLMs tiers/clients	MCP Server avec authentification
Wrapping d'API REST existante	Tool = thin wrapper + validation Pydantic

---

Workflow en 10 étapes

1. Définir le contrat de l'outil

Avant d'écrire du code, complète cette fiche :

• Nom : snake_case explicite (get_invoice_by_id, pas get_data)
• Description : une phrase claire sur CE QUE l'outil fait + QUAND l'utiliser (le LLM lit cette phrase pour décider d'appeler ou non)
• Inputs : chaque paramètre typé, obligatoire ou optionnel, avec valeurs autorisées si enum
• Output : format de retour standardisé (status, data ou error)
• Effets de bord : lecture seule ? écriture ? irréversible ?

Règle : si la description de l'outil est ambiguë pour un développeur humain, elle le sera aussi pour le LLM.

---

2. Rédiger le JSON Schema

Format OpenAI-compatible (compatible Anthropic, Gemini, Mistral) :

SEARCH_WEB_SCHEMA = {
    "name": "search_web",
    "description": (
        "Recherche des informations récentes sur le web. "
        "Utilise cet outil uniquement quand tu as besoin d'informations "
        "publiées après ta date de coupure ou de données factuelles précises."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Requête en langage naturel, la plus spécifique possible"
            },
            "max_results": {
                "type": "integer",
                "description": "Nombre max de résultats retournés (1-10)",
                "default": 5
            },
            "language": {
                "type": "string",
                "enum": ["fr", "en", "ar"],
                "description": "Langue des résultats",
                "default": "fr"
            }
        },
        "required": ["query"],
        "additionalProperties": False   # bloque les paramètres inconnus
    }
}