Surf MCP has well-structured tool definitions with complete schemas and descriptions for all 18 tools. Naming follows verb_noun convention (session_create, goto, click). However, descriptions are often terse (10-50 chars), falling below the 50-200 char LLM-optimized baseline. Parameter descriptions exist but lack actionable constraints (e.g., no enum validation guidance, no format specs). Error handling is minimal, no recovery guidance or categorization. Output schemas are not documented. The 'act' and 'act_autonomous' tools rely on external Fara service with no fallback or timeout guidance.

• Expand tool descriptions to 50-200 chars. Include WHEN to use (vs similar tools), WHAT it returns, and any prerequisites. E.g., 'Navigate to a location (filesystem path or URL). Use after session_create to move the driver. Returns the new location and any navigation errors.'
• Document output schemas for all tools. Specify returned fields, types, and whether results are paginated. E.g., session_list returns {sessions: [{id, drivers: {alias, type}}], total_count}.
• Add error handling with recovery guidance. Categorize errors as retryable (timeout, rate limit) vs user-fixable (invalid session_id, unsupported driver type). E.g., 'Session not found. Call session_list to see active sessions.'
• Add parameter constraints to descriptions. E.g., 'amount: pixels to scroll (1-5000, default: viewport height)' and 'direction: up or down (default: down)'.
• Implement timeout and fallback for Fara calls. Return partial results if Fara is slow, and provide a fallback tool (e.g., click by CSS selector) if visual grounding fails.

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

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