> ## 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.

export const EarlyAccessCallout = ({children}) => <div className="eyebrow-callout not-prose rounded-xl border border-gray-200/80 p-5 dark:border-white/10" style={{
  marginBottom: "1rem",
  borderRadius: "4px"
}}>
    <div className="mb-3">
      <Badge color="green" size="md" icon="flask">
        Early access
      </Badge>
    </div>
    <div className="callout-body text-[15px] leading-relaxed text-gray-700 dark:text-gray-300">{children}</div>
    <style>{`.callout-body a { text-decoration: underline; text-decoration-color: #178251; }`}</style>
  </div>;

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

<EarlyAccessCallout>
  This functionality is actively evolving. Changes may occur as we expand
  capabilities and improve accuracy and reliability. Email
  [support@learningcommons.org](mailto:support@learningcommons.org) ↗ with your
  feedback or issues.
</EarlyAccessCallout>

## 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 (<Tooltip tip="General academic words that appear across subject areas, more common in writing than speech (e.g., vary, factors, determine). Students may encounter them but are unlikely to have fully mastered them at lower grade levels.">Tier 2</Tooltip>, <Tooltip tip="Domain-specific or subject-matter words that are rare outside a particular field (e.g., precipitation, latitude, equator). Students are unlikely to know these without prior instruction in that subject.">Tier 3</Tooltip>, <Tooltip tip="Words that are outdated or no longer in common use in contemporary writing, which may be unfamiliar to students regardless of grade level.">archaic</Tooltip>, etc.)
* Evaluates overall vocabulary complexity relative to the background knowledge estimate

## At a glance

|                      |                                                                                                                                                                                                             |
| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Input type**       | Informational text                                                                                                                                                                                          |
| **Supported grades** | 3–12                                                                                                                                                                                                        |
| **Rubric**           | [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#interpreting-accuracy).

## Evaluator release history

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