Unpress has 10 tools with complete JSON Schema definitions and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-80 chars, below the 194-char baseline), parameter schemas with types, and enums where appropriate. However, output schemas are entirely undocumented, LLMs cannot predict response structure. Error handling is minimal (only 'Session not found' visible). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels (WRITE, DESTRUCTIVE). Parameter descriptions are sparse (e.g., 'Migration session ID' lacks context on how to obtain it). No guidance on dependencies between tools (e.g., unpress_start must precede unpress_migrate). Secrets (wp_auth_token, sanity_token, github_token, vercel_token) are exposed as parameters, violates pattern:secret-injection.

• Move all secrets (wp_auth_token, sanity_token, github_token, vercel_token) to server-side environment variables or vault. Accept only session_id and project identifiers as parameters. Inject credentials inside tool handlers.
• Document output schemas for all tools. Add a 'returns' field to each tool definition specifying the JSON structure (e.g., { session_id: string, status: 'started'|'resumed', phase: string }).
• Add tool annotations: mark unpress_rollback with destructiveHint=true, unpress_status/unpress_scan/unpress_wizard with readOnlyHint=true, and idempotent tools (unpress_status) with idempotentHint=true.
• Enhance error responses with recovery guidance. E.g., 'Session not found. Call unpress_start() to create a new session, or provide a valid session_id from a previous migration.'
• Add dependency hints in descriptions. E.g., unpress_migrate: 'Requires a session created by unpress_start(). Call unpress_scan() first to estimate costs.' unpress_decide: 'Resolves a pending decision from unpress_status(). Check pending_decisions before calling.'