Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
Server provides 15 tools with consistent naming patterns (verb_noun: puppeteer_*) and clear action semantics. All tools have descriptions and Zod-based input schemas with type safety. However, several tools lack parameter descriptions, output schemas are not documented, and error handling guidance is minimal. Parameter descriptions are inconsistently applied, some parameters like 'viewport' and 'proxy' lack field-level documentation. The tool definitions are explicitly visible in src/tools.ts with proper registration via the tool() wrapper, establishing full traceability. Main gaps: (1) missing parameter descriptions on ~40% of parameters, (2) no documented output schemas, (3) no error recovery guidance, (4) risk annotations (WRITE/READ_ONLY/DESTRUCTIVE) present in metadata but not reflected in descriptions.
Missing parameter descriptions on ~40% of parameters. Examples: puppeteer_click (selector, pageId lack descriptions), puppeteer_get_text (selector, pageId), puppeteer_close_page (pageId), puppeteer_close_browser (no params means no descriptions). LLMs cannot infer meaning from names alone, 'pageId' could mean UUID, string ID, numeric ID, or handle. This violates the tool-description pattern.
Output schemas not documented for any tool. Tool descriptions state what they return (e.g., puppeteer_screenshot: 'Returns the image inline'), but no structured schema is provided. LLMs cannot plan downstream operations or extract specific fields without knowing the response structure. This violates the response-shaper and tool patterns.
Add parameter descriptions to all parameters missing them. For each param, specify: (a) what it controls, (b) expected type/format, (c) valid ranges or enums, (d) default behavior if omitted. Example: 'pageId (string): Browser page identifier. If omitted, defaults to the most recently created page. Pass an explicit pageId to target a specific tab.'
Document output schemas for all tools. Use a structured comment or extend tool descriptions with a 'Returns' section. Example for puppeteer_screenshot: 'Returns {data: string (base64-encoded PNG), savedPath?: string (if path param was provided), success: boolean}.'
Add error recovery hints to tools that commonly fail. Example for puppeteer_navigate: 'If the page does not load, try increasing the timeout via puppeteer_wait_for_selector. If the target URL is invalid, check the domain spelling.'
Surface risk annotations in tool descriptions. Prepend descriptions of destructive tools with a warning. Example for puppeteer_close_browser: 'WARNING: Closes the entire browser and all open tabs. This cannot be undone. Returns {success: boolean}.'
Document the pageId auto-default behavior once in puppeteer_new_page (the discovery tool for pages), then reference it in other tools. Example: 'For multi-page workflows, pass an explicit pageId. See puppeteer_new_page for page management details.'
Add format constraints to complex parameters. For puppeteer_launch's viewport: 'viewport object with width (number, pixels, > 0), height (number, pixels, > 0), deviceScaleFactor (optional, > 0.5, default 1.0), isMobile (optional boolean), hasTouch (optional boolean), isLandscape (optional boolean).'
Spec posture evidence
Inferred effective spec: 2025-06-18+.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 20 points across a rubric change (v1 → v2)
58/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
58
2025-06-18+
v2
2026-03-09
F
38
-
v1
write
source verified
77/100
Launch a new Puppeteer browser instance or connect to existing Chrome with remote debugging. Optional — the server will auto-launch with defaults the first time you use any other tool.
puppeteer_navigateread onlysource verified73/100
Navigate a tab to a URL.
puppeteer_new_pagewritesource verified72/100
Create a new browser tab. If puppeteer_launch was not called, the browser auto-launches with defaults.
No error recovery guidance in any tool description. Tools like puppeteer_evaluate and puppeteer_navigate can fail in many ways (timeout, network error, selector not found), but descriptions offer no hints on what to do next. This violates the recovery-guide pattern and leaves agents without fallback strategies.
Risk annotations (WRITE, READ_ONLY, DESTRUCTIVE) are present in metadata but not surfaced in tool descriptions. LLMs cannot see the Risk field, they only read the description text. Destructive tools (puppeteer_close_page, puppeteer_close_browser, puppeteer_delete_cookies) should explicitly warn the user. This violates the command-tool pattern.
pageId parameter is optional on nearly all tools, defaulting to DEFAULT_PAGE_ID if omitted. While convenient, this creates an implicit dependency: agents may not realize that multiple pages require explicit pageId management. No tool description explains this auto-default behavior or when to explicitly pass pageId vs rely on the default.
puppeteer_launch and puppeteer_new_page descriptions do not clarify state management. puppeteer_launch says 'Optional, the server will auto-launch with defaults the first time you use any other tool', but which tool triggers auto-launch? puppeteer_new_page says 'If puppeteer_launch was not called, the browser auto-launches with defaults', this mirrors puppeteer_launch's guarantee but is redundant. The relationship between launch and new_page is unclear.
puppeteer_launchpuppeteer_new_page
Clarify the initialization sequence in puppeteer_launch and puppeteer_new_page descriptions. Explicitly state: 'Call puppeteer_launch first to configure browser options (headless, stealth, proxy, etc.). Call puppeteer_new_page to create additional tabs within that browser instance. If puppeteer_launch is skipped, subsequent tools auto-launch with defaults.'
Add per-item error details for tools managing cookies or requests. Example for puppeteer_set_cookies: 'Returns {failed: [{index: 0, name: 'session', reason: 'Invalid domain'}], succeeded: 2}' so agents know which cookies failed.
Document timeout behavior for network-dependent tools. puppeteer_navigate and puppeteer_wait_for_selector should state: 'Timeout defaults to 30 seconds. Pass timeout (milliseconds) to override. On timeout, returns {error: 'Timeout exceeded', url: '<last-attempted-url>'}.'
Add examples or patterns to descriptions where complex scenarios arise. For puppeteer_evaluate: 'Pass a JavaScript expression that returns a JSON-serializable value. Example: script="document.body.innerText" returns the page text. Complex scripts that reference page state should use arrow functions for proper context binding.'
Implement structured error responses. Instead of returning raw JS errors or empty objects on failure, return {success: boolean, error?: {code: string, message: string, retryable: boolean, suggestion?: string}}.