> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learningcommons.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Vocabulary

> Reference documentation for the Vocabulary literacy evaluator.

[Evaluator last updated September 23, 2025.](#evaluator-release-history)

<EarlyAccess isBreaking={false} />

## Overview

The Vocabulary evaluator gives developers fine-grained vocabulary insights that help ensure texts use words that align with grade-level expectations and support growth in academic language:

* Estimates the background knowledge that a student at the target grade level is likely to have
* Identifies complex words in the text ([Tier 2](/evaluators/understanding-evaluators/core-concepts#tier-2), [Tier 3](/evaluators/understanding-evaluators/core-concepts#tier-3), [archaic](/evaluators/understanding-evaluators/core-concepts#archaic), etc.)
* Evaluates overall vocabulary complexity relative to the background knowledge estimate

## At a glance

|                      |                                                                                                                                                                                                                                            |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Input type**       | Informational text                                                                                                                                                                                                                         |
| **Supported grades** | 3–12                                                                                                                                                                                                                                       |
| **Rubric**           | [Student Achievement Partners (SAP)](https://learnwithsap.org/) ↗'s [Qualitative Text Complexity Rubric for Informational Text](https://learnwithsap.b-cdn.net/app/uploads/2026/04/Qualitative-Text-Complexity-Rubric-Informational.pdf) ↗ |

The evaluator was built and validated using the model and temperature below (other configurations will produce different results and may have lower accuracy):

|                 |                                                                                     |
| :-------------- | :---------------------------------------------------------------------------------- |
| **Model used**  | GPT-4o (Step 1); Gemini-2.5-pro (Step 2, Grades 3–4); GPT-4.1 (Step 2, Grades 5–12) |
| **Temperature** | 0                                                                                   |

## Getting started

Follow the [Quickstart](/evaluators/getting-started/quickstart) to start using this evaluator:

| Access method             |                                                                                                                                                                                                                                                                                                                                                           |
| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Evaluators Playground** | [View in the Learning Commons Platform](https://platform.learningcommons.org/apps/evaluators/playground?utm_source=docs\&utm_medium=evaluators) ↗                                                                                                                                                                                                         |
| **SDK**                   | [Python](https://github.com/learning-commons-org/evaluators/blob/main/sdks/python/src/learning_commons_evaluators/evaluators/vocabulary.py?utm_source=docs\&utm_medium=evaluators) ↗ and [TypeScript](https://github.com/learning-commons-org/evaluators/blob/main/sdks/typescript/src/evaluators/vocabulary.ts?utm_source=docs\&utm_medium=evaluators) ↗ |
| **Python notebook**       | [View in GitHub](https://github.com/learning-commons-org/evaluators/blob/main/evals/vocabulary_evaluator.ipynb?utm_source=docs\&utm_medium=evaluators) ↗                                                                                                                                                                                                  |
| **Prompts**               | [View in GitHub](https://github.com/learning-commons-org/evaluators/tree/main/evals/prompts/vocabulary?utm_source=docs\&utm_medium=evaluators) ↗                                                                                                                                                                                                          |

## Inputs

| Input                  | Description                                           | Required |
| :--------------------- | :---------------------------------------------------- | :------- |
| **Target grade level** | Enables grade context evaluation                      | Yes      |
| **Text type**          | Informational text<br />Optimal length: 130-205 words | Yes      |

## Output

| Field                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Complex words**    | List of Tier 2, Tier 3, archaic, and other complex words in the text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **Complexity score** | <ul><li><strong>Slightly complex:</strong> Uses everyday, familiar vocabulary with few academic or domain-specific terms.<ul><li>Almost entirely contemporary and conversational</li><li>Very low proportion of complex words (archaic, subject-specific, academic)</li><li>Easy to understand and does not impede comprehension of the bulk of the text (1-2 quick pauses for processing by the student may occur)</li></ul></li><li><strong>Moderately complex:</strong> Includes a mix of familiar and academic vocabulary, with some Tier 2 or Tier 3 terms that may require support.<ul><li>Mostly contemporary and conversational</li><li>Low proportion of complex words (archaic, subject-specific, academic)</li><li>Generally allows students to comprehend the bulk of the text with little difficulty, though there may be occasional pauses for clarification (several quick pauses or occasional prolonged pauses may occur)</li></ul></li><li><strong>Very complex:</strong> Relies heavily on Tier 2 and Tier 3 vocabulary with limited contextual scaffolding.<ul><li>Often unfamiliar, archaic, subject-specific, and/or overly academic</li><li>Often presents challenges that may slow down comprehension, but does not completely block the comprehension of the bulk of the text</li></ul></li><li><strong>Exceedingly complex:</strong> Uses dense academic and domain-specific vocabulary that is likely to be inaccessible without significant support.<ul><li>Mostly unfamiliar, archaic, subject-specific, and/or overly academic</li><li>May be ambiguous or purposefully misleading.</li><li>Makes comprehension of the bulk of the text very challenging and requires careful effort to interpret</li></ul></li></ul> |
| **Reasoning**        | Explanation of the complexity rating in the context of the target grade level.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

## Accuracy and validation

<Note>
  This evaluator is provided as Early access. Comprehensive accuracy measures
  are not yet available. Validation testing is ongoing.
</Note>

We assessed performance against an expert-annotated dataset of 580+ texts from [CLEAR Corpus](https://www.commonlit.org/blog/introducing-the-clear-corpus-an-open-dataset-to-advance-research-28ff8cfea84a/) ↗. Accuracy has been most extensively validated on Grades 3–4.

### Grade 3-4 accuracy

| Metric                  | Description                                                                                                              | Result                                                 |
| :---------------------- | :----------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------- |
| **Expert agreement**    | The percentage of evaluated examples where at least one expert agreed with the evaluator's rating during review testing. | 52% against the validation dataset                     |
| **Baseline comparison** | How the evaluator's accuracy compares to a simple, unrefined prompt.                                                     | 33% more accurate (relative) than a naive LLM baseline |

For more information on our validation process, see [Accuracy](/evaluators/understanding-evaluators/core-concepts#accuracy).

## Evaluator release history

| Date               | Changed       |
| ------------------ | ------------- |
| September 23, 2025 | First release |