La granularité des outils dans les agents LLM : ce que 20 configurations de workflow nous ont appris

La sagesse populaire autour des outils d'agents LLM tend à converger vers l'un de deux slogans : « donnez moins d'outils au modèle pour qu'il ne s'embrouille pas », ou « exposez chaque opération comme un outil pour que le modèle puisse composer librement ». Les deux ont tort de manière intéressante. Nous avons construit AgentDoc – un éditeur de documents piloté par MCP – en partie pour disposer d'un banc d'essai crédible sur cette question, et nous avons exécuté 20 configurations de workflow (A–T) sur 13 scénarios de benchmark afin de voir ce qui fait réellement bouger les choses.

Cet article est un compte rendu de ce que nous avons découvert ; nous nous concentrons ici sur les enseignements pratiques pour quiconque conçoit des outils pour des agents LLM – que ce soit pour un serveur MCP, une API de function-calling, ou un orchestrateur sur mesure.

Le dispositif, en bref

Chaque configuration est une combinaison différente de (a) surface d'outils – atomique vs composite vs mixte ; (b) contrôle du workflow – prompting ReAct pur vs FSM ReAct à états contraints ; et (c) politique de vérification – appel optionnel vs obligatoire de get_document_context après chaque mutation. Les configurations vont d'une référence zero-shot monolithique (un seul outil edit_document géant, sans FSM) jusqu'à un FSM étroitement contrôlé avec 35 primitives atomiques.

Le scoring utilise la distance de Levenshtein sur le document final, plus la consommation de tokens et un décompte explicite des hallucinations (appels d'outils référençant des index qui n'existent pas).

Conclusion 1 : « moins d'outils » gagne sur les tokens, perd sur la précision

La référence monolithique edit_document est de loin la moins chère en tokens – le modèle émet un seul gros appel et c'est terminé. Mais ses scores de Levenshtein sont environ 3× pires que les configurations à outils atomiques sur les tâches multi-étapes, parce que le modèle doit planifier la mutation entière en une seule passe avant, sans aucune possibilité de vérifier l'état intermédiaire.

Sur les documents longs, ce régime échoue purement et simplement : le modèle émet une modification référençant un titre qui n'existe plus à l'offset supposé (parce que des modifications hypothétiques antérieures « dans le même plan » ont décalé les index), et le résultat est un document corrompu sur lequel il est difficile de raisonner, même pour le tour d'agent suivant.

Conclusion 2 : « chaque opération comme un outil » gagne sur la précision, perd sur les tokens – et sur les ruptures

Les outils purement atomiques (un find, un delete_substring, un insert_string distincts, etc.) repoussent la vérification dans la boucle de raisonnement du modèle. Avec des modèles de pointe instruction-tuned, la précision est élevée – mais le nombre de tokens explose, et nous observons une rupture nette autour de surfaces de 25 outils : au-delà, le modèle commence à mal choisir entre des outils quasi synonymes (insert_paragraph vs insert_text vs append_text), ce qui constitue son propre mode de défaillance qui n'apparaît pas dans les configurations à 8 outils.

Le nombre d'outils interagit avec l'entropie de nommage. Vingt outils dont les noms se regroupent sémantiquement (insert_*, append_*, prepend_*) sont plus difficiles pour le modèle que trente outils qui couvrent des verbes manifestement distincts.

Conclusion 3 : un petit ensemble de macros bien nommées est le point d'équilibre idéal

Les configurations qui se classent le plus haut sur le score conjoint précision/tokens partagent une structure : des primitives atomiques pour la longue traîne, plus trois à cinq macros bien nommées pour les chemins courants évidents (replace_all, format_all_matches, convert_paragraph_to_heading). Les macros suppriment les séquences multi-étapes les plus courantes – réduisant 4 allers-retours à 1 – sans forcer le modèle à les composer de zéro.

L'astuce n'est pas le nombre de macros ; c'est que chaque macro doit correspondre à une requête en langage naturel que les utilisateurs formulent réellement. Les macros inventées pour l'élégance du code (« composeFormatBatch ») sont ignorées par le modèle au profit des primitives atomiques. Les macros nommées d'après des requêtes courantes (« remplace tous les X par des Y ») sont utilisées immédiatement et correctement.

Conclusion 4 : la vérification structurelle surpasse la vérification par prompt

Dire au modèle « relis toujours le document avant de muter » fonctionne une partie du temps. Un FSM ReAct à états contraints qui verrouille les outils d'écriture jusqu'à ce qu'un appel à get_document_context soit terminé fonctionne tout le temps. Les configurations FSM réduisent les erreurs d'index halluciné d'environ 14 % dans la condition prompt-seul à moins de 2 % – et le coût est un unique aller-retour supplémentaire tous les quelques tours, ce qui est dérisoire par rapport à une modification corrompue.

C'est l'enseignement pratique le plus fort de toute l'étude : si votre agent opère contre un état sensible aux index (un document, un buffer, un arbre syntaxique), ne vous fiez pas aux prompts seuls. Rendez la vérification structurellement inévitable dans la surface d'outils elle-même.

Conclusion 5 : la dérive d'index est un bug de conception d'outils, pas un bug du modèle

Nous avons constaté à plusieurs reprises que les configurations les moins performantes n'étaient pas « faibles » selon une quelconque métrique de capacité – elles exposaient simplement des outils dont les contrats permettaient au modèle de réussir localement et d'échouer globalement. Un outil qui prend un index de caractère et renvoie un succès sans dire au modèle que tout ce qui suit cet index a été décalé est le bug. Les modèles de pointe finiront par apprendre à compenser. Votre surface d'outils ne devrait pas les y obliger.

Concrètement : chaque outil de mutation dans AgentDoc renvoie une charge utile structurée qui inclut un descripteur de plage modifiée ({shifted_after: 412, delta: -23}). L'appel d'outil suivant le voit, et le FSM impose une relecture. Les hallucinations sont tombées proches du plancher en conséquence.

Ce que cela signifie si vous construisez un agent

Trois règles empiriques valant plus que n'importe quel chiffre spécifique ci-dessus :

• Optez par défaut pour des primitives atomiques, ajoutez des macros pour les chemins en langage naturel. Ne préoptimisez pas pour le coût en tokens ; c'est moins cher qu'une modification corrompue.
• Maintenez la surface d'outils sous 25 outils, ou répartissez-la en familles aux noms distincts. L'ambiguïté par regroupement est un véritable mode de défaillance.
• Rendez la vérification structurelle. Un FSM qui conditionne les outils d'écriture à une relecture récente ne coûte presque rien et élimine toute la classe des bugs de dérive d'index.

Le prochain article de cette série porte sur l'architecture voice-first – y compris pourquoi nous avons choisi de relier Gemini Live directement à la surface MCP plutôt que via un proxy de transcription. Cette décision découle exactement des conclusions ci-dessus.