AP16 · Outil piège

Définition

Un outil dont les paramètres se prêtent à l’usage erroné : nom ambigu, chemin relatif, argument que le système connaît déjà mais que le modèle doit remplir.

Symptômes observables

• Des erreurs récurrentes sur un même paramètre.
• Des arguments inventés, ou la mauvaise entité ciblée.

Pourquoi c'est nuisible

Chaque degré de liberté inutile est une occasion d’erreur, et les erreurs se composent sur une longue boucle.

Chiffres

• Sur SWE-bench, l’équipe d’Anthropic a passé plus de temps à optimiser ses outils que le prompt ; imposer des chemins absolus a fait disparaître les erreurs dues aux chemins relatifs.
• Des exemples d’utilisation joints aux définitions d’outils font passer la gestion des paramètres complexes de 72 % à 90 % (mesure de l’éditeur).

Remèdes du catalogue

• A2 · Outils et interface agent-machine (ACI) — Un outil qui rend l’erreur difficile : énumérations, chemins absolus, noms explicites (`user_id` plutôt que `user`) et arguments déjà connus injectés par le code.
• A3 · Sortie structurée — Des paramètres typés et structurés, qui rendent les états invalides impossibles à exprimer.

Mesures hors catalogue

• Le test du stagiaire proposé par OpenAI : un nouveau venu saurait-il appeler l’outil correctement à partir de sa seule description ?

Patterns détournés

• A2 · Outils et interface agent-machine (ACI)

Anti-patterns voisins

• AP12 · Trop d’outils chargés d’emblée
• AP15 · Erreur d’outil non actionnable

Sources

• Building effective agents — Anthropic (E. Schluntz, B. Zhang), 2024-12-19
• Writing effective tools for agents — with agents — Anthropic (K. Aizawa et al.), 2025-09-11
• Function calling — OpenAI (documentation)
• Introducing advanced tool use on the Claude Developer Platform — Anthropic (B. Wu et al.), 2025-11-24