The i18n-magic MCP server has 6 tools with clear, descriptive names and reasonable documentation. All tools have descriptions (ranging from 58-196 chars) that explain WHAT they do and WHEN to use them. Input schemas are visible in the code with Zod validation. However, several critical issues emerge: (1) Output schemas are NOT documented anywhere, the source shows input schemas but no return type documentation, forcing LLMs to guess what fields and structure to expect. (2) Error handling is minimal, no recovery guidance, error categorization, or actionable error messages visible. (3) Tool descriptions mention defaults and constraints textually but lack formal enum/pattern constraints in the schema itself. (4) The add_translation_keys tool returns an array but the output structure is not defined. (5) list_untranslated_keys returns 'keys that exist in default locale but missing in other locales' but the exact return structure is undocumented. These gaps are typical of tools that prioritize happy-path functionality over LLM-friendly error handling and schema documentation.

• Add explicit return type documentation for each tool. Define the response schema inline (e.g., via TypeScript type annotations in comments or JSDoc) or in a separate schema file. Minimal example: 'Returns {success: boolean, key: string, language: string, value: string}' for add_translation_key.
• Implement error categorization. Catch and return distinct error types: 'key_not_found' (recoverable, suggest search_translations), 'language_not_configured' (user-fixable, list available languages), 'file_write_failed' (retryable). Format as {error: string, code: string, recoveryHint?: string}.
• Formalize language constraints. Replace the description note 'Defaults to config.defaultLocale' with a union type like language: z.enum(['en', 'de', 'fr', ...]).optional().describe('Language code. Defaults to config.defaultLocale if omitted.'). This makes the constraint machine-readable.
• Add pagination to search_translations. Include query parameters limit (default 20, max 100) and offset (default 0). Return {results: [...], total: number, hasMore: boolean} so the agent knows when to fetch the next page.
• Document key-related field consistency. Ensure that if a key parameter is expected as a string like 'welcomeMessage', all responses use the same naming (not sometimes 'key', sometimes 'translation_key'). This matches the mxe:response-field-naming pattern.
• Add a dry-run parameter to add_translation_key and update_translation_key with a deprecation note: --dry-run flag (returns what would be written, no side effects) to support the confirmation-request pattern for irreversible ops.