How do I use playwright-fixer-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@playwright-fixer-mcp fix the failing test @AUT-123 in checkout.spec.ts" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

playwright-fixer-mcp

by BobChochola

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

playwright-fixer-mcp

Automated Playwright E2E test repair powered by a self-improving, governed MCP server.

Built on the three-layer AI automation architecture — Knowledge, Capability, and Governance — this tool turns failing Playwright tests into a closed verification loop: it runs the test, collects failure artifacts, reasons about the root cause, applies a rule-validated fix, and re-runs to verify — without hallucinating about runtime state.

We don't increase model intelligence. We reduce model freedom. The result is a system that works not by magic, but by design.

Why This Exists

When a Playwright test fails, most teams do one of two things:

Send the error to an LLM and hope it guesses right.
Alert an engineer to investigate manually.

Both share the same flaw: the LLM is reasoning blind. Timeout 5000ms exceeded contains almost no actionable information. No selector. No DOM context. No iframe structure. No screenshot.

This tool solves that by treating E2E debugging as a state reconstruction problem, not a prompting problem.

Instead of better prompts, the system provides:

Deterministic context — the model never guesses about runtime state; tools provide it
Constrained reasoning — exactly one failure context is resolved, one rule bundle injected
Closed verification — every proposed fix is validated by validate_and_apply_fix (the locked door) and re-run before accepting
Self-improving governance — learned fix patterns become rules, reviewed by humans, promoted automatically

Related MCP server: qa-ai-mcp-server-gits

Architecture

The system separates three concerns that most AI automation tools mix together. Mixing them is the most common failure mode.

┌──────────────────────────────────────────────────────────┐
│  Layer 3 — Governance  (.mdc rule files)                 │
│                                                          │
│  Behavioral contracts, workflow procedures, approval     │
│  gates. The AI executes these procedures — it doesn't    │
│  decide whether to follow them.                          │
│                                                          │
│  playwright-mcp.mdc · rule-evolution-review.mdc          │
└──────────────────────────────┬───────────────────────────┘
                               │ constrains
┌──────────────────────────────▼───────────────────────────┐
│  Layer 2 — Capability  (index.js — this MCP server)      │
│                                                          │
│  Neutral execution: run tests, read specs, analyze       │
│  failures, validate + apply fixes, propose rule updates. │
│                                                          │
│  LOCATOR_VIOLATION_RULES is enforced here as a hard      │
│  constraint (locked-door pattern) — not as a suggestion. │
└──────────────────────────────┬───────────────────────────┘
                               │ consults
┌──────────────────────────────▼───────────────────────────┐
│  Layer 1 — Knowledge  (playwright-test-standards.mdc)    │
│                                                          │
│  Locator priority, DSL conventions, evolved heuristics.  │
│  Guides reasoning — not enforced. Accumulates learned    │
│  rules over time via the rule evolution system.          │
└──────────────────────────────────────────────────────────┘

Key distinction — apply_approved_rules is intentionally not an MCP tool. It lives in rule-evolution-review.mdc as a governed procedure. Keeping it out of the automated executor prevents the system from modifying its own rule layer without human approval.

Closed Repair Loop

@AUT-xxx  (or "npx playwright test --grep @AUT-xxx")
    │
    ▼
resolve_spec_by_tag ──→ read_spec_file
    │                        │
    │                   (understand full test intent before running)
    │
    ▼
run_test_and_analyze_failure (attemptNumber: 1)
    │
    ├── passed: true  ──→ propose_rule_evolution ──→ PENDING queue
    │
    ├── shouldStop: true  ──→ escalate to human (attempt limit reached)
    │
    └── passed: false
            │
            ▼
       analyze_and_fix_selector
       (error message + screenshot path + spec context + rule bundle)
            │
            ▼
       validate_and_apply_fix  ←── LOCKED DOOR: enforces LOCATOR_RULES
            │
            ├── error violations  ──→ regenerate fix, retry validate
            │
            └── ok
                    │
                    ▼
               run_test_and_analyze_failure (attemptNumber + 1)
               (loop until pass or shouldStop)

Rule Evolution Lifecycle

[Automated Loop]           [Human Review]           [Governance Workflow]
propose_rule_evolution  →  PENDING in queue  →  mark APPROVED / REJECTED
                                                          │
                                             "apply approved rules"
                                              triggers rule-evolution-review.mdc
                                                          │
                                             ┌────────────▼────────────┐
                                             │ writes to .mdc file     │
                                             │ removes from Pending    │
                                             │ appends to History Log  │
                                             └─────────────────────────┘

The "trainable parameters" are .mdc rule files — not model weights. The system improves without retraining anything.

Prerequisites

Node.js 18+
Cursor with MCP support
Playwright installed in your project (npm install -D @playwright/test)

Installation

Option A — npm (recommended)

# Install as a dev dependency in your Playwright project
npm install -D playwright-fixer-mcp

Option B — Clone from GitHub

git clone https://github.com/your-username/playwright-fixer-mcp.git
cd playwright-fixer-mcp
npm install

Setup

After installation, run the setup command to copy the Cursor rule templates into your project:

# From your Playwright project root
npx playwright-fixer-mcp setup

# With an explicit project root
npx playwright-fixer-mcp setup --project-root=/path/to/your/project

# Force overwrite existing rule files
npx playwright-fixer-mcp setup --force

This copies four files into .cursor/rules/ in your project:

File	Layer	Purpose
`playwright-mcp.mdc`	Governance	Workflow trigger, closed-loop procedure, hard constraints
`playwright-test-standards.mdc`	Knowledge	Locator priority, DSL conventions, evolved heuristics
`rule-evolution-review.mdc`	Governance	Rule promotion workflow (human-triggered)
`rule-evolution-queue.md`	Queue	Pending / history log for rule proposals

Note: rule-evolution-queue.md is never overwritten if it already contains [PENDING] entries, even with --force. Your pending proposals are safe.

Cursor MCP Configuration

Add to your Cursor MCP config. Create .cursor/mcp.json in your project root (or add to Cursor → Settings → MCP):

If installed as dev dependency

{
  "mcpServers": {
    "playwright-fixer": {
      "command": "node",
      "args": ["./node_modules/playwright-fixer-mcp/index.js"]
    }
  }
}

If cloned locally

{
  "mcpServers": {
    "playwright-fixer": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-fixer-mcp/index.js"]
    }
  }
}

Restart Cursor after adding the configuration. Verify the server appears under MCP tools.

Usage

Running a Test by Tag

Type a test tag in the Cursor chat — the closed-loop repair activates automatically:

@AUT-589-1

npx playwright test --grep @AUT-589-1

The system will:

Find the spec file containing @AUT-589-1 (via resolve_spec_by_tag)
Read the full spec + page object to understand test intent (via read_spec_file)
Run the test (via run_test_and_analyze_failure)
If it fails: collect screenshot + error → analyze → generate fix → validate against locator rules → apply → re-run
If it passes: propose the learned fix pattern as a rule update (propose_rule_evolution)

The loop retries up to 2 times before stopping and escalating to human review.

Reviewing and Promoting Rule Proposals

After a successful auto-fix, a PENDING entry is written to .cursor/rules/rule-evolution-queue.md.

To review and promote:

Open .cursor/rules/rule-evolution-queue.md
Read the proposed rule under ## Pending (awaiting review)
Change  to either  or 
Tell Cursor: "apply approved rules"

The rule-evolution-review.mdc governance workflow activates:

Appends approved rules to the target .mdc file
Removes the entry from the Pending section
Writes a permanent record to the History Log

Hard constraint: The AI cannot self-approve. Only entries the human has explicitly marked are processed.

Project Structure (after setup)

your-project/
├── .cursor/
│   ├── mcp.json                             ← Cursor MCP server config
│   └── rules/
│       ├── playwright-mcp.mdc               ← Governance: workflow + hard constraints
│       ├── playwright-test-standards.mdc    ← Knowledge: locators, DSL, evolved rules
│       ├── rule-evolution-review.mdc        ← Governance: rule promotion procedure
│       └── rule-evolution-queue.md          ← Queue: pending/history rule proposals
├── tests/
│   └── **/*.spec.js                         ← Your Playwright specs (tagged @AUT-xxx)
├── node_modules/
│   └── playwright-fixer-mcp/
│       └── index.js                         ← MCP server (Capability layer)
└── package.json

Test Tag Format

Every test must use the @AUT-xxx tag format for the system to locate and run it:

import helperFunctions from '../helpers.js';
import PageObjectName from '../../pageObjects/PageObjectName.js';

test("description @BaseCase @PageName @testCaseName @AUT-xxx", async () => {
  const { browser, context, page } = await helperFunctions.setup_Backgound_Step();
  const pageObj = new PageObjectName(page);
  await helperFunctions.given_A_Page(page, PageObjectName);
  await helperFunctions.click(page, pageObj.someButton);
  await helperFunctions.check_Element_Contains_Text(page, pageObj.result, 'expected text');
  await browser.close();
});

Always use helperFunctions — direct page.click() / page.fill() calls bypass the failure normalization layer that the CONTEXT_RESOLVERS depend on.

Failure Normalization

The system uses a DSL layer (helperFunctions) to convert raw Playwright errors into semantic signals:

// Raw Playwright error (no semantic information for the system):
// Timeout 5000ms exceeded

// Normalized error from helperFunctions (classifiable):
throw new Error(`Element "${elementName}" not found with selector: ${selector}`);

This is how CONTEXT_RESOLVERS deterministically classifies failures into hover, fill, iframe, or default — without LLM inference.

Locator Rules (Enforced)

validate_and_apply_fix is the only valid write path to spec files. It enforces these constraints before writing:

Rule ID	Severity	Description
`NO_XPATH`	error	XPath locators are blocked. Use `getByRole`, `getByLabel`, or `getByText`.
`IFRAME_USE_FRAME_LOCATOR`	error	In iframe context, `page.locator()` is blocked — must use `frame.locator()`.
`CSS_CLASS_SELECTOR`	warn	CSS class selectors are warned. Prefer semantic locators.

Error-level violations block the write and return the violation list. The model must regenerate a compliant fix and call validate_and_apply_fix again.

Locator Priority (highest → lowest)

1. getByRole('button', { name: '...' })   ← preferred
2. getByLabel('...')
3. getByPlaceholder('...')
4. getByText('...')
5. [data-testid] / [data-qa]
6. CSS class selectors                     ← warn
7. XPath                                   ← blocked

Tool Reference

Automated Loop Tools (Layer 2 — Capability)

Tool	Description
`run_test_and_analyze_failure`	Run `npx playwright test --grep @<tag>`. Returns `passed`, `resolvedContext`, error artifacts. Enforces retry stop-loss (max 2 attempts before `shouldStop: true`).
`analyze_and_fix_selector`	Build a fix suggestion payload from error message + screenshot path + resolved failure context + rule bundle. Returns structured guidance for the model.
`validate_and_apply_fix`	Validate proposed code changes against `LOCATOR_VIOLATION_RULES`, then write to spec. The only valid write path. Returns violations if blocked.
`resolve_spec_by_tag`	Scan `tests/` to find the spec file containing a given `@AUT-xxx` tag. Deterministic — never guess.
`read_spec_file`	Read the full spec + auto-resolve its imported page object. Provides complete test context before analysis.
`read_page_object_selectors`	Extract getter → elementName → selector mapping from a page object file.
`get_failure_artifacts`	Scan `test-results/` for the latest screenshot and trace.zip. Optionally filter by tag.
`get_iframe_context`	Extract iframe selector and frame-related operations from a spec + page object.
`propose_rule_evolution`	Write a learned fix pattern as a `PENDING` proposal to the rule evolution queue. Does not modify any `.mdc` file — human approval required.

Reference / Info Tools

Tool	Description
`get_playwright_fix_workflow`	Return the full fix workflow reference (read spec → run → fail → fix → verify → evolve).
`get_internal_locator_rules`	Return the locator priority rules.
`get_tag_run_rule`	Return the tag trigger rule (when `@AUT-xxx` triggers the closed loop).

Not an MCP Tool (by design)

apply_approved_rules — This is a governance operation triggered by human intent ("apply approved rules"), not by the automated loop. It lives in rule-evolution-review.mdc as a Cursor rule procedure. Keeping it out of index.js enforces the architectural boundary: the executor cannot promote its own rule proposals.

Customization

Adding a New Failure Context

Edit index.js to add a new entry to both CONTEXT_RESOLVERS and FAILURE_CONTEXT_MAP:

// In CONTEXT_RESOLVERS — detection pattern
const CONTEXT_RESOLVERS = [
  // ...existing entries...
  {
    contextKey: "select",
    test: (msg) => /selectOption|dropdown|ant-select/i.test(msg || ""),
  },
];

// In FAILURE_CONTEXT_MAP — instructions and rule blocks for this context
const FAILURE_CONTEXT_MAP = {
  // ...existing entries...
  select: {
    instruction: "3. **This error relates to a dropdown/select**: use `getByRole('option')` or `page.selectOption()`.\n",
    extraRuleBlocks: [],
  },
};

No other code changes required. The resolver runs first-match-wins.

Adding a Custom Locator Violation Rule

const LOCATOR_VIOLATION_RULES = [
  // ...existing rules...
  {
    id: "NO_DATA_TESTID_WHEN_ROLE_EXISTS",
    severity: "warn",
    test: (code) => /\[data-testid\]/i.test(code),
    message: "Prefer getByRole over data-testid when a semantic role exists (LOCATOR_RULES).",
  },
];

severity: "error" blocks the write. severity: "warn" allows it but surfaces the issue.

Adjusting the Retry Limit

const MAX_AUTO_RETRIES = 3; // stop at attempt 3; allows attempts 1 and 2

Increase for environments with higher test flakiness.

Stage Evolution

This tool implements Stages 2–4 of the AI automation evolution path:

Stage 1 → Static rules in skill.md
           (AI reads knowledge before acting)

Stage 2 → MCP selects rule bundles by context     ← CONTEXT_RESOLVERS
           (System decides the framework)

Stage 3 → Closed verification loop                ← repair loop in playwright-mcp.mdc
           (Outputs become testable hypotheses)

Stage 4 → Rules evolve based on execution results ← rule-evolution-queue.md
           (System improves without retraining)

Stage 5 → Self-improving governed AI environment  ← you build this on top
           (The environment becomes the intelligence layer)

The "trainable parameters" are rule bundles in .mdc files — not model weights.

Architecture Articles

This tool was built based on the following series:

Stop Prompting Your Way Out of Playwright Failures — The state reconstruction problem and closed-loop architecture
The Environment Is the Prompt: Why MCP Rules Supersede Static Skill Files — Knowledge vs. constraints; why governance belongs in the environment
Rules That Learn: How We Built a Self-Improving Test Governance System — The execution context separation; why apply_approved_rules is not an MCP tool
The Three Layers of AI Automation Systems — Knowledge / Capability / Governance — and the cost of mixing them

License

MIT

Available Tools

12 tools

analyze_and_fix_selectorAnalyze and fix Playwright selectorA

Analyze Playwright failure: require reading the full spec for context first; use error message + screenshot path (and optional DOM snapshot) to suggest a stable locator fix (getByRole preferred).

ParametersJSON Schema

Name	Required	Description
`domSnapshot`	No	HTML snippet at failure time (e.g. from trace or snapshot)
`errorMessage`	Yes	Playwright error message or stack snippet
`originalCode`	No	Relevant test/spec code snippet that failed (full spec should still be read for context)
`specFilePath`	No	Full path to the spec file (Cursor should read entire file for context before fixing)
`failureContext`	No	Failure context: pass 'hover' \| 'fill' \| 'iframe' \| 'default' to include the corresponding rule and instruction (default: 'default')
`screenshotPath`	No	Path to failure screenshot (e.g. test-results/.../test-failed-1.png); analyze screenshot with error message

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations, the description carries the transparency burden. It discloses a prerequisite (read full spec), inputs to use, and that the fix should prefer getByRole. However, it does not state whether the tool modifies files (though 'suggest' implies non-mutating), how the fix is returned, or limitations on multiple failures.

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

Conciseness5/5

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

The description is a single, dense sentence that front-loads the purpose. Every phrase serves a function: 'Analyze Playwright failure' states the task, 'require reading the full spec for context first' gives a prerequisite, and the rest specifies inputs and output preference. No wasted words.

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

Completeness3/5

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

Given 6 parameters, no output schema, and no annotations, the description covers the primary workflow but leaves gaps: it doesn't explain the return format, how originalCode/failureContext should be used, or what constitutes a stable locator beyond getByRole. It is adequate for a simple analysis tool but not fully comprehensive.

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

Parameters3/5

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

Schema description coverage is 100%, so all six parameters are already described. The description adds minimal parameter-level guidance, only highlighting errorMessage, screenshotPath, and domSnapshot. It does not add semantics beyond the schema, so baseline 3 is appropriate.

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

Purpose5/5

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

The description clearly states the tool's purpose: 'Analyze Playwright failure' and 'suggest a stable locator fix'. It distinguishes from siblings by focusing on analysis and fix suggestion, whereas tools like get_playwright_fix_workflow provide workflow guidance and run_test_and_analyze_failure executes tests.

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

Usage Guidelines4/5

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

The description gives explicit context: 'require reading the full spec for context first' and tells the agent to use 'error message + screenshot path (and optional DOM snapshot)'. It does not explicitly mention when not to use this tool or alternatives, but the workflow is clear enough.

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

get_failure_artifactsGet failure artifacts from test-resultsA

Scan the test-results directory for failure artifacts: latest screenshot path, trace.zip path. Provides deterministic artifact location so the model never guesses where failure evidence is stored. The model should open the screenshot and pass screenshotPath + tracePath into analyze_and_fix_selector.

ParametersJSON Schema

Name	Required	Description	Default
`tag`	No	Test tag to narrow results to a specific subdirectory (optional, e.g. AUT-589-1)
`projectRoot`	No	Project root path (defaults to cwd)

TDQS

A4.5/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses that the tool scans the test-results directory and returns deterministic artifact locations, and it implies the output fields ('screenshotPath + tracePath') via the instruction to pass them into the analyzer. This is sufficient for a read-only search tool. It does not mention error behavior when no artifacts are found, but that is a minor gap.

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

Conciseness5/5

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

The description is just two sentences. The first states the action and outputs, the second provides a deterministic guarantee and the next step. Every sentence contributes essential information with no redundancy or filler.

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

Completeness5/5

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

For a simple tool with no output schema and only two optional parameters, the description tells the model what it returns (screenshot path, trace.zip), how it behaves (deterministic), and what to do next (pass into analyze_and_fix_selector). It is well-integrated into the workflow and covers the essential context for correct invocation. Missing artifact handling is not critical given the tool's simplicity.

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

Parameters3/5

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

The input schema already includes full descriptions for both parameters (tag and projectRoot), achieving 100% schema description coverage. The description adds little beyond the schema; it does not explain how tag or projectRoot affect the scan. The example value 'AUT-589-1' is in the schema, not the description. Thus, the baseline score of 3 is appropriate.

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

Purpose5/5

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

The description uses the specific verb 'Scan' and clearly identifies both the target resource ('test-results directory') and the output artifacts ('latest screenshot path, trace.zip path'). It distinguishes itself from the sibling tool 'analyze_and_fix_selector' by positioning itself as the retrieval step, making its purpose precise and unambiguous.

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

Usage Guidelines5/5

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

The description explicitly instructs the model to 'pass screenshotPath + tracePath into analyze_and_fix_selector', giving a clear next step and the condition for use (whenever failure artifacts are needed). It also explains the benefit ('deterministic artifact location so the model never guesses'), which clarifies why this tool should be used instead of guessing paths. While it doesn't list negative conditions, the directive is strong and actionable.

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

get_iframe_contextGet iframe context from specA

Extract iframe selector and frame-related operations from a spec file and its page object. Returns the iframe locator string, count of frame operations, and enforcement reminder. Call this for any failure whose context is 'iframe' to provide deterministic frame structure before calling analyze_and_fix_selector — the model must never guess the iframe selector.

ParametersJSON Schema

Name	Required	Description	Default
`specFilePath`	Yes	Absolute path to the spec file

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states what the tool returns ('iframe locator string, count of frame operations, and enforcement reminder') and emphasizes the deterministic nature of the result. It does not mention error handling or side effects, but for a read-only extraction tool, the disclosed behavior is sufficient.

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

Conciseness5/5

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

The description is two sentences long, front-loaded with the core action, and every sentence adds essential information. There is no filler or repetition of schema details, making it highly concise and well-structured.

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

Completeness5/5

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

Given a single parameter and no output schema, the description is complete: it explains what the tool does, what it returns, and exactly when to invoke it. It also integrates well with sibling tools by directing the calling sequence, leaving no critical gaps for an agent to guess.

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

Parameters4/5

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

The schema describes specFilePath as 'Absolute path to the spec file' (100% coverage). The description adds meaning by noting the tool also reads 'its page object' and returns specific frame-related context, which goes beyond the raw parameter definition and helps the agent understand the tool's broader operation.

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

Purpose5/5

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

The description uses a specific verb ('Extract') and resource ('iframe selector and frame-related operations'), clearly distinguishing it from sibling tools like analyze_and_fix_selector or read_spec_file. It also states the source (spec file and page object), making the tool's function unambiguous.

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

Usage Guidelines5/5

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

The description explicitly states when to use the tool: 'Call this for any failure whose context is ''iframe''' and positions it as a prerequisite before analyze_and_fix_selector. It also provides a strong exclusion rule: 'the model must never guess the iframe selector,' making the usage guidance direct and actionable.

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

get_internal_locator_rulesGet internal locator rulesA

Return company internal Playwright locator rules (getByRole preferred, no XPath).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior3/5

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

With no annotations, the description carries the full burden. It discloses that the tool returns rules and adds the behavioral detail that the rules prefer getByRole and disallow XPath. However, it does not specify the return format (e.g., list, object) or whether any read-only guarantees exist, leaving some ambiguity for a zero-parameter getter.

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

Conciseness5/5

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

The description is a single, crisp sentence that front-loads the verb 'Return' and packs key details into a parenthetical. Every word contributes value, and there is no redundancy or filler.

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

Completeness4/5

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

For a simple getter with no parameters and no output schema, the description provides enough context about the tool's purpose and the nature of the returned rules. It could mention the return structure or that the rules are static, but the tool's simplicity makes this a minor gap rather than a critical omission.

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

Parameters4/5

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

The tool has zero parameters, and the schema confirms this with an empty properties object. The baseline for zero parameters is 4, and the description adds no unnecessary parameter details, so the score reflects that the schema fully covers the parameter aspect.

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

Purpose5/5

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

The description clearly states that the tool returns company internal Playwright locator rules, and specifies the content preference (getByRole preferred, no XPath). This distinguishes it from sibling tools that handle rule evolution, tag rules, or workflow fixes, so the purpose is unambiguous.

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

Usage Guidelines4/5

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

The description conveys a clear use case: retrieve internal Playwright locator rules. It does not explicitly mention when not to use it or name alternatives, but the context of 'internal' and the sibling tool names provide enough situational clarity for an agent to decide when this tool is appropriate.

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

get_playwright_fix_workflowGet Playwright fix workflowA

Return the recommended workflow when fixing Playwright tests: (1) Read the entire test case first for context, (2) On failure, analyze the screenshot together with the error message.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It fully discloses what the tool returns (the two-step workflow) and implies no side effects or additional behavior. There are no hidden mutations, auth requirements, or rate limits to disclose, making it adequately transparent.

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

Conciseness5/5

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

The description is a single sentence with a numbered list of two steps. It is front-loaded with the purpose and does not waste words. Every element earns its place, making it highly concise and well-structured.

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

Completeness5/5

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

For a simple zero-parameter tool with no output schema, the description is complete. It specifies exactly what the tool returns and the context in which it applies. The information is sufficient for an agent to select and invoke the tool correctly without any ambiguity.

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

Parameters4/5

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

The tool has zero parameters, and the schema confirms this with an empty properties object. Per the baseline for 0-parameter tools, a score of 4 is appropriate since there are no parameter semantics to clarify.

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

Purpose5/5

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

The description clearly states the verb 'Return' and the specific resource: 'the recommended workflow when fixing Playwright tests'. It provides the actual workflow steps, making the tool's purpose unmistakable and distinct from siblings like 'analyze_and_fix_selector' or 'get_failure_artifacts'.

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

Usage Guidelines4/5

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

The description provides clear context: use this tool when fixing Playwright tests to obtain the recommended workflow. It does not explicitly mention alternatives, but the context is sufficient for a zero-parameter informational tool. The workflow steps imply it should be consulted before applying fixes.

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

get_tag_run_ruleGet tag run ruleC

Return the rule: when user inputs npx playwright test --grep @AUT-xxx or @AUT-xxx (test tag), automatically trigger MCP run. Call run_test_and_analyze_failure first; on failure use its return to call analyze_and_fix_selector.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden. It says 'Return the rule' implying a read-only operation, but it does not disclose side effects, permissions, or return structure. The second sentence embeds instructions to call other tools, which is confusingly mixed into the tool's behavior description, potentially misleading about what the tool actually does.

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

Conciseness3/5

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

The description is relatively short and front-loaded with 'Return the rule', but the second sentence is a run-on that mixes rule definition with imperative workflow instructions. It could be split into separate concerns: one sentence for what the tool returns, and another for contextual usage guidance if needed. Some content feels tangential to the tool itself.

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

Completeness2/5

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

Given the tool has no parameters and no output schema, the description must clarify what the rule is and how to use it. It explains the trigger conditions but does not specify the return value's format or how to interpret it. The embedded instruction to call other tools suggests the description is trying to define a workflow rather than describe this tool's invocation, leaving the agent uncertain about what to do with the returned rule.

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

Parameters4/5

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

The tool has zero parameters and the schema is empty with 100% coverage. The description adds no parameter details, but the baseline for 0-parameter tools is 4, as there is no parameter information burden. The description focuses on the tool's purpose rather than parameter formatting.

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

Purpose4/5

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

The description starts with 'Return the rule', clearly indicating the tool returns some rule content, and the content is about tag-triggered MCP runs. This distinguishes it from sibling tools like analyze_and_fix_selector or run_test_and_analyze_failure. However, it doesn't specify the return format or whether it's a string, object, or instruction set, leaving some ambiguity.

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

Usage Guidelines2/5

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

The description does not state when to use this tool versus alternatives. Instead, it instructs the agent to call run_test_and_analyze_failure first and then analyze_and_fix_selector on failure, which is guidance for a workflow involving other tools, not for selecting get_tag_run_rule. No exclusions or alternatives are mentioned.

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

propose_rule_evolutionPropose rule evolution from fixA

After a test passes following an automated fix, propose the learned pattern as a new rule entry. This tool writes the proposal to a PENDING queue file for human review — it does NOT modify any .cursor/rules files directly. A human must mark the entry APPROVED before it can be applied. This is the governance layer: the AI proposes, the human decides.

ParametersJSON Schema

Name	Required	Description
`fixSummary`	Yes	One-sentence description of what the fix did (e.g. 'hover all sibling buttons before asserting tooltip text')
`projectRoot`	No	Project root (defaults to cwd)
`errorPattern`	Yes	Short description of the error pattern that triggered this fix (e.g. 'ant-tooltip-inner not visible after hover')
`proposedRule`	Yes	The rule text to add — written as a concrete, actionable instruction for future fixes (markdown ok)
`failureContext`	Yes	The failure context this rule applies to
`targetRuleFile`	Yes	Which .cursor/rules file this rule belongs to (without .mdc extension). Use 'playwright-test-standards' for locator/DSL/spec conventions; 'playwright-mcp' for workflow/trigger/closed-loop rules. Custom rule files added by the team are also accepted.

TDQS

A4.4/5.0

Behavior5/5

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

With no annotations, the description fully discloses key behavioral traits: it writes to a PENDING queue, does not modify .cursor/rules files, and requires human APPROVAL before application. This gives the agent a clear safety profile and workflow understanding.

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

Conciseness5/5

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

Four sentences, each earning its place: purpose, write target, approval requirement, and governance summary. Information is front-loaded and there's zero waste.

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

Completeness4/5

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

The description covers the core behavior and workflow adequately. It doesn't explain return values or file naming, but given no output schema and 100% parameter coverage, the essential context is present. A minor gap is not specifying what the tool returns on success or whether it errors on duplicate proposals.

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

Parameters3/5

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

Schema description coverage is 100%, so parameters are already well-documented. The description does not add parameter-specific details, but it provides useful workflow context (e.g., 'learned pattern', 'PENDING queue') that reinforces the purpose. Baseline 3 is appropriate.

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

Purpose5/5

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

The description states exactly what the tool does: propose a learned pattern as a new rule entry after a test passes following an automated fix. It distinguishes from siblings by emphasizing it writes to a PENDING queue and does NOT modify rules files directly, clarifying its governance role.

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

Usage Guidelines4/5

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

It gives a clear trigger condition ('after a test passes following an automated fix') and contrasts with direct file modification. It doesn't explicitly name alternative tools like validate_and_apply_fix, but the governance framing makes when to use it unambiguous.

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

read_page_object_selectorsRead page object selector definitionsA

Extract all selector definitions from a page object file. Returns a getter → elementName → selector mapping so the model sees the exact CSS/attribute selectors in use — essential for diagnosing broken selectors without guessing. If structured extraction fails, returns the raw file content as fallback.

ParametersJSON Schema

Name	Required	Description	Default
`pageObjectPath`	Yes	Absolute path to the page object file

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden. It discloses the success output format and the fallback behavior when structured extraction fails. It does not mention error cases beyond the fallback, but for a read-only extraction tool this is substantial transparency.

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

Conciseness5/5

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

The description is two sentences, both information-dense. The first states the action and outcome, the second adds purpose and fallback. No redundant wording or filler.

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

Completeness5/5

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

For a simple one-parameter read tool with no output schema, the description is complete: it states what is extracted, the mapping format, the purpose, and the fallback if extraction fails. Nothing essential is missing.

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

Parameters3/5

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

Schema description coverage is 100% for the single parameter, pageObjectPath, which is fully described as an absolute path. The description adds no additional parameter-specific information beyond the schema, so the baseline of 3 is appropriate.

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

Purpose5/5

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

The description clearly states the tool extracts all selector definitions from a page object file, with a specific verb and resource. It also describes the output mapping, distinguishing it from sibling tools like analyze_and_fix_selector by focusing on reading rather than modifying.

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

Usage Guidelines4/5

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

The description gives clear context for when to use this tool: 'essential for diagnosing broken selectors without guessing.' It does not explicitly name alternatives or exclusions, but the read-only nature and diagnostic purpose imply when it is appropriate.

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

read_spec_fileRead spec file and page objectA

Read the full content of a spec file and auto-resolve its imported page object. Provides the model with complete, deterministic test context — full step flow, helper DSL calls, and selector definitions — before calling analyze_and_fix_selector. Never let the model guess about test intent; call this first.

ParametersJSON Schema

Name	Required	Description	Default
`specFilePath`	Yes	Absolute path to the spec file

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses that the tool auto-resolves imported page objects and provides complete deterministic context, which is useful behavioral information. However, it does not mention potential failure modes, whether it is strictly read-only, or any side effects, leaving some gaps.

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

Conciseness5/5

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

The description is two sentences, front-loaded with the action verb 'Read,' and every sentence adds value. It efficiently conveys purpose, output, and usage priority without unnecessary filler.

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

Completeness4/5

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description provides sufficient context about what it does and why it matters. It names the return context (step flow, DSL calls, selectors) and its role in the workflow, though it could mention error handling or what happens if the file is missing.

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

Parameters3/5

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

Schema coverage is 100% for the single parameter specFilePath, which is already described as 'Absolute path to the spec file'. The description adds no additional meaning to the parameter, so the baseline score of 3 applies.

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

Purpose5/5

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

The description clearly states the tool reads a spec file and auto-resolves its imported page object, naming specific content (full step flow, helper DSL calls, selector definitions). It distinguishes itself from siblings like analyze_and_fix_selector by positioning this as the prerequisite step.

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

Usage Guidelines4/5

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

The description explicitly says to call this tool before analyze_and_fix_selector and instructs 'Never let the model guess about test intent; call this first,' giving clear when-to-use guidance. It does not mention alternatives or when not to use it, but the primary use case is unambiguous.

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

resolve_spec_by_tagResolve spec file path by tagA

Resolve the absolute spec file path that contains a given @AUT-xxx tag by scanning test specs. This enables the required workflow: read the spec FIRST (read_spec_file) to understand intent, then run the test. Avoid guessing which spec to read — this tool deterministically finds it.

ParametersJSON Schema

Name	Required	Description
`tag`	Yes	Test tag with or without @ (e.g. AUT-589-1 or @AUT-589-1)
`projectRoot`	No	Project root to scan (defaults to cwd)
`maxFilesToScan`	No	Safety limit for number of spec files to scan (default: 500)

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the transparency burden. It discloses that the tool scans test specs, returns an absolute path, and is deterministic. While it doesn't explicitly state side effects or failure behavior, the nature of 'resolve' and 'scanning' implies a read-only operation. This is sufficient for a resolver tool.

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

Conciseness5/5

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

Two sentences, no filler. The first sentence states the action, the second provides workflow context and rationale. Every word earns its place, and the most critical information is front-loaded.

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

Completeness4/5

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

The description covers the tool's purpose, its position in the workflow, and the deterministic nature of the result. It also implies the return value (absolute path). Missing edge-case behavior (e.g., what happens if the tag is not found) but for a simple resolver, this is adequate.

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

Parameters3/5

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

The input schema covers all three parameters with descriptions (100% coverage), so baseline is 3. The description adds no additional parameter-specific meaning beyond the overall scanning behavior and references the @AUT-xxx tag format, which is already in the schema.

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

Purpose5/5

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

The description uses a specific verb and resource 'Resolve the absolute spec file path that contains a given @AUT-xxx tag', clearly distinguishing it from siblings like read_spec_file (which reads the file content). It also highlights the intended workflow, making the tool's unique role obvious.

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

Usage Guidelines4/5

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

The description explicitly states the workflow: use this tool first to find the spec, then call read_spec_file. 'Avoid guessing which spec to read' gives clear when-to-use context. It doesn't list alternative tools or when not to use it, but the context is strong enough for an agent to infer appropriate usage.

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

run_test_and_analyze_failureRun Playwright test and collect failure artifactsA

Run npx playwright test --grep @. Returns passed/failed + resolvedContext (hover/fill/iframe/default) + artifacts for analyze_and_fix_selector. Enforces retry stop-loss: returns shouldStop:true when attemptNumber >= 3, requiring human escalation.

ParametersJSON Schema

Name	Required	Description
`tag`	Yes	Test tag without @ (e.g. AUT-589-1); @ prefix is optional
`projectRoot`	No	Project root where to run playwright (default: current working directory)
`attemptNumber`	No	Current attempt number starting at 1. When >= 3, returns shouldStop: true to escalate to human instead of retrying.

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses that the tool executes an npx playwright command, returns passed/failed status, resolvedContext (with enumerated values), artifacts, and enforces a retry stop-loss policy. This adds valuable behavioral context beyond the schema. It does not mention side effects or environment dependencies, but these are less critical for a test runner.

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

Conciseness5/5

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

The description is two sentences, front-loaded with the command, then outputs, then retry policy. Every sentence conveys essential information without redundancy. It is concise and well-structured, making it easy for an agent to quickly grasp the tool's function.

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

Completeness4/5

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

For a tool with no output schema, the description identifies the primary outputs (passed/failed, resolvedContext with allowed values, artifacts, shouldStop) and references the downstream consumer (analyze_and_fix_selector). It covers the core usage scenario and termination condition. It could be more complete by describing the artifact format or error handling, but it is sufficient for an agent to invoke and interpret results.

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

Parameters3/5

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

The input schema already provides full descriptions for all three parameters (tag, projectRoot, attemptNumber), so the baseline is 3. The description adds minor context by illustrating the grep usage (@<tag>) and explaining the retry stop-loss behavior for attemptNumber, but this largely overlaps with schema descriptions. No significant new parameter semantics are introduced.

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

Purpose5/5

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

The description clearly states the action ('Run npx playwright test --grep @<tag>'), the resource (a Playwright test tagged with the provided tag), and the purpose (collect failure artifacts for analyze_and_fix_selector). It distinguishes this tool from siblings like get_failure_artifacts by emphasizing that it actually executes the test, not just retrieves artifacts.

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

Usage Guidelines4/5

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

The description gives clear context: use this tool to run a tagged test and obtain failure artifacts for downstream analysis. It also provides an explicit stopping condition (shouldStop at attemptNumber >= 3) with human escalation. However, it does not explicitly contrast with alternative sibling tools (e.g., get_failure_artifacts) or specify when not to use this tool, so it lacks explicit exclusions.

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

validate_and_apply_fixValidate and apply fix to specA

Validate proposed code changes against LOCATOR_VIOLATION_RULES (no XPath, no bare CSS classes, iframe must use frame.locator), then apply to spec file. Returns violations if any error-level rule is violated — model must fix and retry. This is the only valid path to write spec changes; direct file edits bypass LOCATOR_RULES enforcement.

ParametersJSON Schema

Name	Required	Description
`specFilePath`	Yes	Absolute path to the spec file to modify
`failureContext`	No	Failure context for context-specific validation (e.g. iframe enforces frame.locator usage)
`proposedChanges`	Yes	List of code replacements to apply in order

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description carries full responsibility for behavioral disclosure. It discloses the validation rules (no XPath, no bare CSS classes, iframe must use frame.locator), the application step, and the violation-return/retry behavior. It also explains enforcement consequences vs direct edits. However, it does not specify whether partial application occurs or the exact state of the file after a violation, which would improve transparency.

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

Conciseness5/5

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

The description is three sentences long and front-loaded with the core purpose. Every sentence earns its place: the first defines the action, the second covers return/retry behavior, and the third emphasizes enforcement. No redundant wording.

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

Completeness4/5

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

For a tool with no output schema and no annotations, this description gives a solid contract: validation rules, application, violation return, and retry directive. It could be more explicit about failure atomicity (whether any changes are applied when violations occur), but overall it is complete enough for an agent to invoke correctly.

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

Parameters3/5

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

Schema description coverage is 100%, with each parameter having a meaningful description. The tool description adds context about validation rules but does not provide additional detail on individual parameters beyond the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.

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

Purpose5/5

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

The description clearly states the tool validates proposed code changes against LOCATOR_VIOLATION_RULES and then applies them to a spec file. It distinguishes itself from sibling read/analysis tools by explicitly stating it is the only valid path to write spec changes, making its unique purpose unambiguous.

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

Usage Guidelines5/5

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

The description explicitly says 'This is the only valid path to write spec changes; direct file edits bypass LOCATOR_RULES enforcement,' providing a strong directive on when to use this tool. It also instructs the agent to fix and retry if violations are returned, covering the expected follow-up workflow.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

12 tool updatesv1.0.0Aug 2, 2026
- First observedanalyze_and_fix_selector
- First observedget_failure_artifacts
- First observedget_iframe_context
- First observedget_internal_locator_rules
- First observedget_playwright_fix_workflow
- First observedget_tag_run_rule
- First observedpropose_rule_evolution
- First observedread_page_object_selectors
- First observedread_spec_file
- First observedresolve_spec_by_tag
- First observedrun_test_and_analyze_failure
- First observedvalidate_and_apply_fix

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-08-02 09:55 across 12 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: running tests, analyzing failures, validating fixes, reading specs, resolving tags, retrieving artifacts, and managing rules. Even the three 'get_*' tools (workflow, locator rules, tag run rule) are unique and well-separated by their descriptions.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., analyze_and_fix_selector, run_test_and_analyze_failure, resolve_spec_by_tag). The verbs vary appropriately, but the naming scheme is uniform and predictable.

Tool Count5/5

With 12 tools, the server is well-scoped for its purpose. Each tool covers a distinct step in the Playwright fixing workflow, and the count is within the ideal 3-15 range, feeling neither sparse nor bloated.

Completeness5/5

The tool set provides full lifecycle coverage for the intended workflow: resolving/reading specs, running tests, collecting artifacts, analyzing and fixing selectors, validating changes, and proposing rule evolution. There are no obvious dead ends, and the flow from failure to fix is complete.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcpOAuth
ai.aient
MCP-native AI SRE: ask what's broken in production, get a reviewed GitHub fix PR.
Monitoring Observability Version Control
2
MCP Server By TestMu AIOAuth
com.lambdatest.mcp
Run, debug, and triage tests from your IDE using natural language, no dashboard switching, no manual data transfers. The TestMu AI (formerly LambdaTest) MCP Server is a single remote server exposing four tool suites: HyperExecute — analyze your project, generate YAML configs and test runner commands, then monitor jobs and sessions. Automation — pull a TestID's details plus command, network, and console logs into one chat for instant root-cause analysis. Includes mobile app upload. SmartUI — explain pixel, layout, DOM, and perceptual changes in a visual regression run, with context-aware React/HTML/CSS fixes. Accessibility — audit any public URL or a local React app against WCAG and get ready-to-apply remediation steps. Connects over https://mcp.lambdatest.com/mcp using OAuth 2.1 — no API keys in your config. One-click install in Cursor; works with Claude, GitHub Copilot, Cline, and any MCP client. Tests execute on the TestMu AI cloud: 3,000+ browsers and 10,000+ real devices.
Cloud Platforms Testing & QA Tools
1
mintqa-mcp
io.github.adamgusky
MCP server for Mint — AI-powered QA that runs your app in a real browser on every PR.
Testing & QA Tools CI/CD & DevOps
2
a2areplayreceipt-mcp
com.clauxel.a2areplayreceipt
Remote MCP for A2A failure replay MCP, structured receipts, audit logs, and reviewer-ready evidence.
Observability Monitoring Testing & QA Tools
2

Related MCP Servers

AWT (AI Watch Tester)
Testing & QA Tools Autonomous Agents AI & Machine Learning
ksgisang
A
license
Not graded
quality
D
maintenance
AI-powered E2E testing MCP server. Point at a URL — AI generates test scenarios, runs Playwright tests, and self-heals failures automatically. Works on Canvas and Flutter Web apps.
Updated 5 months ago (2026-04-15 03:46 UTC)
7
MIT
qa-ai-mcp-server-gits
Testing & QA Tools CI/CD & DevOps Developer Tools
gits5213
A
license
B
quality
D
maintenance
MCP server for end-to-end QA automation: generates test scenarios, discovers Playwright locators, creates TypeScript test code, executes tests, and creates GitHub issues for failures.
Updated 3 months ago (2026-06-12 20:07 UTC)
6
11 npm
MIT
mcp-lab-agent
Testing & QA Tools Autonomous Agents Developer Tools
Wesley-Gomes93
A
license
B
quality
D
maintenance
Autonomous QA testing MCP server that analyzes, fixes, and learns from test failures. Integrates with IDE and Slack to provide cause and fix in plain language.
Updated a month ago (2026-08-01 14:56 UTC)
31
12 npm
MIT
test-genie-mcp
Testing & QA Tools Code Analysis
MUSE-CODE-SPACE
A
license
B
quality
B
maintenance
Self-healing test automation MCP server that diagnoses and fixes issues in mobile and web apps, including a one-command vibe-check to prioritize broken functionality.
Updated 2 months ago (2026-07-06 14:07 UTC)
23
62 npm
MIT