Clarify coarse tool invocation and repair malformed database filters

docs/tool-guidance-repair-v1.md

@@ -0,0 +1,55 @@
+# Explizite Werkzeugverträge und Filterkorrektur
+
+Der Live-Test `bug20-analysis-tools-20261018` wurde in der ersten H2-Runde
+blockiert. Nach einem leeren Filterarray lieferte das Modell zweimal eine flache
+Liste statt eines Filterobjekts. Die Anfragen wurden nicht ausgeführt. Die neuen
+größeren Werkzeuge waren im Katalog enthalten, ihre konkreten Aufrufformen aber
+nicht im festen Instruktionstext der Anfangsrunden erklärt.
+
+## Korrekturhinweise
+
+Neue technische Fehler unter `/next/arguments/filters` erhalten einen konstanten,
+wertfreien Hinweis mit der korrekten Form:
+
+```json
+[{"column":"observed_column","operator":"eq","value":123}]
+```
+
+Spalte und Wert sind illustrative Platzhalter und müssen aus belegten Daten
+gewählt werden. Der Hinweis verlangt ausdrücklich eine nichtleere Liste von
+Objekten statt einer flachen Liste. Er enthält keine Daten aus der abgelehnten
+Antwort und bleibt innerhalb der bestehenden 160-Zeichen-Grenze. Das gilt für
+volle Anfangsrunden, die schlanke Schleife und deren bisherigen v19-Pfad.
+
+Es gibt keine automatische Reparatur oder Ausführung einer ungültigen Anfrage.
+Die nächste Modellantwort wird erneut vollständig validiert. Bestehende
+gespeicherte Korrekturhinweise werden beim Promptaufbau nicht rückwirkend ersetzt.
+
+## Werkzeuganweisung
+
+Neue Kontexte mit mindestens einem der größeren Werkzeuge erhalten den Marker
+`tool_guidance_version = 1`. Nur diese Kontexte ergänzen die Systeminstruktionen
+um die konkreten Formen von `database.relations` und/oder `source.context`,
+entsprechend dem jeweils verfügbaren Katalog. Dazu kommen die nichtleere
+Filterstruktur und der Hinweis, Ausgabe-JSON nicht wie komprimierte Eingabedaten
+zu kodieren. Passende größere Werkzeuge werden empfohlen, Grundwerkzeuge bleiben
+verfügbar.
+
+Die Anweisung steht in vollständigen Anfangsrunden und schlanken Rechercheschritten
+einmal im Systemtext. In Konsolidierung und vorbereitender Abschlussbewertung
+wird sie nicht angefügt. Sie kann mit den bestehenden stabilen Instruktionen
+gecacht werden; zusätzliche LLM-Aufrufe entstehen nicht.
+
+Kontexte ohne Marker behalten ihre bisherigen Nachrichten und Schemas. Die vier
+gespeicherten Untersuchungsaufrufe des blockierten Tests wurden offline exakt
+rekonstruiert. Ein erneuter Aufruf desselben alten, blockierten Arbeitsstands
+bekommt dadurch nicht automatisch einen neuen Promptvertrag. Für die Erprobung
+der ergänzten Werkzeuganweisung ist ein frischer Kontext erforderlich.
+
+## Validierung
+
+Lokale Tests reproduzieren beide fehlerhaften Filterformen in vollen und schlanken
+Antworten, prüfen die Annahme korrekter Filterobjekte, die persistierte Korrektur
+und eine danach erfolgreiche Werkzeugaktion. Weitere Prüfungen betreffen die
+Anweisung in beiden Promptarten, historische Verträge, beide größeren Werkzeuge,
+Paket-Wiederaufnahme und Caching. Es wurden keine bezahlten API-Aufrufe ausgeführt.