Docs/Skills/Readability Score Skill

Readability Score Skill

Calculate readability score

OperationalCredits 2 per callp50 569msText Processing

Overview

Readability Score first replaces every tab, carriage return and line feed in `text` with a space and trims it; empty text returns a 400 error. The formulas are for English: text with no words (only punctuation, digits or symbols) and text where most letters are outside the Latin script (Chinese, Japanese, Cyrillic and so on) also return a 400 rather than meaningless grades. Because line breaks become spaces, a heading or bullet without terminal punctuation runs into the next sentence, which raises the sentence-length based scores. Add periods to list items if you want them counted as separate sentences.

`textCounts.syllableCount`, `lexiconCount` (words) and `sentenceCount` come from the text-readability library, as do Gunning Fog, Coleman-Liau, the Automated Readability Index and the New Dale-Chall score. `smogIndex` is taken from the readability-scores library instead. Flesch Reading Ease (two decimals) and Flesch-Kincaid Grade (one decimal) are computed from those three counts using exact words-per-sentence and syllables-per-word ratios; textstat and text-readability round both ratios to one decimal first, so their figures can differ from ours by a few points. These are standard formulas over syllables per word, words per sentence, characters per word, polysyllabic word counts and, for Dale-Chall, the share of words outside a list of familiar words.

All grade-style metrics and the Dale-Chall score are floored at 1. `fleschReadingEase` is not floored: it runs roughly 0 to 100 with higher meaning easier, and very dense text can go below 0. Its label in `readabilityText` uses lower bounds of 90 very easy, 80 easy, 70 fairly easy, 60 standard, 50 fairly difficult, 30 difficult, and very confusing below that. The Dale-Chall label maps whole-number bands from "average 4th-grade student or lower" up to "13th to 15th-grade (college) student" for 9 and above.

`averageGradeLevel` is the mean of Flesch-Kincaid, Gunning Fog, Coleman-Liau, SMOG and ARI, rounded to one decimal. `targetAudience` reads from it: 16 and above post-graduate, 13 college, 9 high school, 6 middle school, otherwise elementary. Short samples of a sentence or two produce unstable scores. Results are identical on every plan.

Live Test Readability Score Skill Skill →

The tool

Once your client is connected to the VerveKit server, this appears in its tool list as ReadabilityScoreSkill. It is read-only and open-world — it fetches and never mutates anything on your side — so most clients call it without asking you to confirm.

Tool call
{
  "name": "ReadabilityScoreSkill",
  "arguments": {
    "text": "The quick brown fox jumps over the lazy dog. This sentence contains every letter of the alphabet."
  }
}

You do not name the tool yourself; the model picks it. Asking about The quick brown fox jumps over the lazy dog. This sentence contains every letter of the alphabet. in the terms this skill covers is enough for it to reach for ReadabilityScoreSkill on its own — naming it explicitly also works, and is the way to force the call.

Connecting

One server URL covers every skill in the catalog, including this one. Authorization is OAuth: the client opens a browser once, and there is no key to paste into a config file.

{
  "mcpServers": {
    "vervekit": {
      "url": "https://api.vervekit.com/v1/mcp"
    }
  }
}

Per-client setup — Claude, Cursor, VS Code, ChatGPT — is on the MCP setup page.

Arguments

These are the properties on the tool's inputSchema, so a well-behaved client validates them before the call is made. Premium arguments are accepted on every plan but only take effect on plans that include them.

ArgumentTypeDescription
textRequiredstringThe text to calculate the readability score of

What the model gets back

The result carries a structuredContent object matching the tool's declared outputSchema, so a client reads fields without parsing prose. status is "ok" and error is null on success; a null field means the value was not available for that input, not that the call failed.

Result
{
  "status": "ok",
  "error": null,
  "data": {
    "textCounts": {
      "syllableCount": 82,
      "lexiconCount": 49,
      "sentenceCount": 1
    },
    "readability": {
      "fleschReadingEase": 15.52,
      "fleschKincaidGrade": 23.3,
      "gunningFog": 26.95,
      "colemanLiauIndex": 13.19,
      "smogIndex": 22.08,
      "automatedReadabilityIndex": 27.8,
      "daleChallReadabilityScore": 17
    },
    "readabilityText": {
      "fleschReadingEase": "very confusing",
      "daleChallReadabilityScore": "average 13th to 15th-grade (college) student"
    },
    "averageGradeLevel": 22.7,
    "targetAudience": "post-graduate"
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

FieldTypeExampleDescription
textCountsobject{…}Counts of syllables, words, and sentences found in the analyzed text
textCounts.syllableCountnumber82Total number of syllables detected in the text
textCounts.lexiconCountnumber49Total number of words in the text
textCounts.sentenceCountnumber1Total number of sentences detected in the text
readabilityobject{…}Raw numeric scores from each readability formula
readability.fleschReadingEasenumber15.52Flesch Reading Ease score on a 0-100 scale; higher scores mean the text is easier to read
readability.fleschKincaidGradenumber23.3Flesch-Kincaid Grade Level; the approximate U.S. school grade a reader needs to understand the text
readability.gunningFognumber26.95Gunning Fog index; the estimated years of formal education a reader needs to understand the text on a first reading
readability.colemanLiauIndexnumber13.19Coleman-Liau Index; an estimated U.S. grade level based on characters per word and words per sentence
readability.smogIndexnumber22.08SMOG Index; the estimated years of education needed to understand the text, based on its count of polysyllabic words
readability.automatedReadabilityIndexnumber27.8Automated Readability Index; an estimated U.S. grade level based on characters per word and words per sentence
readability.daleChallReadabilityScorenumber17New Dale-Chall score; a readability rating based on how many words in the text are outside a list of words familiar to average 4th-grade readers
readabilityTextobject{…}Plain-language interpretations of the numeric readability scores
readabilityText.fleschReadingEasestringvery confusingPlain-language difficulty label derived from the Flesch Reading Ease score, e.g. "very easy" or "very confusing"
readabilityText.daleChallReadabilityScorestringaverage 13th to 15th-grade (college) studentPlain-language grade-level description derived from the Dale-Chall score, e.g. "average 4th-grade student or lower"
averageGradeLevelnumber22.7Average grade level computed by averaging the grade-based metrics (Flesch-Kincaid, Gunning Fog, Coleman-Liau, SMOG, and Automated Readability Index)
targetAudiencestringpost-graduateSuggested target audience derived from the average grade level, e.g. "elementary", "high school", or "post-graduate"

Failure modes

Errors come back as tool errors carrying a sentence the model can act on, not a bare status code. Error handling covers the full list.

StatusWhat it means
400 / 422The arguments did not validate. The message names the offending one.
401The OAuth session is invalid or expired — reconnect the server.
403Blocked by a key restriction or an IP allow-list. Never a bad identity.
404This skill is not part of VerveKit. Check the catalog.
429Out of credits, or a brief rate limit. The message tells them apart.

A call costs 2 credits each time the tool actually runs; a model that reasons about the tool without calling it costs nothing.

Use cases

Editorial CMS Publishing
Before publishing articles, newsroom CMS editors check the Flesch-Kincaid grade level and word counts to match target reader expectations.
Patient Instructions Review
When clinicians draft care summaries, health portals flag passages scoring above an elementary target audience so staff can rephrase dense medical terms.
Curriculum Reading Assessment
To assign books to suitable grade bands, edtech apps evaluate uploaded chapters against Dale-Chall scores and the average grade level.
Consumer Contract Auditing
Flag convoluted policy clauses during drafting by checking consumer agreements against the Gunning Fog index and reading ease ratings.

Other ways to use Readability Score Skill

Set up Readability Score Skill on VerveKit, or reach the same source a different way. Your VerveKit account and credits work on all of them — one key, one balance.

Call it as a REST APIOne HTTPS endpoint and an x-api-key header, with SDKs for Node, Python and .NET.APIVerve →Reference →
Google Sheets or ExcelA =VERVE() formula fills a column — no script, no export, recalculates in place.VerveSheets →Reference →

More in Text Processing:

Was this page helpful?