a11y-toolkit presents well-structured accessibility tools with strong semantic naming (verb_noun pattern) and comprehensive descriptions. All 23 tools follow consistent naming conventions (a11y_* prefix with clear action verbs: audit, suggest, generate, validate). Descriptions range 150-500 chars, well above the 10-char minimum and within the production baseline of 194 chars average. Input schemas are present for all tools with typed parameters and enum constraints where appropriate (lang: [es, en] throughout; browser enum in a11y_audit_dom; action enum in a11y_ledger). However, output schemas are NOT explicitly documented in the visible code, the server.py excerpt shows only tool registration with input schemas, not return types. This is a critical gap: LLMs cannot reason about downstream tool chaining without knowing what fields are returned. Error handling is minimal in the visible code; no recovery guidance or actionable error messages are apparent. Parameter descriptions are generally good (mode explanations, timeout defaults documented), but dependencies between parameters (e.g., informe being optional in a11y_disprove) lack explicit documentation. The ledger tool conflates three distinct actions (record/gaps/summary) into one tool, violating single-responsibility principle. Tools are well-composed overall, with good chaining potential (snapshot/diff workflow, audit/disprove loop), but the lack of visible output schema documentation and error handling prevents a higher score.

• Document the output schema for EVERY tool. For a11y_audit_url, document that it returns {score: number, findings: [{criterion: string, level: string, remediation: string}], ...}. For a11y_snapshot, document the structure of the accessibility tree. This enables LLMs to chain tools correctly and reduces discovery overhead.
• Split a11y_ledger into three separate tools: a11y_ledger_record (records an audit), a11y_ledger_gaps (shows new issues since baseline), a11y_ledger_summary (shows overall coverage). Each tool does one thing, names are clear, and LLMs can call them independently without guessing modes.
• Add explicit error handling guidance to tool descriptions. E.g., 'If Playwright is not installed, returns error with link to installation instructions. Retryable: false.' This guides LLM recovery strategies.
• Document parameter relationships explicitly. For a11y_disprove, clarify: 'If informe is omitted, performs a fresh audit then disproves findings against the live URL. If informe is provided, skips audit and disproves the existing report findings.'
• Add per-item success/failure details when tools process multiple items. If a11y_evidence aggregates multiple audit reports but some fail to load, return a response like {successful_reports: [...], failed_reports: [{path: string, error: string}], summary: ...}. This prevents silent data loss.
• Rename a11y_audit_url to a11y_audit_static and a11y_audit_dom to a11y_audit_rendered to make the distinction explicit. Or enhance descriptions with 'Use this for static HTML analysis (no JavaScript rendering, faster)' vs 'Use this for rendered analysis (requires Playwright, detects real contrast and focus).'