OverlayQA MCP gives AI coding agents accessibility and design-QA superpowers: audit live URLs for WCAG/contrast/token issues and manage OverlayQA issues and projects without leaving the editor.
scan_accessibility: Run a WCAG audit on any URL; get violations with severity, WCAG criteria, and an overall score.
scan_contrast: Check color-contrast ratios and get failing foreground/background element pairs.
audit_tokens: Audit a live page's design-system tokens and get a 0-100 health score plus findings (font sizes, colors, spacing, etc.).
scan_and_create_issues: Scan a URL and auto-create issues for every violation at or above a minimum severity.
create_issue: File a QA issue with title, severity, type, and description.
list_issues: List issues in a project, filtered by status and severity.
update_issue: Change an issue's status (open, in-progress, resolved, verified, closed).
create_project: Create a new project for a site URL.
list_projects: List all projects on your team.
compare_visual: Listed as coming soon; currently returns a not-implemented notice (use the OverlayQA browser extension for visual comparison).
Allows exporting OverlayQA issues to Asana projects for task management.
Allows comparing a live page against a Figma frame and auditing design tokens against a Figma file (coming soon).
Allows exporting OverlayQA issues to Jira for bug tracking and project management.
Allows exporting OverlayQA issues to Linear for issue tracking.
Allows exporting OverlayQA issues to Notion databases for project management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OverlayQA MCP Scan example.com for accessibility issues"
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.
OverlayQA MCP is a Model Context Protocol server that gives your AI coding agent accessibility and design-QA superpowers. Ask Claude Code, Cursor, or Windsurf to audit any URL for WCAG and color-contrast issues, then file dev-ready issues straight into your OverlayQA projects, without leaving your editor.
You: Scan staging.acme.com for accessibility issues, then open issues for the criticals.
Agent: scan_accessibility → 7 violations (2 critical, 3 high), score 71/100.
scan_and_create_issues → created 2 issues in "Acme Web":
- Buttons missing accessible names (WCAG 4.1.2) — critical
- Insufficient text contrast on .cta (WCAG 1.4.3) — high
You: List the open criticals.
Agent: list_issues(status=open, severity=critical) → 2 issues.One click:
Or add it to your editor's MCP config manually:
Claude Code (.mcp.json in your project root) / Cursor (~/.cursor/mcp.json) / Windsurf (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] }
}
}Any MCP-compatible client works the same way. On first run a browser tab opens to connect your OverlayQA account (free, no card). The token caches at ~/.overlayqa/auth.json for 30 days.
Related MCP server: Accessibility MCP Server
Ten tools your agent can call. Each is written so the model picks the right one from natural language.
Audit
Tool | What it does |
| Run a WCAG audit (axe-core) on any URL. Returns violations with severity, WCAG success criteria, and an overall score. |
| Check color-contrast ratios across a page. Returns the failing foreground/background element pairs. |
| Audit a live URL's design-system tokens. Returns a 0-100 token-health score and findings (inconsistent font sizes, text colors, spacing, font families, border radii) with severity. Audits the live page only. |
File and manage issues
Tool | What it does |
| Scan a URL and auto-create an issue for every violation above a severity threshold. |
| File a QA issue with title, severity, type, and description. |
| List issues in a project, filtered by status and severity. |
| Change an issue's status (open, in-progress, resolved, verified or closed), for example to mark it resolved after you fixed it. Takes the issue id or its display id such as OQ-12. |
| Create a project for a site URL. |
| List all projects on your team. |
Coming soon
Tool | What it does |
| Compare a live page against a Figma frame. |
Every tool also accepts an optional context argument: one sentence on why the agent is calling it. OverlayQA records that sentence, the tool name, your account, project and issue ids, counts and scores, the URL a scan runs on, and your editor's name and version (from the MCP handshake) as product analytics. The sentence is capped and stripped of email addresses and credential-like strings before it is stored. Nothing else travels: not your conversation, not your code, not the tool's replies. Full detail: overlayqa.com/privacy.
"Scan example.com for accessibility issues."
"Check the contrast on our pricing page and tell me what's failing."
"Scan staging.acme.com and create issues for anything critical or high."
"Create a high-severity accessibility issue: the login button has no focus ring."
"List the open critical issues in the Acme Web project."
"Create a project for shop.acme.com, then scan it."
Scans | Create issues & projects | |
Free | 3 / day, forever | — |
14-day trial | 30 / day | yes |
Paid | 10-30 / day by plan, unlimited on Pro | yes, with export to Linear / Jira / Asana / Notion |
Which editors does it work with? Claude Code, Cursor, Windsurf, and any MCP-compatible client (it speaks standard stdio MCP).
Is it free? Yes to start: 3 accessibility/contrast scans per day with no card. A 14-day trial raises that to 30 scans per day and unlocks issue and project creation. After that, creating issues and projects needs a paid plan (Pro has unlimited scans).
What does it actually scan? Any public URL. Accessibility uses axe-core mapped to WCAG success criteria; contrast checks foreground/background ratios and returns the failing element pairs.
Do I need an account? Yes, a free OverlayQA account. On first run a browser tab opens to connect it; the token caches locally for 30 days.
Does it work with the OverlayQA Chrome extension? Yes. The MCP server and the extension share the same projects and issues, so anything you file from your editor shows up in the extension and the dashboard, and vice versa.
The MCP server is one way into OverlayQA. The Chrome extension is the other: click any element on a live page and it captures a screenshot plus the CSS, DOM, and metadata into a dev-ready issue in seconds, and runs AI accessibility and design-system audits right on the page. Same projects, same issues, shared with this server.
Website: overlayqa.com
Chrome extension: Chrome Web Store
Free accessibility checker (no account): overlayqa.com/accessibility-checker
Free color-contrast checker (no account): overlayqa.com/color-contrast-checker
Pricing: overlayqa.com/pricing
Model Context Protocol: modelcontextprotocol.io
MIT
Audit a live URL's design-system token usage. Returns a 0-100 token-health score plus findings (inconsistent font sizes, text colors, spacing, font families, border radii) with severity and evidence. Audits the live page only; the figmaFileKey argument is accepted but Figma comparison is not yet available via MCP.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to audit for design token usage | |
| figmaFileKey | No | Optional Figma file key for token comparison |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the return structure (score + findings with severity/evidence), the live-only limitation, and the current non-functionality of the figmaFileKey argument. It does not explicitly state that the operation is read-only, but 'audit' implies it.
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?
Two sentences, front-loaded with the primary action, then the limitation. Every sentence earns its place with no unnecessary detail.
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 no output schema, the description provides a solid summary of the output (score + findings) and the return type. It gives examples of finding types and mentions severity/evidence. It could be more detailed about output structure, but it is adequate for a moderately complex audit tool.
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 coverage is 100% with descriptions for both parameters, so baseline is 3. The description adds meaningful context beyond the schema by clarifying that figmaFileKey is accepted but not yet functional, which is critical for agent expectations.
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 verb ('Audit'), the resource ('live URL's design-system token usage'), and the specific output (0-100 score and findings). It distinguishes from sibling tools like scan_accessibility and scan_contrast by focusing on design tokens.
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?
Provides clear context on scope: audits the live page only, and explicitly warns that figmaFileKey is accepted but Figma comparison is not yet available. It does not explicitly name alternative tools for different use cases, but the context is sufficient for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Coming soon — not yet implemented; the server returns a not-implemented notice (use the OverlayQA browser extension for visual comparison today). Will compare a live URL against a Figma frame and return visual differences and a match score.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The live URL to compare | |
| figmaNodeId | Yes | Figma node ID of the frame to compare against | |
| figmaFileKey | Yes | Figma file key (from the Figma URL) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It is transparent about the tool's current stub status and the server's not-implemented response, plus the intended future behavior. It lacks details about authentication or request requirements, but for an unimplemented tool this is sufficient and honest.
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 two sentences, front-loaded with the critical 'Coming soon' warning, and includes the alternative and intended capabilities without wasted words.
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?
For a stub tool with no output schema, the description provides everything needed: current status, server behavior, alternative tool, intended output, and parameter coverage is provided by the schema. No critical information is missing.
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 coverage is 100%, and each parameter has a clear description (URL, Figma file key, node ID). The description adds no extra parameter-level detail beyond reinforcing the comparison purpose, 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific future function: compare a live URL against a Figma frame and return visual differences and a match score. This clearly distinguishes it from sibling tools like scan_accessibility and audit_tokens, which address different quality concerns.
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 explicitly warns that the tool is not yet implemented, tells the agent the server will return a not-implemented notice, and directs users to the OverlayQA browser extension as a current alternative. This gives clear when-not-to-use and alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an issue in an OverlayQA project. Title is required; severity, type, and description default to medium / design-bug / empty.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Issue type (default: design-bug) | |
| title | Yes | Issue title | |
| severity | No | Issue severity (default: medium) | |
| projectId | Yes | Project to create the issue in | |
| description | No | Issue description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses default values for severity, type, and description, which is useful behavioral information. However, it does not mention return values, side effects, or permission requirements, and no annotations compensate for these 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 a single, well-structured sentence that front-loads the core purpose and packs defaults without waste.
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?
With no output schema and no annotations, the description should explain what the tool returns or any additional context. It covers the basic creation behavior and defaults, but omits return value information and usage context relative to siblings, making it minimally adequate.
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?
All parameters have schema descriptions, providing 100% coverage. The tool description adds the empty default for description and consolidates defaults for severity and type, which adds semantic value beyond the schema.
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 creates an issue in an OverlayQA project, specifying the action, resource, and context. It distinguishes from siblings by focusing on direct issue creation rather than scanning or listing.
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?
No explicit guidance is provided on when to use this tool versus alternatives like scan_and_create_issues. The mention of required title and defaults implies direct creation, but exclusions or alternative scenarios are not discussed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new OverlayQA project. Returns the project id, name, slug, displayPrefix, and url.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Primary URL for this project | |
| name | Yes | Project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It does reveal the return values (id, name, slug, displayPrefix, url), which is useful. However, it does not disclose potential side effects, error conditions, idempotency, or authentication requirements, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that states the action and the return values. It is concise, front-loaded, and every word adds value with no redundancy or filler.
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 the tool's simplicity (2 parameters, no nested objects) and the absence of an output schema, the description is near-complete: it names the action and the return fields. It could mention prerequisites or error scenarios, but for a straightforward create operation, it is largely sufficient.
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?
The input schema fully describes both parameters ('name' and 'url') with their meanings, so schema coverage is 100%. The description adds no additional parameter-specific semantics beyond what the schema already provides, so it meets the baseline of 3 without exceeding it.
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 a specific verb ('Create') and resource ('OverlayQA project'), making the tool's purpose immediately clear. It also distinguishes itself from sibling tools by mentioning the return values of a project creation operation, which none of the scanning/listing/issue tools provide.
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 implies its usage through the name and action, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or context (e.g., needing a project before initiating scans). The guidance is implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List issues in a project, optionally filtered by status and severity.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by status | |
| severity | No | Filter by severity | |
| projectId | Yes | Project to list issues from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It implies a read-only operation and mentions filtering options, but it does not disclose return format, pagination, or ordering. For a list operation, some additional detail about output or side effects would be expected.
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 a single, tightly written sentence with no redundancy. It front-loads the main purpose and concisely notes the optional filters, making it easy to parse.
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 the low complexity and 100% schema coverage, the description is mostly complete, but it does not describe the return value (e.g., an array of issues) or any behavioral details like pagination or sorting. Since there is no output schema, this information would be valuable for the agent to set expectations.
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%; each parameter (projectId, status, severity) already has a clear description in the schema. The tool description adds no extra semantic detail beyond restating that filters exist, 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List issues in a project, optionally filtered by status and severity' clearly states the verb (list), resource (issues), and scope (in a project, with filters). It distinguishes itself from sibling tools like create_issue (which creates) and list_projects (which lists projects).
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 clearly indicates this is for listing issues, implying when to use it. It does not explicitly name alternatives or exclusions, but the context of sibling tools makes the use case obvious. Lacks an explicit 'when not to use' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all OverlayQA projects in the authenticated user's team.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds context about authentication (user's team) and scope (all projects), but it does not explicitly state that the operation is read-only, or describe pagination or return format. For a simple list tool, this is adequate but not rich.
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 a single sentence that immediately states the verb and resource. It is front-loaded and contains no unnecessary words, making it highly efficient.
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?
For a zero-parameter tool with no output schema, the description sufficiently states what it does and the scope. It could mention alternatives or return details, but the purpose is clear enough for the agent to select and invoke it correctly.
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?
The tool has zero parameters, so the schema coverage is effectively 100%. The description does not need to explain parameters, and the baseline for 0 parameters is 4. No additional parameter semantics are required.
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 uses the specific verb 'List' with the resource 'OverlayQA projects' and scopes it to the authenticated user's team. This clearly distinguishes it from sibling tools like list_issues (for issues) and create_project (for creation).
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?
No guidance is given on when to use this tool versus alternatives. It does not mention that list_issues is for issues or create_project for creating projects, nor any exclusions or prerequisites. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an accessibility audit on a URL. Returns WCAG violations with severity, descriptions, and an overall score. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to scan for accessibility issues | |
| projectId | No | Optional project ID to associate results with |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of disclosure. It discloses the return format (WCAG violations with severity, descriptions, overall score), the one-page-per-call limitation, and quota counting. It does not explicitly mention authorization requirements or side effects, but the description gives meaningful behavioral context beyond a bare action statement.
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 three concise sentences: the primary action, the output, and the limitations/quota. There is no redundancy or filler, and every sentence earns its place. The most important information is front-loaded.
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?
For a simple two-parameter tool with no output schema, the description adequately explains what it returns (severity, descriptions, overall score) and the scope (one page per call) and quota. This is sufficient for an agent to invoke the tool correctly without additional documentation.
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?
Both parameters (url and projectId) are fully described in the schema, giving 100% schema description coverage, so the baseline is 3. The description does not add any additional parameter-specific semantics beyond what the schema already provides, such as formatting or constraints for the URL.
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 states 'Run an accessibility audit on a URL' with a clear verb and resource. It further specifies 'Returns WCAG violations with severity, descriptions, and an overall score,' which differentiates it from sibling tools like scan_contrast (focused on contrast only) and scan_and_create_issues (which implies creating issues). The scope is unambiguous.
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 usage context such as 'Scans one page per call' and quota limits ('Free plans include 3 scans per day'), which implies when to use it. However, it does not explicitly name alternative tools or say when not to use this tool, leaving that inference to the agent based on sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an accessibility scan on a URL and automatically create issues in the given project for each violation at or above the minimum severity. Returns scan summary + issue IDs created. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to scan | |
| projectId | Yes | Project to create issues in | |
| minSeverity | No | Minimum severity to create issues for (default: medium) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure. It reveals the mutating side effect (creating issues), the return value (scan summary + issue IDs), and usage limitations (one page per call, plan quotas). This is strong coverage, though it omits edge cases like no violations or authentication requirements.
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 three sentences long, with the main purpose front-loaded and no wasted words. It succinctly covers purpose, return value, and constraints, earning every sentence.
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?
For a tool with no output schema and no annotations, the description adequately captures the return format and key usage limits. It could improve by mentioning behavior when no violations are found, but the core workflow is complete enough for an agent.
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?
The input schema already documents all parameters with 100% coverage. The description adds minimal new semantic insight; it restates minSeverity as 'at or above the minimum severity' and implies projectId is the target, but these align with schema descriptions without enriching parameter meaning.
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 runs an accessibility scan and automatically creates issues for violations, specifying the verb, resource, and outcome. It distinguishes from siblings like scan_accessibility and create_issue by emphasizing the combined scan-and-create workflow.
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 operational constraints (one page per call, daily scan limits) but does not explicitly contrast with alternative tools such as scan_accessibility or create_issue. When to use this tool is implied by the combined functionality rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a color contrast audit on a URL. Returns elements failing WCAG contrast ratios with severity and details. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to scan for color contrast issues |
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 output behavior (returns failing elements with severity and details), the scope (one page per call), and rate limits. This is substantial behavioral context for a tool that performs audits.
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?
Three short sentences each convey a distinct piece of information: purpose, output, and usage limits. There is no redundancy or wasted wording.
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?
For a simple tool with one parameter and no output schema, the description adequately covers the purpose, output format, and limitations. It lacks details on error cases or specific WCAG level, but is sufficient for selecting and invoking the tool correctly.
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% for the only parameter (url), so the baseline is 3. The description does not add any additional semantic information about the URL beyond the schema's 'The URL to scan for color contrast issues'.
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 uses a specific verb 'Run' and precise resource 'color contrast audit on a URL', and states the output (elements failing WCAG contrast ratios with severity). This clearly distinguishes it from siblings like scan_accessibility or compare_visual.
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?
Provides clear context that this is for contrast audits, with the limitation of one page per call and rate limits (3 free scans/day). It doesn't explicitly mention alternatives or when not to use, but the purpose is so specific that usage is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.7audit_tokenscompare_visualcreate_issuecreate_projectlist_issueslist_projectsscan_accessibilityscan_and_create_issuesscan_contrastScored across 9 tools
The tools are mostly distinct, but scan_accessibility and scan_contrast overlap since contrast is a subset of accessibility, and scan_and_create_issues is a combination of scanning and issue creation. These overlaps are clarified by the descriptions, leaving only minor ambiguity.
All tool names follow a consistent snake_case verb_noun pattern (e.g., scan_accessibility, list_issues, create_project). The only compound verb, scan_and_create_issues, still fits the pattern and is readable.
With 9 tools, the server is well-scoped for its QA platform purpose, covering scanning, issue management, and project management. The count is neither too thin nor excessively heavy, and each tool contributes to the intended workflows.
The surface covers core scanning and issue/project creation/listing, but lacks update/delete operations for issues and projects, and the compare_visual tool is not yet implemented. These gaps prevent full lifecycle management and leave the visual comparison feature incomplete.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Give AI coding agents access to your Vynix visual feedback, bug reports, and AI diagnosis.
AI QA tester — real browsers scan sites for bugs, SEO, perf, and accessibility issues via chat.
Scan URLs for WCAG 2.1 violations, generate AI fixes, and produce VPAT 2.5 compliance reports.
