Brooklyn MCP presents a mix of strengths and significant gaps. The server implements 13 tools with clear verb-noun naming (launch_browser, close_browser, navigate_to_url, etc.), which is excellent. However, critical issues emerge in parameter descriptions, schema completeness, and error handling guidance. Most tools have solid base descriptions (100-200 chars), but parameter-level documentation is sparse or missing. Output schemas are not explicitly documented in the provided code, which is a major gap. Error handling lacks recovery guidance, tools do not explain what to do when a browser_id is invalid or a URL navigation times out. The server also lacks tool annotations (readOnlyHint, destructiveHint, idempotentHint) which are increasingly important for agent safety.

• Add explicit output schemas to all tools. Document return types as JSON Schema (e.g., 'Returns: {"browsers": [{"id": string, "type": string, "isActive": boolean}]}').
• Enhance error handling descriptions. For each tool, add: 'Error scenarios: If browser_id is invalid, the server will attempt to resolve using the target strategy. If target resolution fails, returns error code BROWSER_NOT_FOUND with available browser IDs. This is not retryable; call list_active_browsers to see options.'
• Add tool annotations in the tool definition (if using MCP SDK v2.1+). For launch_browser: {"annotations": {"destructive": true}}. For close_browser: {"destructive": true, "idempotent": false} (closing twice may error). For read-only tools like navigate_to_url: {"readOnly": true}.
• Improve enum documentation. Instead of relying on descriptions, expand enum parameter documentation: '"target": enum with values: "latest" (most recently launched browser), "current" (your last-used browser), "byId" (requires valid browserId parameter)'.
• Refactor informational tools to use verb_noun naming: brooklyn_getting_started → get_getting_started_guide, brooklyn_examples → get_code_examples, brooklyn_status → get_server_status, brooklyn_logs → get_server_logs. This makes intent clearer and reduces naming ambiguity.
• Add dependency hints to tool descriptions. E.g., navigate_to_url description: 'Navigate to a URL in the target browser. If you do not know the browser ID, call list_active_browsers first.'
• Document timeout behavior and defaults explicitly. wait_for_url has a timeout parameter (30s default, 100-300s range), but navigate_to_url does not expose a timeout. Clarify if navigation has a default timeout and what happens on timeout (retry? fail?).

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

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