hal-mcp demonstrates solid fundamentals: all 6 tools have clear action-verb names (search_, get_, export_) and substantive descriptions (100-200 chars). Input schemas are fully visible with typed parameters and descriptions. However, output schemas are undocumented, responses are inferred from code but not formally declared. Parameter constraints (enums for doc_type, sort, fmt) are documented in descriptions but not enforced as JSON Schema enums. Error handling is absent: no guidance on retryability, user-fixable vs fatal errors, or recovery paths. The server is read-only (no destructive operations), which mitigates some risk, but LLMs still need clear error semantics.

• Add JSON Schema output definitions to each tool docstring. Example: 'Returns: {"docs": [{"hal_id": str, "title": str, "year": int, ...}], "total": int, "start": int}'.
• Convert parameter constraints to JSON Schema enums. For doc_type, declare enum: ["article", "these", "hdr", "communication", "ouvrage", "chapitre", "rapport", "poster", "brevet", "image", "video"]. Same for sort, fmt, group_by.
• Add maxItems/minimum/maximum to numeric parameters in schema. E.g., rows: {type: integer, minimum: 1, maximum: 100}.
• Document error scenarios and recovery paths. E.g., 'If query returns 0 results, try broadening the search or using search_structures to find a lab first.'
• Clarify pagination: document the 'start' parameter (if supported), return 'total' count in response, and explain how to fetch subsequent pages.