HumanifyMe demonstrates solid tool design with consistent naming patterns (verb_noun), comprehensive parameter descriptions, and proper Zod-based schema validation. All 16 tools have descriptions and input schemas. However, output schemas are not explicitly documented in the visible code, only input validation is enforced via Zod. Error handling is well-structured (toHumanifyError mapping to closed codes) but lacks recovery guidance in error messages. Tool composition is clean (single responsibility per tool), and security practices are sound (API keys via keyring, no secrets in params). Main gaps: output schema documentation, error messages missing actionable recovery steps, and some parameter descriptions could be more prescriptive about constraints.

• Add explicit output schema documentation to each tool definition. Define return types as Zod schemas (e.g., outputSchema: z.object({rewrite: z.string(), feedbackToken: z.string()})) and expose them in tool registration.
• Enhance error messages with actionable recovery steps. Instead of 'Invalid input', return 'Invalid feedback signal: got "maybe". Valid values: sounds_like_me, not_quite, needs_work.'
• Implement confirmation flow for destructive operations. Add a 'confirm' parameter or a separate 'confirm_delete_sample' tool that requires explicit user approval before deletion.
• Move parameter constraints from code validation into description text. E.g., 'The writing sample text (minimum 100 characters, maximum 50,000 characters)' so LLMs see constraints before calling.
• Register tool annotations (destructiveHint, readOnlyHint) in the MCP tool definition. Update registerTool() to accept and expose these hints via the MCP protocol.