> The full index of these docs is at [llms.txt](https://u22a8.ai/llms.txt).

# Teaching

How to teach and retract through MCP, when a teach lands in your organization’s model and what it changes.

A **teach** is a request plus the answer it should get. Your organization’s model learns from it in the background and keeps answering while it does.

You teach from inside a conversation. Tell your assistant what A8 got wrong, and it calls the `teach` tool on A8’s [MCP server](https://u22a8.ai/docs/a8-mcp.md). Approving that call records the teach.

## 1 What a teach is

The request is the one you send to judge, and the answer is the verdict it should get:

| Part     | Holds                                                                      | Required |
| -------- | -------------------------------------------------------------------------- | -------- |
| `input`  | The criterion and the subject: a string, or the messages of a conversation | Yes      |
| `format` | The verdict’s shape, as JSON Schema                                        | Optional |
| `answer` | The verdict the request should get, in that shape                          | Optional |

*Table 1.* The three parts of a teach. A teach with an `answer` records it; a teach with only an `input` returns a proposal.

A correction is a teach of a request you already sent, with the answer you wanted. Your assistant sends the same `input` and `format` it judged, and the answer you named:

```json
{
  "input": [
    {"role": "system", "content": "Which queue does the ticket belong in?"},
    {"role": "user", "content": "It arrived crushed. I want a refund."}
  ],
  "format": {
    "properties": {"queue": {"enum": ["billing", "shipping", "account"]}}
  },
  "answer": {"queue": "billing"}
}
```

The result says when the teach was recorded and whether it replaced an earlier answer:

```json
{"recorded_at": "2026-10-22T14:03:11Z", "replaced": false}
```

Teaching needs the `models:train` permission. See [API keys](https://u22a8.ai/docs/api-keys.md).

### 1.1 Two ways to teach

- **Name the answer.** A8 records it when you approve the call.
- **Say what you want learned, in your own words.** For example, “double-charge tickets go to billing, even when the order came late”. A8 proposes the request and the answer it would record. A8 records it when you agree and your assistant teaches the proposal.

### 1.2 One criterion per teach

A teach covers one criterion. When a schema’s properties carry criteria of their own, teach each criterion in a request of its own. See [Check one subject against several criteria](https://u22a8.ai/docs/check-one-subject-against-several-criteria.md).

## 2 The same request, a new answer

A request is the same when its `input` and `format` match exactly as JSON: the same strings and values, whatever the key order. Teaching it again with a different answer replaces the old answer, and the result says `replaced: true`.

A follow-up is taught with the whole conversation as its `input`, A8’s earlier responses included. The `answer` is the verdict the latest user message should get.

A request phrased differently is a separate example, and both count. Each request replaces its own answer alone.

## 3 When a teach lands

A teach is recorded the moment you approve it. A fit follows once your organization has been quiet for about a minute, so a hundred teaches in a row become one fit. Until the fit completes, `a8` answers from the version it already serves.

Each fit produces a version named by a [horizon](https://u22a8.ai/docs/a8-horizons.md), a timestamp. A version whose horizon is at or after a teach’s `recorded_at` includes that teach. Every response names the version that answered in `model`, so any verdict tells you whether your latest teaching is in it.

## 4 Retracting

`retract` removes an example taught by mistake, such as a throwaway fixture or a wrong paste. It takes the request alone, its `input` and `format`, and the next version is fitted from the examples that remain. The result says whether the request had a taught answer to remove:

```json
{"retracted": true}
```

To correct an answer, teach the same request with the right one. Retract an example that should leave the model.

> **Pinned versions keep the example.** Versions fitted before a retraction keep the example, so a [pinned version](https://u22a8.ai/docs/a8-horizons.md) answers as it did and still cites it. That is what pinning is for.

## 5 Finding what you taught

Ask A8. “What have I taught you about refunds?” returns the taught examples most relevant to the question, word for word, ready to retract or teach again. This is **recall**, and it needs the `models:explain` permission. Recall lists the examples in the version that answers: a teach appears once its fit lands, and a retracted example leaves with the next fit. See [Precedents](https://u22a8.ai/docs/a8-precedents.md).

## 6 Checking that it took

Test the model the way you would test a student: ask it new questions with answers you know, and compare. See [Testing A8](https://u22a8.ai/docs/a8-testing.md).

## 7 Scope

Teaching is scoped to your organization. Your examples stay in it and train its model alone. They shadow the reference model for the criteria you teach, and the reference model answers the rest.

When you teach a criterion the reference model already covers, your examples take its place in your model. That criterion then earns its [accuracy levels](https://u22a8.ai/docs/a8-abstention.md) on your examples, so a criterion taught with a handful of examples can promise less than the reference model did. The promise follows the evidence.

The reference model stays as published, and you can call it directly as `a8-1-1@reference`. Run the same test against both to measure what your teaching changed.

> **Teaching moves your model.** Every fit mints a new horizon, and the `system_fingerprint` on your responses changes with it. Re-check any baseline of expected verdicts when it moves. See [Reproducibility](https://u22a8.ai/docs/a8-reproducibility.md).

## 8 Edge cases

| Case                                               | Behaviour                                                       |
| -------------------------------------------------- | --------------------------------------------------------------- |
| The same request taught again with the same answer | The result says `replaced: false`, and the model stays as it is |
| A schema whose properties carry their own criteria | `teach` returns an error naming those properties                |
| A retract of a request you have yet to teach       | The result says `retracted: false`                              |
| A teach while a fit is running                     | The teach is recorded and lands in the fit after it             |
| A key holding `models:infer` alone                 | `teach` and `retract` return a permission error                 |

*Table 2.* How teaching behaves at its edges.

## 9 Related concepts

- [Horizons](https://u22a8.ai/docs/a8-horizons.md): the versions a fit produces, and pinning
- [Precedents](https://u22a8.ai/docs/a8-precedents.md): the taught examples behind a verdict, and recall
- [Accuracy and abstention](https://u22a8.ai/docs/a8-abstention.md): the levels a criterion earns from its examples
- [MCP](https://u22a8.ai/docs/a8-mcp.md): the `teach` and `retract` tools and their schemas

## Next steps

- [Testing A8](https://u22a8.ai/docs/a8-testing.md): Test what A8 learned the way you would test a student, with new questions, known answers, accuracy and coverage, on a pinned version.
- [Precedents](https://u22a8.ai/docs/a8-precedents.md): Precedents are the taught examples behind a verdict: how to ask for them, what each citation carries, recall and the permission they need.
- [A8 over MCP](https://u22a8.ai/docs/a8-mcp.md): Connect an MCP host to A8, and judge, teach and retract from inside a conversation with three tools.