MCPify converts OpenAPI specs to MCP tools dynamically. The 7 demo tools have reasonable naming (verb_noun pattern: listUsers, getUserById, deleteUser, createUser, listProducts, getProductById, createProduct) and complete input schemas with typed parameters and descriptions. However, several critical issues limit the score: (1) Most tool descriptions are extremely brief (10-20 chars: 'Retrieve a list of users', 'Get a user by ID'), providing minimal context for LLM selection and no guidance on when to use vs similar tools. (2) No output schemas are documented anywhere in the source, LLMs cannot know what fields to expect from responses. (3) No error handling guidance is visible in tool definitions. (4) Some parameter descriptions lack actionable detail (e.g., 'Numeric ID of the user to retrieve' doesn't specify format, range, or constraints). (5) The deleteUser and createProduct tools lack destructive/write confirmation patterns. (6) No per-tool security annotations (readOnlyHint, destructiveHint) are present despite the Risk metadata in the spec being provided. This is a proof-of-concept OpenAPI→MCP translator, so dynamic generation constraints apply, but production use would require template improvements.

• Expand tool descriptions to 50-150 chars. Example: 'listUsers' → 'Retrieve all users. Returns a paginated list of user IDs, names, emails, and roles. Use this to discover users before calling getUserById or createUser. Results are paginated, use limit and offset for large datasets.'
• Document output schemas for every tool. Add a 'Returns' section to the description or a separate outputSchema field. Example for getUserById: 'Returns: {id (number), name (string), email (string), role (enum: admin|user), createdAt (ISO 8601 string)}'
• Add pagination parameters to list operations: limit (default 20, max 100) and offset (default 0). Document total_count in output.
• Add tool annotations (readOnlyHint, destructiveHint) to tool definitions based on Risk metadata. Emit readOnlyHint=true for GET operations, destructiveHint=true for DELETE, idempotentHint=true for operations safe to retry.
• Enhance parameter descriptions with format and constraints. Example for 'id' parameter: 'User ID (positive integer, 1 - 9999999).' Example for 'email' in createUser: 'User email address (valid email format, unique).'
• Add error recovery guidance to descriptions. Example for deleteUser: 'If user not found, call listUsers() first to verify the ID exists. Deletion is permanent.'
• For destructive operations (deleteUser), consider adding a confirmation_required boolean parameter or a separate dry-run preview step to prevent accidental deletion.
• Define field-name consistency: ensure tool output uses the same field names as input parameters (e.g., if createUser accepts 'role', getUserById should return 'role', not 'userRole' or 'account_role').

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry