fix: simplify MCP tool response to reduce grammar size for Bedrock

[Kaiohz]

Summary

• Replace BricksDocumentInfo (16 fields) with DocumentSummary (5 fields) in list_bricks_documents MCP tool
• Bedrock returns 400 "compiled grammar is too large" when tool schemas are too complex
• Only expose what the LLM needs: id, file_name, mime_type, size, status

[Kaiohz]

Review — fix: simplify MCP tool response to reduce grammar size for Bedrock

Score: 8/10 🟢

---

✅ What works well

1. Problème bien ciblé — Bedrock a une limite de taille de grammaire pour les tool schemas. En réduisant de 16 champs (avec aliases Pydantic) à 5 champs essentiels, on réduit drastiquement la surface du JSON Schema généré. C'est la bonne approche.

2. Typage du retour — Le passage de list → list[DocumentSummary] est un vrai plus. FastMCP va maintenant générer un schema JSON propre pour le tool, au lieu d'un list opaque.

3. Mapping explicite — La list comprehension est claire et explicite. On mappe uniquement les 5 champs utiles, pas de fuite de données internes.

4. Description sur id — Le champ id a une description qui fait le lien avec read_bricks_document : "Document ID — pass this to read_bricks_document". C'est exactement ce qu'un LLM a besoin de savoir pour enchaîner les appels. Excellent choix.

5. Approche non-destructive — BricksDocumentInfo reste intact dans le domaine. Seule la couche MCP fait le mapping. L'architecture hexagonale est respectée.

---

⚠️ Points à améliorer

1. Pas de test pour le mapping — DocumentSummary est un nouveau modèle qui mappe depuis BricksDocumentInfo. Même si c'est simple, un test unitaire qui vérifie que le mapping fonctionne (surtout les defaults) serait bienvenu. Ex:

   def test_document_summary_from_bricks_document_info():
       doc = BricksDocumentInfo(id="abc", fileName="test.pdf", url="...", mimeType="application/pdf", size=1024, status="ready")
       summary = DocumentSummary(id=doc.id, file_name=doc.file_name, mime_type=doc.mime_type, size=doc.size, status=doc.status)
       assert summary.id == "abc"

2. Descriptions en français — Les descriptions Pydantic sont en français ("Nom du fichier", "Type MIME du fichier", etc.) alors que la description de id est en anglais ("Document ID — pass this to read_bricks_document"). En pratique, pour un tool MCP destiné à des LLMs multilingues, l'anglais serait préférable pour maximiser la compréhension. Mais ce n'est pas bloquant — le LLM comprendra les deux.

3. Fin de fichier sans newline — Le diff montre \\ No newline at end of file. Cosmétique, mais ça fait du bruit dans les diffs futurs. Ajouter un newline final.

4. DocumentSummary dans le fichier tools — Le modèle est défini directement dans mcp_bricks_tools.py. Pour un projet en architecture hexagonale, ça serait plus propre dans un module application/responses/ ou application/schemas/, séparé de la logique MCP. Mais vu la taille du modèle (5 champs), c'est acceptable ici.

---

💡 Suggestions optionnelles

• Model_config sur DocumentSummary — Si jamais l'API Bricks renvoie du camelCase dans les futures additions, ajouter model_config = ConfigDict(populate_by_name=True) en amont éviterait des surprises.

• Champs url manquant ? — L'ancien BricksDocumentInfo expose un champ url (URL pré-signée). Le LLM n'en a pas besoin directement (il passe par read_bricks_document), mais c'est bon à documenter dans la docstring du tool si quelqu'un se pose la question.

---

Verdict

PR propre et ciblée. Le fix est minimal, non-destructif, et résout le problème Bedrock. Les suggestions ci-dessus sont des améliorations cosmétiques/qualité — la PR est mergeable en l'état. 👍

Les 2 points qui mériteraient un follow-up : ajouter un test pour le mapping et homogénéiser les descriptions (FR vs EN).