Advanced Rules

Advanced Rules are a set of automated accessibility tests that use screenshots, computer vision, and large language models to catch issues standard axe-core cannot — such as headings that only look like headings, informative images with unhelpful alternative text, and text contrast over gradients or images.

The analyze tool can run Advanced Rules alongside the standard axe-core ruleset. When it does, advanced findings are merged into the same results array your agent already consumes, so no change to your prompts or workflow is required.

Advanced Rules are governed by your organization's axe Configuration, and — where your administrator allows it — can be overridden per server or per scan.

Accepted preset values

Advanced Rules that use AI report a confidence score rather than a definitive pass or fail, and a preset sets the threshold at or above which a finding is reported. For what each preset means and how to choose between them, see Confidence Controls — the thresholds are identical in every product that runs Advanced Rules.

Wherever the axe MCP Server accepts a preset — the advancedRules tool argument or the AXE_ADVANCED_RULES environment variable — these are the values it recognizes:

Values are case-insensitive and surrounding whitespace is ignored, so " Balanced " and "BALANCED" both resolve to balanced. There is no percentage alias for disabled.

Choosing a preset

There are three ways to set the preset. When more than one is present, the highest-precedence one wins:

1. The advancedRules tool argument — per scan
2. The AXE_ADVANCED_RULES environment variable — per server
3. Your organization's axe Configuration default — per organization

Whichever source is used, the resolved value is reported back in the response's advancedRules block, so your agent can always see which preset actually ran.

Organization default

Your organization's default comes from the Default Advanced Rules setting in axe Configuration, which an administrator manages in the axe Account Portal. That page documents the available options and the "Allow users to change" checkbox that decides whether the two overrides below are permitted at all.

Two things specific to the axe MCP Server:

• The server reads axe Configuration on every analyze call, so a change your administrator makes takes effect on your next scan — no server or client restart needed.
• If the setting is locked, the environment variable and tool argument are silently ignored and the response reports "source": "org_policy_locked", so you can tell an override was dropped rather than applied.

AXE_ADVANCED_RULES environment variable

Set AXE_ADVANCED_RULES in your MCP server configuration to pick a preset for every scan that server runs. This is the right place for a team-wide or project-wide choice that shouldn't have to be repeated in each prompt.

{
  "servers": {
    "axe-mcp-server": {
      "command": "npx",
      "args": ["-y", "axe-mcp-server"],
      "env": {
        "AXE_ACCESS_TOKEN": "<your-token>",
        "AXE_ADVANCED_RULES": "thorough"
      }
    }
  }
}

See the Configuration Reference for details, and your client setup guide for where the env block lives in your client.

Invalid Advanced Rules value: "high". Expected one of: 'precise' (90%), 'balanced' (70%), 'thorough' (50%), 'disabled'.

advancedRules tool argument

Pass advancedRules to a single analyze call to override the preset for that scan only. Prompt your AI agent in natural language — the agent translates your intent into the tool call:

Analyze http://localhost:3000 for accessibility issues using the
thorough advanced rules preset

The agent calls the analyze tool with a payload similar to:

{
  "url": "http://localhost:3000",
  "advancedRules": "thorough"
}

An invalid value here is a per-call schema validation error naming the accepted values; it does not affect the server or subsequent calls.

Use the tool argument when you want a one-off deviation — for example thorough on a page you're actively auditing, or disabled on a large page where you only want fast standard results:

Analyze http://localhost:3000 with advanced rules disabled

The advancedRules response block

Every analyze response includes an advancedRules block reporting the preset that actually ran and where it came from:

{
  "pageUrl": "http://localhost:3000",
  "data": [],
  "advancedRules": {
    "value": "balanced",
    "source": "org_default"
  }
}

value is always one of the four presets. source explains how that value was reached:

Fail-closed behavior

The axe MCP Server never guesses at a preset. If axe Configuration is reachable but the Advanced Rules setting is missing, or holds a value this version of the server doesn't recognize, the scan reports "value": "disabled", "source": "unavailable" and runs standard axe-core only — it does not fall back to a hardcoded preset. This keeps a version skew between your server and the axe Account Portal from silently applying a threshold nobody chose.

If axe Configuration cannot be fetched at all (network failure, invalid credentials), the analyze call fails outright rather than scanning with unknown settings. That is existing behavior for all settings, not specific to Advanced Rules — see Authentication errors.

When Advanced Rules don't run

An effective value of disabled means Advanced Rules are genuinely not loaded into the scan: no screenshot is captured for them, nothing is sent to Deque for evaluation, and no AI credits are consumed. Your standard axe-core findings are returned exactly as they otherwise would be.

If you asked for a preset that couldn't be honored because Advanced Rules aren't available to your server, the response's messages array says so:

Advanced Rules are not enabled for this server; the scan used standard axe-core only.

No message is emitted when you didn't ask for anything — a disabled organization default is a deliberate choice, not a problem to report.

Partial degradation

Advanced Rules never fail a scan. If the rules load but their server-side evaluation runs into trouble, analyze returns your standard axe-core results plus a message describing what was lost:

Availability

The axe MCP Server is included in the axe DevTools for Web bundle, and Advanced Rules come with it. If you have access to the axe MCP Server, you have Advanced Rules — there is no separate Advanced Rules purchase to make.

One thing can still leave them unavailable: Advanced Rules are evaluated server-side, so your deployment must be connected to Deque's AI infrastructure. Private cloud and on-premises deployments need the ML and LLM services — see the AI Feature Availability Guide. SaaS customers are connected out of the box.

If scans report "source": "unavailable" and you expect Advanced Rules to be available, contact your Customer Success Manager. Availability is resolved when the server starts, so restart the MCP server (or your MCP client) after a subscription change rather than expecting the next scan to pick it up.

What gets sent to Deque

Advanced Rules are the one case where analyze sends page data to Deque servers. When an active preset is resolved, the scan:

1. Captures a full-page screenshot in the browser and uploads it to Deque's screenshot endpoint.
2. Sends the recorder's evaluation payload — the page structure, computed styles, and geometry the advanced rules need — to Deque's advanced-rules endpoint, where the ML and LLM models evaluate it.
3. Merges the returned findings into your results.

Standard axe-core scanning is unaffected: with Advanced Rules disabled, the analyze tool sends nothing to Deque beyond authentication and configuration requests.

AI credits

Advanced Rules that use large language models consume AI credits from your organization's monthly allocation. Organizations with a dedicated Advanced Rules subscription are not charged credits.

When your credit balance is exhausted, the AI-powered advanced rules are skipped and the remaining advanced rules still run — the scan does not fail. See AI Credits for monitoring and purchasing.

Scan time

Advanced Rules add meaningful time to a scan — typically 15 to 20 seconds, on top of the screenshot capture and upload. If your scans start timing out after enabling Advanced Rules, raise BROWSER_TIMEOUT_MS (see the Configuration Reference) or use disabled for iteration and an active preset for a final check.

Reliability

Because some advanced rules use AI, results can vary slightly between runs on the same page. A finding reported at 75% confidence may score 65% on the next scan, which can change whether it clears your threshold. Results can also vary across machines and environments, since operating system, GPU, and display characteristics all affect rendering.

Treat a run-to-run difference in advanced findings as expected variance rather than a regression. See Limitations and Considerations for the full picture.

Relationship to other settings

• Experimental rules are independent. advancedRules: "disabled" does not disable experimental axe-core rules, and enabling experimental rules does not bypass your Advanced Rules preset. The two settings combine.
• There is no separate confidence-threshold option. The threshold is derived from the preset, matching axe Configuration and the axe DevTools Browser Extension.
• Accessibility standard, best practices, and needs review still apply. Advanced findings are filtered by the same axe Configuration settings as standard findings.