The Midscene MCP server defines 12 browser automation tools with complete Zod schemas and descriptions. Tool naming follows the pattern midscene_<action> consistently, which is clear and descriptive. Descriptions range from 120 - 230 characters, generally within the 10 - 1024 baseline and specific enough to guide LLM selection. However, several critical gaps reduce the score: (1) Parameter descriptions lack explicit constraints (e.g., no min/max for scrollType distance, no explanation of deepThink's actual behavior vs benefit). (2) Return/output schemas are not formally documented, the code returns generic TextContent blocks with free-form text rather than structured JSON responses. The rubric requires documented output schemas so LLMs can plan downstream calls and extract typed data. (3) Error handling is minimal, tools call ensureAgent() or wrap() but do not return actionable error messages with recovery guidance (e.g., 'Already connected. Call midscene_disconnect first.' instead of bare exceptions). (4) Several parameter relationships are undocumented: e.g., distance only applies when scrollType='once', but the schema doesn't enforce or describe this dependency. (5) Some descriptions are vague: 'Faster and more reliable for single actions' (midscene_ai_tap) doesn't explain *why* or *when* to use it vs midscene_ai_action. Overall, the server demonstrates solid naming and basic completeness but lacks the structured output design, error guidance, and constraint documentation expected of production-grade tools.

• Define formal output schemas for each tool. Instead of returning { content: [{ type: 'text', text: 'Connected to current tab.' }] }, return structured objects like { status: 'connected', tabId: string, timestamp: ISO8601 }. Document these in tool descriptions so LLMs know what to expect.
• Add numeric bounds to all numeric parameters. E.g., midscene_ai_scroll distance parameter: 'The distance to scroll in pixels (1-5000; default: 300).' midscene_ai_wait_for timeoutMs: 'Maximum time to wait in milliseconds (100-60000; default: 15000).'
• Clarify conditional parameter relationships. For midscene_ai_scroll, explicitly document: 'distance is required when scrollType="once" and ignored for scrollType="untilBottom"|"untilTop"|"untilLeft"|"untilRight".'
• Enhance error messages with recovery guidance. When ensureAgent() fails (not connected), catch and return: 'Browser not connected. Call midscene_connect_current_tab first.' When already connected, return: 'Already connected to a tab. Call midscene_disconnect first, then reconnect.'
• Expand differentiation descriptions. For midscene_ai_tap vs midscene_ai_action, add: 'Use midscene_ai_tap for single clicks/taps (~500ms per action). Use midscene_ai_action for multi-step workflows where Midscene plans the sequence (~5-30s for complex flows). Tap is faster but less intelligent; action is slower but handles complex interactions.'
• Document deepThink trade-offs explicitly. 'If true, uses a two-step AI call to precisely locate ambiguous elements. Increases latency (~1-2s) and token cost but improves accuracy for elements with similar text/appearance. Default: false (single-step, faster, suitable for most cases).'