explain_finding

Get a detailed, human-readable explanation of a specific finding, including why it matters and its impact on users.

Description

The explain_finding tool provides comprehensive context about an accessibility or UX issue. Use it to understand why an issue matters before deciding how to fix it.

This tool bridges the gap between get_findings (what's wrong) and suggest_fix (how to fix it) by explaining the why.

Parameters

Parameter	Type	Required	Description
finding_id	`string`	required	Finding ID from get_findings response
audit_id	`string`	required	Parent audit ID containing the finding
detail_level	`'brief' \| 'standard' \| 'comprehensive'`	optional	Amount of detail to include. Default: 'standard'

Detail Levels

Level	Content	Use Case
`brief`	Quick summary, severity, basic impact	Triage, quick review
`standard`	Full explanation, WCAG reference, examples	Regular development
`comprehensive`	Everything + research citations, user testing insights	Compliance reports, education

Response

type

properties

Example Conversations

Standard Explanation

"Explain finding fnd_xyz789 from audit aud_abc123"

Returns a standard explanation with WCAG reference and impact.

Brief Explanation

"Give me a quick explanation of the button accessibility issue"

explain_finding({
  finding_id: "fnd_xyz789",
  audit_id: "aud_abc123",
  detail_level: "brief"
})

Comprehensive Explanation

"I need a comprehensive explanation of this color contrast issue for our compliance documentation"

explain_finding({
  finding_id: "fnd_xyz789",
  audit_id: "aud_abc123",
  detail_level: "comprehensive"
})

Contextual Questions

"Why does this button accessibility issue matter?"

Claude uses explain_finding to provide context about user impact.

When to Use

Situation	Use explain_finding
Triaging findings	Yes - understand severity
Before fixing	Yes - understand the problem
Creating tickets	Yes - include context
Learning	Yes - educational value
Compliance reports	Yes (comprehensive level)
Quick fix	Optional - go straight to suggest_fix

Workflow Position

audit_url → get_findings → explain_finding → suggest_fix
                               ↑
                     (understand before fixing)

Example Response

For a color contrast finding:

{
  "finding_id": "fnd_xyz789",
  "rule_id": "color-contrast",
  "severity": "serious",
  "explanation": "The text 'Subscribe to newsletter' has a contrast ratio of 3.2:1 against its background. WCAG requires a minimum ratio of 4.5:1 for normal text.",
  "impact": {
    "affected_users": [
      "Users with low vision",
      "Users viewing in bright sunlight",
      "Users with color deficiencies"
    ],
    "user_impact": "Users may struggle to read the text, leading to eye strain, slower reading speed, or complete inability to access the content.",
    "business_impact": "Could reduce newsletter signups by making the call-to-action difficult to read."
  },
  "wcag_reference": {
    "criterion": "1.4.3 Contrast (Minimum)",
    "level": "AA",
    "link": "https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html"
  },
  "examples": {
    "bad": "<p style='color: #999'>Subscribe to newsletter</p>",
    "good": "<p style='color: #595959'>Subscribe to newsletter</p>"
  },
  "related_findings": [
    {
      "id": "fnd_related123",
      "relationship": "Same element also has font-size issue"
    }
  ]
}

get_findings - Get the findings to explain
suggest_fix - Get code to fix the issue
Resources - Access UX guidelines

Was this page helpful?

explain_finding

On this page