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.
{
"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"
}
}
}https://api.vervekit.com/v1/mcpPer-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.
| Argument | Type | Description |
|---|---|---|
textRequired | string | The 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.
{
"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.
| Field | Type | Example | Description |
|---|---|---|---|
textCounts | object | {…} | Counts of syllables, words, and sentences found in the analyzed text |
textCounts.syllableCount | number | 82 | Total number of syllables detected in the text |
textCounts.lexiconCount | number | 49 | Total number of words in the text |
textCounts.sentenceCount | number | 1 | Total number of sentences detected in the text |
readability | object | {…} | Raw numeric scores from each readability formula |
readability.fleschReadingEase | number | 15.52 | Flesch Reading Ease score on a 0-100 scale; higher scores mean the text is easier to read |
readability.fleschKincaidGrade | number | 23.3 | Flesch-Kincaid Grade Level; the approximate U.S. school grade a reader needs to understand the text |
readability.gunningFog | number | 26.95 | Gunning Fog index; the estimated years of formal education a reader needs to understand the text on a first reading |
readability.colemanLiauIndex | number | 13.19 | Coleman-Liau Index; an estimated U.S. grade level based on characters per word and words per sentence |
readability.smogIndex | number | 22.08 | SMOG Index; the estimated years of education needed to understand the text, based on its count of polysyllabic words |
readability.automatedReadabilityIndex | number | 27.8 | Automated Readability Index; an estimated U.S. grade level based on characters per word and words per sentence |
readability.daleChallReadabilityScore | number | 17 | New 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 |
readabilityText | object | {…} | Plain-language interpretations of the numeric readability scores |
readabilityText.fleschReadingEase | string | very confusing | Plain-language difficulty label derived from the Flesch Reading Ease score, e.g. "very easy" or "very confusing" |
readabilityText.daleChallReadabilityScore | string | average 13th to 15th-grade (college) student | Plain-language grade-level description derived from the Dale-Chall score, e.g. "average 4th-grade student or lower" |
averageGradeLevel | number | 22.7 | Average grade level computed by averaging the grade-based metrics (Flesch-Kincaid, Gunning Fog, Coleman-Liau, SMOG, and Automated Readability Index) |
targetAudience | string | post-graduate | Suggested 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.
| Status | What it means |
|---|---|
400 / 422 | The arguments did not validate. The message names the offending one. |
401 | The OAuth session is invalid or expired — reconnect the server. |
403 | Blocked by a key restriction or an IP allow-list. Never a bad identity. |
404 | This skill is not part of VerveKit. Check the catalog. |
429 | Out 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.
Related
More in Text Processing: