Browser-MCP has 13 tools with complete input schemas and descriptions, but quality is inconsistent. Tool names follow verb_noun convention (navigate, get_text, click, type, etc.), which is good. However, descriptions are terse (avg ~40 chars, well below the 194-char baseline), lacking context on WHEN to use each tool or dependencies between them. Parameter descriptions are sparse, many lack guidance on expected formats, ranges, or constraints. Output schemas are not documented anywhere in the source. Error handling is absent from descriptions. The server lacks pagination guidance for tools like get_html and snapshot that could return large results. No mention of idempotency, retryability, or side effects in tool descriptions.

• Document output schema for every tool. Example: 'navigate() returns {success: boolean, url: string, title: string, loadTime: number}'. This enables LLMs to chain tools and extract needed fields.
• Expand descriptions to 100-200 chars. Add WHEN to use: 'Use get_text() to extract visible text for reading/analysis. Use get_html() if you need DOM structure or specific element content. Use snapshot() for accessibility tree and interactive elements.'
• Add constraint guidance to parameters. E.g., 'selector: CSS selector string (e.g., #button-id, .class-name, div[data-test="value"]). Returns error if 0 or >1 element matches.'
• Add error recovery hints. E.g., 'If wait() times out, try increasing timeout or use get_html() to inspect current DOM. If click() fails, verify selector matches exactly one element via snapshot().'
• Declare side effects and idempotency. E.g., 'navigate() is idempotent, calling twice with same URL is safe. click() and type() modify page state, retry only if you're certain the first call failed.'