keycloak-mcp has 23 tools with mostly complete naming and parameter schemas, but critical gaps in descriptions and error handling. Tool names follow verb_noun conventions well (get_*, list_*, search_*, set_*, reset_*). Parameters are typed (string, integer, boolean) with descriptions in most cases. However, descriptions are inconsistently detailed, some tools have brief 1-2 sentence descriptions (20-50 chars), and output schemas are not documented in the source. Error handling and recovery guidance are absent. The server focuses on read operations (21/23 READ_ONLY) with sensitive write operations (logout_user, set_user_enabled, reset_password) but no confirmation or dry-run patterns. Tool definitions are visible in keycloak_mcp/server.py via FastMCP decorator registration, so we can score directly rather than inferring.

• Document output schemas for every tool. Add a 'Returns' section to each tool's docstring specifying the structure, field types, and key IDs needed for downstream calls. Example: 'Returns: {"users": [{"user_id": str, "username": str, "email": str}], "total": int}'
• Add confirmation/dry-run patterns to write operations. Before logout_user or reset_password execute, return a preview ('You are about to reset password for john_doe. Confirm to proceed.') or dry-run output showing what will change.
• Wrap all external API calls in try-catch blocks and return structured error responses with recovery guidance. Example: 'KeyCloak server unavailable. Health check failed: {error_detail}. Verify KEYCLOAK_URL and credentials in config.'
• Extend tool descriptions to 100-200 characters (baseline 194). Explain WHEN to use each tool and what distinguishes it from related tools. Example for get_client: 'Get detailed client configuration (credentials, redirects, grant types). Use after list_clients to fetch config for a specific client_id.'
• Remove plaintext password parameter from reset_password. Add a 'generate_temporary' boolean flag. If true, server generates a random temporary password and returns it in the response (NOT logged in parameters). Agents can then display it to the user.
• Add warnings to get_user_credentials and get_user_sessions descriptions: 'Returns sensitive session tokens and credential metadata. Do not echo raw output to end users. Extract only the fields needed for your task.'
• Apply JSON Schema format and pattern constraints. For date_from parameters, use 'format': 'date' and description 'ISO 8601 date (YYYY-MM-DD), e.g. 2024-01-15'. For top, max_results: add 'minimum': 1, 'maximum': 1000 to schema.