MCP server for browser automation using Puppeteer
This Puppeteer server has 7 well-registered tools with schemas and descriptions present, but suffers from significant quality gaps. All tools have descriptions (10 - 35 chars, mostly below the 50-char threshold for clarity), but the descriptions lack actionable detail about when to use each tool, parameter constraints, and expected outcomes. Input schemas are present for all tools but many parameters lack descriptions, particularly critical for `puppeteer_evaluate` which accepts arbitrary JavaScript without any safety guidance. Parameter types are defined (string, number) but lack enums, ranges, or validation rules. Output schemas are not documented, the LLM cannot predict what fields are returned. Error handling is present but generic; errors do not guide recovery or explain how to self-correct. The tool set is reasonably composed (each does one thing), but lacks pagination, result limits, and chaining IDs. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present, forcing LLMs to infer risk from descriptions alone, a failure for `puppeteer_evaluate` which is actually destructive and unbounded.
Click an element on the page
Execute JavaScript in the browser console
Fill out an input field
Hover an element on the page
Navigate to a URL
Take a screenshot of the current page or a specific element
Select an element on the page with Select tag
puppeteer_evaluate accepts arbitrary JavaScript without any safety, constraints, or examples. Description is 34 chars and does not explain escape rules, timeout behavior, injection risks, or output format. No schema prevents LLM from hallucinating invalid JS syntax.
No output schemas documented. LLM cannot predict return structure. For example, puppeteer_screenshot returns TextContent + ImageContent, but this is not declared in the tool definition, LLM must infer from context. puppeteer_evaluate's JS result type is completely undocumented.
Parameter descriptions are missing or minimal. puppeteer_navigate has no description for the 'url' parameter; puppeteer_click has no description for 'selector'; puppeteer_evaluate has no description for 'script'. LLM cannot infer constraints (e.g., 'selector must be a valid CSS selector', 'script must be synchronous JS').
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 48 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 49 | - | v1 |
Tool descriptions are under 50 characters and lack actionable context. 'Navigate to a URL' (17 chars) does not explain when to use this tool vs others, what happens on redirect, what to do on 404, or expected output. 'Execute JavaScript in the browser console' (42 chars) does not explain return type, timeout, or restrictions.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). puppeteer_click, puppeteer_fill, puppeteer_select, puppeteer_evaluate are marked WRITE in the brief, but the tool definition carries no annotation. LLM must guess which tools are safe to retry.
screenshot width/height parameters have no range constraints. LLM could pass width=999999 or height=0, causing puppeteer.launch() failures or OOM. Descriptions say 'default: 800' but no min/max bounds.
Error messages are generic ('Element not found', 'Screenshot failed', 'Failed to click') and do not guide recovery. No suggestion of alternative tools or retry strategies. Per pattern:recovery-guide, errors should say 'what went wrong' AND 'what to do next'.
No pagination support. If puppeteer_screenshot or puppeteer_evaluate produces large output, no limit is enforced. No way to stream or paginate results.
Selector parameter is used across multiple tools (puppeteer_click, puppeteer_fill, puppeteer_select, puppeteer_hover) but validation is not consistent. No guidance on valid CSS selector syntax, XPath support, or fallback behavior if selector does not match. LLM cannot distinguish between 'selector not found' and 'invalid selector syntax'.