Folionaut has well-structured tool definitions with comprehensive Zod schemas and descriptions. All 7 tools have clear descriptions (100-200 chars), all parameters are typed and described, and input schemas are properly defined in src/validation/tool.schemas.ts. However, there are notable gaps: (1) output schemas are not documented, the source shows input schemas but no return type documentation; (2) error handling is not evident in the visible code, no recovery guidance or error categorization patterns; (3) the tool descriptions lack context about when to use each tool vs. similar ones (e.g., get_content vs. search_content); (4) no pagination metadata returned (e.g., total count, next_cursor) for list_* tools despite accepting limit parameters; (5) tool risk levels are marked (READ_ONLY, WRITE, REVERSIBLE, DESTRUCTIVE) but tool annotations (readOnlyHint, destructiveHint, idempotentHint) are not visible in the registration code. The server scores well on naming clarity (verb_noun pattern for all tools) and parameter constraints (enums, min/max bounds), but falls short on output structure, error recovery, and tool composition completeness.

• Document the return type for every tool. Add a 'Returns' section to each tool description or include a separate output schema. Example: 'Returns: {id: string, slug: string, type: string, data: object, status: string, createdAt: ISO8601, updatedAt: ISO8601}'.
• Add error handling patterns to tool descriptions. For get_content and search_content, add: 'If the content is not found, returns an empty result or a 404 error with suggestions for similar content types or available slugs.'
• For list_content and search_content, clarify pagination. Update descriptions to state: 'Returns paginated results with total count and next_cursor for fetching additional pages. Use limit and status to filter.'
• Register tool annotations in the MCP server code. Use readOnlyHint for list_*, get_*, and search_*; destructiveHint for delete_*; idempotentHint for create_* (if slug is provided) and update_*.
• Refine descriptions for get_content vs. search_content: get_content: 'Retrieve a specific content item by its exact slug identifier. Use when you know the exact slug.' search_content: 'Search for content across all types using free-text queries. Use when you do not know the exact slug or want to find multiple matching items.'
• Add a confirmation step to delete_content. Modify the tool to return a confirmation_required error or add a separate confirm_delete_content tool. Document that deletion is permanent.
• Define a schema for the 'data' field in create_content and update_content. Document that 'data' must be a valid JSON object and list example fields for each content type (or link to a schema discovery tool like list_types with type details).