Skip to content

AI Doc Readability Scorer

Score Markdown docs on structure, code examples, API discoverability, schema coverage, LLM parseability and readability, with fixes ranked by impact.

AI Doc Readability Scorer

63
Overall scoreFair

Overall score 63 out of 100, Fair

Improvement priorities

1
Code Examples+3 overall

Include complete, runnable examples with imports and context, not just snippets.

2
API Discoverability+3 overall

List API endpoints or functions with their HTTP methods and paths.

3
API Discoverability+3 overall

Document parameters with name, type, description, and whether they are required.

4
API Discoverability+3 overall

Document response formats with status codes and example response bodies.

5
Schema Coverage+3 overall

Define request and response schemas using JSON Schema, TypeScript interfaces, or structured tables.

6
Structure+2 overall

Use bullet or numbered lists when enumerating items, steps, or options.

7
Structure+2 overall

Add a "Conclusion", "Summary", or "Next Steps" section at the end.

8
Code Examples+2 overall

Include at least 3 code examples covering different use cases or scenarios.

9
API Discoverability+2 overall

Add a dedicated Authentication section explaining API keys, tokens, or OAuth flows.

10
API Discoverability+2 overall

Document error codes, their meanings, and how to handle common errors.

Updated . Provided as is. Check the output before you rely on it in production.

How to use AI Doc Readability Scorer

  1. 1

    Paste your documentation

    Enter your README, API documentation, or tutorial content. Select the document type for format-specific scoring criteria.

  2. 2

    Review dimension scores

    See scores across 6 dimensions: structure, code examples, API discoverability, schema coverage, LLM parseability, and human readability — each with a progress bar.

  3. 3

    Read specific findings

    Expand each dimension to see specific findings and suggestions — missing code examples, poor heading hierarchy, ambiguous language that confuses AI agents.

  4. 4

    Follow the improvement priority list

    The priority list sorts suggestions by impact, so you can address the most impactful improvements first for both human readers and AI agents.

Questions and answers

What is AI Doc Readability Scorer?
Doc readability here means how readily both a person and an AI assistant can find, follow and quote your documentation. This scorer runs concrete checks on a README, API reference, tutorial or guide in six dimensions, from structure and code examples to LLM parseability, and ranks the fixes by impact.
Why does LLM parseability matter?
Developers increasingly read documentation through AI assistants, which retrieve and summarize it for them. Documentation with clear headings, complete code examples and explicit parameter descriptions is quoted more accurately.
Does it send my documentation to a server?
No. All scoring happens entirely in your browser.
What document types does it support?
README files, API documentation, tutorials, and general guides. Select the document type for format-specific scoring criteria and recommendations.
For AI agents: how to call this tool

Machine-readable contract, endpoints and examples. Humans can ignore this section.

Best Path For Builders

Browser workflow

Runs instantly in the browser with private local processing and copy/export-ready output.

Browser Workflow

This tool is optimized for instant in-browser execution with local data handling. Run it here and copy/export the output directly.

/ai-doc-readability-scorer/

For automation planning, fetch the canonical contract at /api/tool/ai-doc-readability-scorer.json.