readability-analysis

Readability & Technical Editorial Analysis

This skill provides multi-dimensional analysis of text complexity and house-style linting, converting raw statistical metrics into actionable editorial guidance. It is backed by the docstats multi-protocol engine.

Design Role: docstats is designed as a post-hoc acceptance gate (for CI/CD pipelines, PR reviews, and pre-publish QA) rather than an in-loop generative dial. Empirical evaluations show that injecting live numeric metrics during generation does not improve prose quality over clear textual guidance and risks artificial metric gaming.

Available MCP Tools (Server readability-docstats)

1. analyze_document (Preferred)

Performs comprehensive two-axis assessment:

• Axis A (Readability): 10 grade-level and reading ease formulas + consensus standard.
• Axis B (House-Style Linting): Deterministic counts and rates of throat-clearing openers, binary contrast frames, non-technical filler adverbs, prose em dashes, and rhythm variation hints. Computes ai_tell_score (0.0–10.0 scale, floor ≥ 7.0).

2. get_readability_scores

Calculates Axis A readability scores and raw text statistics (syllables, words, sentences).

3. get_ai_pattern_scores

Calculates Axis B house-style lint counts, rates, diagnostic flags, and ai_tell_score.

---

How to Run It

Recommended Workflow: Post-Hoc Acceptance Gate

Use docstats asynchronously after drafting or during automated review:

1. Generate or edit the draft using qualitative editorial guidelines.
2. Run analyze_document as a quality gate.
3. If Axis B or Axis A fails, apply targeted edits to resolve diagnostic flags.

MCP Invocation

Pass exactly one source parameter:

• text: Plain text or markdown string.
• web_url: Publicly reachable HTML page or online PDF URL.
• gcs_pdf_uri: gs://... URI in Google Cloud Storage.

// Example MCP Tool Call
{
  "name": "analyze_document",
  "arguments": {
    "text": "Your draft content here..."
  }
}