# Décrire une ability en une phrase ambiguë trompe un agent une fois sur cinq

> Testée sur plusieurs agents, une description d'ability trop vague a conduit au mauvais choix d'outil dans environ un cas sur cinq. Diagnostic et reformulation corrigée.

- Auteur : Clément Hadrot
- Publié le : 2025-11-21
- Mis à jour le : 2025-11-21
- Catégorie : IA & MCP
- URL : https://wpmoderne.dev.wordpress-developpement.fr/ia-mcp/ability-description-ambigue-trompe-agent-un-sur-cinq/

## L’essentiel

- Une phrase courte semble suffisante tant qu'elle n'est pas testée sur plusieurs agents
- Le mauvais choix d'outil ne provoque aucune erreur visible dans le journal
- Ajouter un contre-exemple explicite a fait chuter le taux d'erreur à zéro sur le même jeu de tests

« Planifie un rendez-vous pour ce client » : sur un système de prise de rendez-vous exposant deux abilities proches, `proposer_creneau` et `reserver_creneau`, cette simple phrase a suffi, dans nos tests, à déclencher la mauvaise ability une fois sur cinq. Ni erreur technique, ni message d'alerte : juste un rendez-vous réservé fermement là où une simple proposition à valider était attendue.

Cet article détaille le diagnostic mené sur ce cas précis, testé sur plusieurs agents distincts pour écarter l'hypothèse d'un comportement isolé à un seul modèle, et la reformulation qui a fait disparaître l'erreur sur le même jeu de tests. Il ne traite pas du schéma d'entrée des deux abilities, resté inchangé du début à la fin de ce travail.

## Le protocole de test suivi

Plutôt que de se fier à une impression après quelques essais manuels, le diagnostic a reposé sur un jeu de vingt formulations différentes d'une même intention de prise de rendez-vous, soumises à trois agents différents, pour un total de soixante appels. Le taux d'erreur observé, proche d'un cas sur cinq toutes formulations et tous agents confondus, s'est révélé remarquablement stable d'un agent à l'autre, ce qui a orienté le diagnostic vers la description des abilities plutôt que vers un comportement propre à un seul modèle.

## La description initiale, courte et apparemment claire

Les deux abilities portaient des descriptions courtes, rédigées rapidement lors de leur mise en place : « Propose un créneau à un client » pour la première, « Réserve un créneau pour un client » pour la seconde. À la lecture, la différence semble nette. Face à une formulation naturelle du type « planifie un rendez-vous », qui ne précise pas explicitement s'il s'agit d'une proposition ou d'une confirmation, les deux descriptions restaient également plausibles pour le modèle.

> L'essentiel à retenir : Une phrase courte semble suffisante tant qu'elle n'est pas testée sur plusieurs agents ; Le mauvais choix d'outil ne provoque aucune erreur visible dans le journal ; Ajouter un contre-exemple explicite a fait chuter le taux d'erreur à zéro sur le même jeu de tests

```
{
  "name": "reserver_creneau",
  "description": "Réserve un créneau pour un client.",
  "input_schema": {
    "type": "object",
    "properties": {
      "client_id": { "type": "integer" },
      "creneau_id": { "type": "integer" }
    },
    "required": ["client_id", "creneau_id"]
  }
}
```

## Pourquoi aucune erreur n'apparaissait dans le journal

Le schéma d'entrée des deux abilities étant valide dans les deux cas, l'appel se déroulait sans exception ni code d'erreur : du point de vue du journal technique, tout s'était bien passé. Seule une relecture humaine du résultat final, comparé à l'intention initiale de la personne ayant formulé la demande, permettait de repérer le problème. C'est ce qui rendait ce type d'erreur particulièrement difficile à détecter en conditions réelles, sans protocole de test dédié.

## La reformulation testée

La correction a porté sur l'ajout, dans chaque description, d'un exemple positif et d'un contre-exemple explicite, plutôt que sur une reformulation plus longue de la seule action réalisée.

```
{
  "name": "reserver_creneau",
  "description": "Confirme définitivement un créneau pour un client, sans possibilité d'annulation automatique. "
    . "À utiliser seulement si le client a explicitement confirmé sa disponibilité. "
    . "Ne pas utiliser pour une simple proposition non confirmée : utiliser proposer_creneau dans ce cas.",
  "input_schema": { "...": "inchangé" }
}
```

## Le résultat obtenu sur le même jeu de tests

Après reformulation des deux descriptions selon ce même principe, les soixante appels du jeu de test initial ont été rejoués à l'identique : aucune erreur de choix d'ability n'a été observée, contre environ un cas sur cinq avant correction. Ce résultat, obtenu sans modifier le schéma d'entrée ni le comportement des deux abilities, confirme que le problème résidait entièrement dans la description, pas dans leur conception technique.

- Rejouer un même jeu de formulations sur plusieurs agents avant de conclure à un problème de description.
- Ajouter un contre-exemple explicite plutôt qu'un simple synonyme du verbe d'action.
- Vérifier le résultat final, pas seulement l'absence d'erreur technique dans le journal.

> Un taux d'erreur d'une fois sur cinq ne se voit jamais dans une démonstration réussie de quatre essais sur cinq : il ne se révèle qu'en testant systématiquement, avec un volume suffisant pour que la moyenne apparaisse.

## En résumé

Une description d'ability trop courte peut sembler parfaitement claire à la lecture tout en restant ambiguë pour un modèle confronté à une formulation naturelle imprécise. Tester systématiquement, avec plusieurs formulations et plusieurs agents, reste le seul moyen fiable de détecter ce type d'ambiguïté avant qu'elle ne se manifeste en production ; l'ajout d'un contre-exemple explicite dans la description a, dans ce cas précis, suffi à la faire disparaître entièrement.