mcp-a11y demonstrates solid domain-specific tool design with clear accessibility focus. All 7 tools have descriptions (194 - 392 chars, within baseline) and explicit input schemas with Zod validation. However, several tools lack output schema documentation, parameter descriptions are sometimes sparse, and error handling guidance is minimal. Tool naming is strong (verb_noun pattern: audit_page, fix_contrast, generate_alt_text). The open_pr tool includes a security guardrail comment but no formal permission-gate pattern. Most tools are READ_ONLY (safe), but open_pr is WRITE and lacks confirmation/dry-run support. Schemas are present but not all parameters are fully described (e.g., 'target' in fix_contrast lacks range/default clarity).

• Document output schemas for all tools. Add a 'outputSchema' field to tool registration or include a structured example in the description. E.g., audit_page should document: {violations: [{ruleId, description, selector, impact}], passes: [...], incomplete: [...]}.
• Add confirmation/dry-run support to open_pr. Implement a 'dry_run' boolean parameter (default false) that returns the PR diff without creating it. Require explicit confirmation for actual PR creation.
• Enhance parameter descriptions with defaults and constraints. E.g., 'target' → 'Target contrast ratio (default 4.5 for WCAG AA normal text, range 1.0 - 21.0)'. 'lang' → 'Language code for html lang attribute (default: en, ISO 639-1 format)'.
• Classify errors and provide recovery guidance. E.g., generate_alt_text error: 'Vision model failed: {reason}. Retryable: {true|false}. Next step: {retry|check API key|use imageUrl instead of selector}'.
• Add tool annotations (readOnlyHint, destructiveHint) to tool registration. Mark audit_page, fix_contrast, simple_fixes, generate_alt_text, generate_report as readOnly=true. Mark open_pr as destructive=true to signal side effects.