Better Playwright MCP

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool retrieves outerHTML for debugging purposes, but doesn't describe what happens if the element isn't found, whether this requires an active page session, what permissions are needed, or what the return format looks like. For a tool that interacts with browser elements, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and front-loaded with the core purpose in the first clause. Every word earns its place: it states what the tool does, how it works (via XP reference), and the primary use case. No wasted words or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given this is a browser interaction tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what happens on success/failure, what format the HTML is returned in, whether the page needs to be loaded first, or how this differs from similar sibling tools. The debugging context is helpful but doesn't compensate for missing behavioral context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters (pageId and ref) clearly documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema descriptions ('页面ID' and '元素的xp引用值'). This meets the baseline for high schema coverage where the description doesn't need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '通过xp引用获取元素的outerHTML结构' (get element's outerHTML structure via XP reference). It specifies both the action (获取/获取) and resource (元素outerHTML结构), though it doesn't explicitly differentiate from sibling tools like getPageSnapshot or getScreenshot that also retrieve content. The debugging context ('用于调试选择器') adds useful specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides minimal usage guidance. While it mentions the tool is '用于调试选择器' (for debugging selectors), it doesn't specify when to use this tool versus alternatives like getPageSnapshot (which captures full page) or waitForSelector (which waits for elements). No explicit when-not-to-use or prerequisite information is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.