Accessibility/design QA via MCP: scan URLs for WCAG and contrast issues, audit design tokens, and manage OverlayQA projects and issues from your editor.
scan_accessibility — run an axe-core WCAG audit on a URL (optionally tied to a project); returns violations with severity and an overall score.
scan_contrast — check color-contrast ratios on a URL and list failing foreground/background element pairs.
scan_and_create_issues — scan a URL and auto-file an issue per violation at or above a chosen minSeverity in a given project.
audit_tokens — audit a live page's design-system tokens for a 0–100 health score plus findings (fonts, colors, spacing, radii); its figmaFileKey argument is inert since Figma comparison isn't available yet.
compare_visual — planned Figma-vs-live comparison; currently returns a not-implemented notice.
create_issue — file an issue with title, description, severity (critical/high/medium/low) and type (design-bug, design-gap, design-debt, accessibility, design-token).
list_issues — list a project's issues, filtered only by status and severity.
list_projects / create_project — list team projects or create one from a name and optional URL.
Note: the schema exposes far less than the README advertises — no update_issue, get_issue, move_issue, label, comment, or member tools, and create_issue takes no assignee; scan quotas (3/day free) apply as described in the README.
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 read, assign, discuss, label and resolve issues in 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
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, description and optional assignee. |
| Page through issues filtered by status, severity, type, labels, assignee, creator, page, creation time, or active/finished/ignored state. Each issue says who filed it and whether it still needs a reply. |
| Edit supplied issue fields, assignment, ignored state or status. Takes a UUID or display id such as OQ-12. |
| Create a project for a site URL. |
| List all projects on your team. |
| Read the workspace label library, assigned labels, and your permissions. |
| Create a reusable workspace label. |
| Apply or remove one label without changing issue text or other labels. |
| Rename a workspace label (owner/admin). |
| Delete a workspace label and its assignments; keep the issues (owner/admin). |
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 | no |
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
Use list_labels with a project UUID to see that workspace's labels and your permissions. create_label creates a reusable label; set_issue_label applies or removes it from one issue without changing its other labels or text. Workspace owners and admins can use rename_label and delete_label; deletion removes the label's assignments, not its issues. list_issues accepts labelIds (match any), including unlabeled. Shared reports preserve the names present when shared.
Local verification can set OVERLAYQA_API_BASE and an isolated OVERLAYQA_AUTH_FILE; neither changes the default production endpoint or normal saved login.
Requires the matching issue-parity API deployment. Existing scans and status updates remain compatible with 0.2.0.
Tool | What it does |
| Read description, ownership, labels, ignored state, screenshots, captured element/CSS, viewport evidence, and the issue's comments. |
| Filter by one or more statuses, severities or types; labels; assignee ( |
| Find teammate user IDs for assignment and mentions in a readable project's workspace. |
| Choose an assignee, use |
| Change any supplied title, description, severity, type, status, assignee or ignored flag. Omitted fields remain unchanged. Ignoring never resolves an issue. Setting verified records a status; it does not run a scan. |
| Move by stable issue UUID into another writable project in the same workspace; retain comments and evidence. Read the returned display ID afterward. |
| Read the discussion, audience, mentions and attachment metadata. |
| Post with explicit |
| Edit or delete your own native comments. Edits preserve audience and files. |
| Read a native comment file as filename and base64 bytes under the issue's access rules. |
For mentions, use @[userId] in the text and include the same ID in mentionedUserIds. Comment creation requires a UUID requestId: reuse it when retrying that same submission after a lost response, so a retry does not post twice. Attachments are base64 bytes with filename and MIME type, up to ten PNG/JPG/PDF files and 10 MiB total per comment.
list_issues defaults to all states for compatibility. Use state: "active" for open/in-progress issues that are not ignored. finished includes resolved/verified/closed issues that are not ignored; ignored selects the independent ignore flag. All supplied filters intersect. Pages start at 1 and contain up to 100 issues; an empty filtered page is not a complete-project result unless hasMore is false.
To poll for new feedback, pass createdAfter with the createdAt of the newest issue you have already seen (an ISO-8601 time with a zone, such as 2026-10-05T22:00:00Z); only issues created after it come back. pageUrl narrows the list to one page and ignores the query string. Each listed issue carries source (client means a reviewer filed it on a share link), commentCount, lastCommentAt and lastCommentBy (reviewer or team), so an issue still needs a reply when source is client and commentCount is 0, or lastCommentBy is reviewer. If the server has not been updated for a filter yet, the tool answers FILTER_NOT_SUPPORTED instead of an unfiltered list.
The label tools listed above are included in this release. Saved designs, scheduled reviews and Figma visual comparison remain outside this issue-management release. Client review tools are described below and require their matching server update.
Run npm test and npm run build. The live journey drives the built client over the real stdio protocol against a local API or production using designated fixture accounts; it creates and removes its own projects and produces JSON and HTML evidence.
MCP_PARITY_API=http://127.0.0.1:3241 MCP_SERVER_ENV=/path/to/server/.env npm run test:issues-live
MCP_PARITY_API=https://api.overlayqa.com npm run test:issues-liveRelease order: deploy and verify the server endpoints, then publish npm 0.3.0 and update the MCP registry. A local build or version bump is not a publication.
verify_issue({ issueId, requestId }) runs the same fix-verification engine as the dashboard on the issue’s saved public URL. The issue must be resolved, verified, or closed, have original screenshot evidence, and have a verifiable type (General and Improvement cannot be checked). Use a new UUID for each check; reuse that UUID only when retrying the same request after a lost response. Verification uses the workspace’s existing permissions and verification allowance and follows the server rollout setting.
The result contains a saved check ID, verdict, explanation, confidence, after-screenshot URL, capture context, and timestamps. A check can pass, pass with a caveat, fail, be inconclusive, or report an error. It never updates issue status. Inspect the evidence before deciding whether to change status with update_issue. Private or localhost pages require the browser extension’s signed-in capture.
get_issue_verifications({ issueId }) reads the latest 50 saved checks, newest first, without running another check. get_issue also includes latestVerification, or null when none exists. On an older server, an absent field means this capability has not been deployed; it does not mean the issue has never been checked.
list_issues accepts notDetected: true for issues flagged “No longer detected”, or false for issues without that flag (including issues never checked). It combines with status, state, page and other filters before pagination. The returned notDetectedAt and lastDetectedAt timestamps describe scan detection, not proof of a fix. A server that ignores this filter is refused as FILTER_NOT_SUPPORTED.
These additions need the matching server deployment before the client release. Both local and hosted MCP offer verification and saved history; hosted verification needs scan and write permission. This change does not enable verification in production.
These tools require the matching server deployment before publishing this client. The guest-options database migration must be applied before deploying that server. They are available on local and hosted MCP connections and use the app's project permissions.
Tool | What it does |
| Read a project's client links, titles, share URLs, capture status, visits, comments, completed reviewers, and each client's invitation/reminder state. |
| Create a live or snapshot review link, optionally with a title, client email addresses, a welcome note and private guest comments. Snapshot capture finishes asynchronously; read the list for readiness. |
| Revoke or restore a link, change its expiry, or change responsive previews. |
| Replace the complete client email list. Retained addresses keep their history; removed addresses stop reminders. An empty list removes all recipients while preserving the link. |
Creating a public link requires the user's intent to share. Adding email addresses requires their intent to invite those people. A new address may receive an invitation and automatic day 3/7/10 reminders. Read invitationsEnabled and the returned per-address invites: when delivery is off, addresses are saved with sent: false, skipped: true and may be invited after it is enabled. One failed invitation does not undo the link or successful invitations.
The list returns doneReviewers and clients with email, invitedAt, inviteFailed, lastReminderAt, done, commented, and unsubscribed. Done reviewing means a client finished giving feedback; it does not certify fixes or mean everyone is done. Only the client can perform that gesture. Reminder timing and stop conditions remain owned by the existing scheduler; there is no MCP send-now tool.
After an uncertain recipient-update response, retry the same complete list and reopen it; retained addresses are not invited twice. Creating a review does not have a retry key: after a lost response, use list_client_reviews to check for the saved link before creating another. Project viewers and read-only hosted connections can read progress but cannot change links or invite people.
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.
Free WCAG 2.2/ADA/508 accessibility MCP: scan, AI fixes, verify, vision audit, localhost tunnel
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.
