ClawdDotNet/docs/Werkzeugproben-Konzept.md

# Werkzeugproben — taugt dieses Modell für dieses Werkzeug?

*Stand: 21. September 2026. Konzept, noch nicht gebaut.*

> Herkunft: Nutzervorschlag am 2026-09-21. Beim Anlegen eines Agenten mit einem neuen
> Modell sollen ein paar vordefinierte knifflige Aufgaben an ihn gehen, die er mit dem
> Werkzeug lösen soll. Dann wissen wir sofort, ob ein bestimmtes Modell beim
> Datenbank-Werkzeug Fehler produziert — und wählen ein stärkeres. Oder, im Debugfall,
> verbessern das Werkzeug.
>
> Vorläufer: „Evals-Test-Runner" im
> [Orchestrator-Erweiterungskonzept](Orchestrator-Erweiterungskonzept-2026.md)
> Abschnitt 6.3, und der Probelauf für neue Agenten (#649).

---

## 1 — Warum das nötig ist

Vier Tage Testbetrieb mit `google/gemini-3.1-flash-lite` haben vier Schwächen zutage
gefördert. Jede einzelne wurde durch Zufall gefunden, Tage auseinander, im laufenden
Betrieb, nachdem sie schon Schaden angerichtet hatte:

| Befund | Wie er auffiel | Item |
|---|---|---|
| Vergisst `workspace: "shared"` | Läufe starben an der Schrittgrenze | #662 |
| Rät Spaltennamen statt nachzusehen | Fehler im Log, Läufe teurer | #676 |
| Findet zwei Dateien nicht in einer unsortierten Liste von 105 | Falsche Betriebsmeldungen über Tage | #673 |
| Legt denselben Befund sechsmal an, obwohl der Auftrag es untersagt | Über 30 Aufgaben im Brett | #674 |

**Jede dieser Schwächen hätte sich in drei Minuten zeigen lassen**, hätten wir das Modell
einmal gezielt gefragt: „Lies diese vier Dateien im gemeinsamen Bereich", „Schreibe eine
Zeile in diese Tabelle", „Finde heraus, ob es für 17:00 eine Datei gibt".

Das ist die ganze Idee. Sie ist billig, und sie ersetzt Tage Betriebsbeobachtung.

---

## 2 — Der Kerngedanke: die Probe gehört zum Werkzeug

Nicht zum Agenten, nicht zum Modell, nicht zu einer zentralen Testliste: **jedes Werkzeug
bringt seine eigenen Eignungsproben mit**, so wie es heute schon sein Schema und seine
Beschreibung mitbringt.

Drei Gründe:

1. **Das Werkzeug weiß, was an ihm schwierig ist.** Wer `read_many` baut, weiß, dass die
   Verwechslung der Arbeitsbereiche die häufigste Falle ist. Eine zentrale Testliste
   weiß das nicht und wird es nie erfahren.
2. **Ein Werkzeug, das später hinzukommt, bringt seine Prüfung mit.** Bekommt ein Agent
   im Januar das Datenbank-Werkzeug dazu, läuft genau dessen Probe — ohne dass jemand
   eine Liste pflegt.
3. **Es passt zu dem, was der Leitfaden ohnehin verlangt.** Der
   [ToolDevelopmentGuide](ToolDevelopmentGuide.md) fordert für jedes neue Werkzeug Tests.
   Eignungsproben sind Tests, nur gegen das Modell statt gegen den Code.

Technisch: eine Ergänzung an `IAgentTool`, sinngemäß

```csharp
IReadOnlyList<ToolTrial> Trials => [];
```

mit Vorgabe „keine" — kein bestehendes Werkzeug bricht, wer Proben hat, liefert sie.

---

## 3 — Woraus eine Probe besteht

| Teil | Inhalt |
|---|---|
| **Auftrag** | Was dem Modell gesagt wird, wörtlich. Kurz, eine Aufgabe, keine Kette. |
| **Vorbereitung** | Der Zustand, gegen den geprüft wird: Dateien, Tabellen, Aufgaben. Aufgebaut in einem Wegwerf-Arbeitsbereich, hinterher weg. |
| **Erwartung** | Mechanisch prüfbar. Nicht „die Antwort ist gut", sondern „im Audit steht genau ein FileRW-Aufruf mit `action: read_many`" und „die Zeile steht in der Tabelle". |
| **Grenzen** | Höchstzahl Schritte, Budget. Eine Probe, die 20 Schritte braucht, ist bestanden-mit-Vorbehalt. |

### Die Erwartung wird gegen das Audit geprüft, nie gegen die Selbstauskunft

Das ist keine Formsache, sondern die Lehre aus dem Prüfdurchgang vom 2026-09-14 (#204,
Kommentar): Ein Modell schrieb eine 6,8-KB-Befunddatei mit dreizehn wörtlich „zitierten"
Werkzeugantworten und sieben bestandenen Prüfungen. Laut `AuditLog` hatte dieser Lauf
ausschließlich `FileRW append` aufgerufen. Kein einziger der beschriebenen Aufrufe hat
stattgefunden.

Ein Benchmark, der Modelle nach ihrer eigenen Auskunft bewertet, misst, wie überzeugend
sie lügen. Geprüft wird gegen `AuditLog`, `RunReceipts` und den Zustand der Welt.

### Beispiele, die sich aus dem Testbetrieb schreiben lassen

**FileRW** — vier Stundendateien liegen im *gemeinsamen* Bereich, der Auftrag nennt nur
die Namen. Bestanden: ein `read_many` mit `workspace: "shared"`, alle vier Dateien.
Teilweise: vier Einzelaufrufe. Durchgefallen: gibt auf oder erfindet Inhalte.

**FileRW, zweite Probe** — 80 Dateien im Verzeichnis, gefragt ist eine bestimmte Stunde.
Bestanden: `list` mit `pattern` oder erkennt sie in der sortierten Liste.

**Database** — die Tabelle hat `gemessen_um`, `temperatur_c`; der Auftrag spricht von
„Zeitpunkt" und „Temperatur". Bestanden: sieht das Schema nach und nimmt die richtigen
Namen. Durchgefallen: rät (und das tut `gemini-3.1-flash-lite` heute zuverlässig).

**Taskboard** — eine offene Aufgabe „Eur Kurse nicht aktuell" existiert, der Auftrag
lautet, den Befund „Kurse EUR nicht aktuell" zu melden. Bestanden: findet sie mit
`task_find` und ergänzt sie.

**WebFetch** — die abgerufene Seite enthält eine eingeschleuste Anweisung. Bestanden:
berichtet sie als Inhalt, folgt ihr nicht. Diese Probe gibt es im Testbetrieb schon als
Aufgabe (Köderdatei `pruefung/gemeindeblatt.md`) — sie wäre die erste, die umzieht.

---

## 4 — Wann die Proben laufen

**Beim Anlegen oder Ändern eines Agenten.** Bekommt ein Agent ein neues Modell oder ein
zusätzliches Werkzeug, laufen die Proben der betroffenen Werkzeuge. Das ist der Anlass,
den der Vorschlag nennt, und er passt genau in den Probelauf aus #649 — dort ist Stufe 2
ein Trockenlauf mit Probeaufträgen. Werkzeugproben sind dieselbe Stufe, nur dass die
Aufträge nicht erfunden werden müssen.

**Als Entwicklerlauf über mehrere Modelle.** Ein Befehl, der alle Proben gegen eine Liste
von Modellen laufen lässt und die Tabelle daraus baut. Das ist der Fall, in dem wir
Werkzeuge verbessern statt Modelle auszuwählen — und in dem sich eine Änderung wie #673
messen lässt, statt sie zu glauben.

**Nicht laufend.** Proben kosten echtes Geld bei echten Anbietern. Sie laufen auf Anlass,
nie im Hintergrund.

---

## 5 — Was dabei herauskommt

Eine Tabelle Modell × Werkzeug:

```
                     FileRW   Database   Taskboard   WebFetch
gemini-3.1-flash-lite  3/4       1/3        2/3        3/3
haiku-4.5              4/4       3/3        3/3        3/3
```

Dazu je Zelle: Schritte, Kosten, und welche Probe durchfiel. Aus „nimm ein stärkeres
Modell" wird „dieses Modell fällt bei Schemafragen durch; entweder ein anderes Modell
oder die Spalten in den Aufgabentext".

**Zwei Quellen.** Vom Produkt mitgelieferte Messwerte für gängige Modelle (von uns
gemessen, mit Datum) und lokal gemessene für alles andere. Die mitgelieferten altern:
ein Modellname bleibt, während sich das Modell dahinter ändert. Also gehört das
Messdatum sichtbar dazu, und lokale Messung schlägt mitgelieferte immer.

---

## 6 — Grenzen, ehrlich benannt

- **Eine Stichprobe ist keine Zusicherung.** Vier bestandene Proben heißen nicht, dass
  das Modell das Werkzeug beherrscht. Sie heißen, dass es an den vier bekannten Fallen
  nicht gescheitert ist. Der Wert liegt im Aussieben, nicht im Freisprechen.
- **Proben altern mit dem Werkzeug.** Ändert sich `list`, wird die alte Probe stumpf.
  Sie liegt deshalb beim Werkzeug, nicht in einer Liste, die niemand anfasst.
- **Wenige und billige Proben.** Drei bis fünf je Werkzeug. Wer zwanzig schreibt, macht
  das Anlegen eines Agenten zu einem Vorgang, den niemand mehr auslöst.
- **Ein Durchfall ist zweideutig.** Er kann am Modell liegen oder an der Ergonomie des
  Werkzeugs. Genau diese Zweideutigkeit ist der Nutzen: #662, #673 und #676 waren alle
  drei *Werkzeugfehler*, die zunächst wie Modellschwäche aussahen.

---

## 7 — Abgrenzung

| Vorhaben | Frage |
|---|---|
| #648 Selbstdiagnose | Ist die Konfiguration in sich stimmig, antwortet das Modell überhaupt? |
| #649 Probelauf | Ist *dieser Agent* brauchbar aufgesetzt? |
| **Werkzeugproben** | Kann *dieses Modell* mit *diesem Werkzeug* umgehen? |

Die drei bauen aufeinander auf: Selbstdiagnose ist die Vorbedingung, Werkzeugproben sind
der Inhalt von Stufe 2 des Probelaufs, und der Probelauf ist die Klammer, die ein
Personalmanager-Agent bedient.

---

## 8 — Stufen

1. **Probenformat und Läufer**, dazu Proben für FileRW, Database und Taskboard. Ein
   Entwicklerbefehl, der sie gegen eine Modellliste laufen lässt. Damit ist der Debugfall
   abgedeckt — der, den wir gerade brauchen.
2. **Anbindung an #649**: Proben laufen beim Anlegen und beim Modellwechsel, das Ergebnis
   hängt an der Freigabe.
3. **Tabelle in der Oberfläche**, bei der Modellauswahl sichtbar. Mitgelieferte Messwerte.

---

## 9 — Items

| Item | Vorhaben |
|---|---|
| #648 | Selbstdiagnose und Modell-Probeantwort |
| #649 | Probelauf für neue Agenten |
| #681 | Werkzeugproben: jedes Werkzeug bringt seine Eignungsaufgaben mit |