> ## Content Index
> Fetch the complete content index at: https://www.sfeir.dev/llms.txt
> Use this file to discover other available public pages before exploring further.

# Concevoir des tools MCP pour un agent IA
- URL: https://www.sfeir.dev/ia/concevoir-des-tools-mcp-pour-un-agent-ia/
- Published: 2026-10-30T07:00:00.000Z
- Updated: 2026-10-30T07:00:00.000Z
- Description: 7 règles pour concevoir les tools d'un serveur MCP : orientés tâche, noms plutôt qu'IDs, verbosité réglable, erreurs instructives, annotations.
- Author: Baptiste PIRAULT
- Tags: IA, MCP, Agent IA, Agentic

### Concevoir des tools MCP pour un agent, pas un wrapper d'API

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#concevoir-des-tools-mcp-pour-un-agent-pas-un-wrapper-dapi)

Quand on crée son premier serveur MCP, le réflexe naturel est d'exposer son API existante telle quelle : un endpoint REST, un tool. Le résultat compile, répond correctement à chaque appel... et fonctionne mal. L'agent doit faire les jointures lui-même, et paie en contexte chaque résultat intermédiaire. Un tool MCP n'est pas une API pour un développeur : c'est une interface pour un lecteur qui a une mémoire de travail petite et chère. Voici les règles de conception que j'applique désormais. Pour la mise en place technique d'un serveur, voir [Créer votre server MCP dans Spring Boot](https://www.sfeir.dev/back/creer-votre-server-mcp-dans-spring-boot/) ; cet article porte sur ce que le serveur expose.

## Règle 1 : des tools orientés tâche, pas orientés table

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#r%C3%A8gle-1--des-tools-orient%C3%A9s-t%C3%A2che-pas-orient%C3%A9s-table)

Réserver une réunion avec `list_users`, `list_events` et `create_event` coûte trois allers-retours et deux jeux de résultats que l'agent doit garder en contexte. Un seul tool `schedule_event` fait la jointure côté serveur pour le prix d'un appel.

La question à se poser pour chaque tool : *que ferait une personne avec les mêmes accès ?* Le tool doit être une étape de ce travail, pas une ligne de votre schéma.

Le même principe remplace l'énumération par la recherche dès qu'une collection peut dépasser la taille du contexte :

- `search_logs` qui renvoie les lignes pertinentes, plutôt que `read_logs` qui renvoie le fichier ;
- `search_projects(query)` plutôt que `list_projects()`.

La consolidation réduit aussi le risque que l'agent choisisse le mauvais tool, un mode d'échec bien réel au-delà d'une douzaine de tools.

## Règle 2 : renvoyer des noms, pas des identifiants

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#r%C3%A8gle-2--renvoyer-des-noms-pas-des-identifiants)

`uuid`, `mime_type` et `256px_image_url` sont pensés pour un client de base de données. Un agent n'a pas de table de correspondance : il devine, ou dépense un appel pour résoudre l'identifiant.

```
// À éviter
{"owner": "7f3a9c2e-...", "mime_type": "application/vnd.google-apps.document"}

// À préférer
{"owner": "Marie Dupont", "owner_id": "7f3a9c2e-...", "file_type": "Google Doc"}
```

Quand un identifiant doit vraiment circuler (parce qu'une écriture ultérieure en a besoin), renvoyez-le **à côté** du nom, jamais seul.

## Règle 3 : donner un réglage de verbosité

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#r%C3%A8gle-3--donner-un-r%C3%A9glage-de-verbosit%C3%A9)

Un paramètre `response_format` avec les valeurs `concise` et `detailed` déplace la décision de taille vers l'appelant, qui sait s'il explore ou s'il s'apprête à agir. Anthropic a mesuré la même réponse Slack à **206 tokens** en mode détaillé et **72 tokens** en mode concis, les deux suffisant à enchaîner l'appel suivant ([Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents?ref=sfeir.dev)).

```python
@mcp.tool()
def search_tickets(query: str, response_format: Literal["concise", "detailed"] = "concise"):
    ...
```

Quelques lignes de code serveur, et l'une des réductions de contexte les moins chères qui existent.

## Règle 4 : des troncatures et des erreurs qui enseignent

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#r%C3%A8gle-4--des-troncatures-et-des-erreurs-qui-enseignent)

Une réponse coupée à une limite doit dire quoi faire autrement. `47 résultats supplémentaires, affinez avec theme:` apprend à l'agent son prochain appel ; une coupure sèche l'invite à relancer la même requête trop large.

Même principe pour les erreurs : nommez ce qui ne va pas et montrez une valeur bien formée.

```
# Opaque
Error 400: invalid parameter

# Instructif
Invalid date "next monday". Expected ISO 8601, e.g. "2026-10-12".

```

Un code d'erreur opaque envoie l'agent tester des variantes qui coûtent plus cher que l'échec initial. Et fixez une limite de taille explicite à vos réponses (Claude Code plafonne la sortie d'un tool autour de 25 000 tokens) plutôt que de laisser un gros résultat décider à votre place.

## Règle 5 : écrire les descriptions pour un nouveau collègue

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#r%C3%A8gle-5--%C3%A9crire-les-descriptions-pour-un-nouveau-coll%C3%A8gue)

Les descriptions de tools sont du prompt, et elles sont lues à froid. Une bonne description :

- définit les termes propres à votre domaine ;
- explique comment les ressources sont liées entre elles ;
- documente la syntaxe de requête attendue ;
- nomme les paramètres sans ambiguïté (`user_id` plutôt que `user`, qui laisse le type ouvert).

De petits changements de formulation modifient fortement le comportement : Anthropic attribue une partie du score de Claude Sonnet 3.5 sur SWE-bench Verified au seul affinage des descriptions de tools.

Sur le namespacing, mon expérience nuance les recommandations publiées : les hôtes préfixent déjà chaque tool par le nom du serveur (`mcp__mon-serveur__search`), donc les collisions entre serveurs sont rares. Le préfixe redevient utile quand un même serveur expose plusieurs familles de ressources : `projects_search` et `users_search` évitent la confusion.

## Règle 6 : annoter chaque tool

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#r%C3%A8gle-6--annoter-chaque-tool)

La spécification MCP prévoit des annotations : `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. Sans elles, un agent (ou l'hôte qui le pilote) ne peut pas juger si un appel est sûr à faire de façon autonome. C'est aussi ce qui permet à un client de demander confirmation avant un `delete_*` et de laisser passer un `search_*`.

```python
@mcp.tool(annotations={"readOnlyHint": True, "openWorldHint": False})
def search_tickets(query: str): ...
```

## Règle 7 : mesurer la surface avec un agent

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#r%C3%A8gle-7--mesurer-la-surface-avec-un-agent)

Une surface de tools ne révèle sa forme que lorsqu'un agent l'utilise sur des tâches réalistes. La méthode :

- écrire des tâches qui demandent plusieurs appels et portent du vrai contexte ;
- les faire tourner dans une boucle simple appel modèle / appel tool ;
- enregistrer par tâche : succès ou échec, nombre d'appels, tokens consommés, erreurs rencontrées ;
- **lire les transcripts**.

La forme de l'échec nomme le correctif. Des appels presque identiques répétés pointent vers la pagination. Des paramètres erronés pointent vers les descriptions. Une piste abandonnée pointe vers un tool qui n'existe pas. Donner ces transcripts à un agent de code produit des propositions sur toute la surface d'un coup, plutôt qu'un tool à la fois.

## Mon propre contre-exemple

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#mon-propre-contre-exemple)

Par honnêteté : le dernier serveur que j'ai construit expose seize tools, dont cinq simples `list_*` qui enveloppent chacun une collection, et aucune campagne d'évaluation n'a validé cette forme. Il fonctionne. Mais "fonctionne" n'est pas "bien conçu", et c'est précisément le piège : un wrapper 1:1 passe tous les tests fonctionnels. Seule une mesure avec un agent le révèle.

## Conclusion

[](https://github.com/batou9150/writing-workspace/blob/main/blog/drafts/5%5FMCP%2C%20concevoir%20des%20tools%20pour%20un%20agent%20%28FR%29.md?ref=sfeir.dev#conclusion)

Concevoir un tool MCP, c'est concevoir une interface pour un utilisateur qui lit tout, ne retient rien d'un appel à l'autre, et paie chaque token. Moins de tools, mieux nommés, qui font les jointures côté serveur, renvoient des noms lisibles et des erreurs qui expliquent quoi faire : c'est ce qui sépare un serveur qui répond d'un serveur qu'un agent sait utiliser.

[Créer votre server MCP dans Spring BootEt si je discutait avec la référence des sites médias tech et IA sfeir.dev ? Découvrez comment mettre en place un server MCP avec Spring Boot, et à l’exploité dans des outils comme Claude desktop ou Codex.![](https://storage.ghost.io/c/0b/31/0b31478e-a66a-46f1-8c34-d44388e21192/content/images/icon/plume-point-34dfd587-a9ef-4e6b-aa69-66d983d4059c.png)sfeir.dev - Le média incontournable pour les passionnés de tech et d'intelligence artificielleErwan Le Tutour![](https://storage.ghost.io/c/0b/31/0b31478e-a66a-46f1-8c34-d44388e21192/content/images/thumbnail/Sans-titre-175d5ffe-691d-4b67-a61e-1d57c61fc583.png)](https://www.sfeir.dev/back/creer-votre-server-mcp-dans-spring-boot/)