Den Tool-Kontext eines Agenten abstimmen

Diese Anleitung behandelt die praktische Arbeit an der zweistufigen Tool-Oberfläche: nachsehen, was ein Lauf schickt, das ändern und einen Agenten diagnostizieren, der zum falschen Tool gegriffen hat. Warum es so funktioniert, liest du unter Tool-Kontext und Prompt-Caching.

Nachsehen, was ein Lauf wirklich schickt

Öffne eine Unterhaltung und tippe auf die Anzeige Kontextnutzung in der Kopfzeile. Sie baut genau die Oberfläche nach, die der nächste Dispatch schicken würde, ohne etwas auszuführen. Mehr anzeigen (oder der Befehl /context) öffnet den vollständigen Kontext, in dem du jedes Tool prüfen kannst.

Zwei Segmente zählen hier:

• Tool-Definitionen und MCP & dynamische Tools — die residente Menge, mit den echten Tokenkosten jedes Tools.
• Bei Bedarf geladene Tools — der zurückgestellte Index. Jeder Eintrag kostet nur seinen Namen, denn die Anfrage trägt nur den Namen; öffnest du einen, siehst du trotzdem die volle Beschreibung und das Schema, also was er kosten würde, wenn der Lauf ihn nachzieht.

Ist das zurückgestellte Segment leer, ist die Zurückstellung auf diesem Server aus. Prüfe --tool-deferral in der cc_server CLI.

Festlegen, welche Tools von Anfang an geladen werden

Die residente Menge ist Richtlinie, keine Konfiguration — sie liegt in ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) und gilt für jeden Lauf:

• residentBuiltins — das Datei- und Shell-Vokabular.
• residentDiscovery — search_tools und list_my_tools. Die nimmst du nicht heraus; über sie erreicht ein Agent alles andere.
• residentMcpTools — die wenigen Tools von Control Center, deren Schema sich auf jeder Anfrage lohnt.
• Ein Block je Modus, für die Tools, die ein bestimmter Modus in fast jedem Turn braucht.

Zwei Regeln, wenn du sie bearbeitest:

Nimm ein Tool nur auf, wenn die meisten Läufe es benutzen. Jeder Name kostet sein Schema bei jeder Anfrage jedes Laufs, und das dauerhaft. Ein Tool, das wichtig ist, sobald es gebraucht wird, insgesamt aber selten vorkommt, gehört in die zurückgestellte Hälfte — der Agent findet es trotzdem.

Nimm den echten Namen des Tools. Ein residenter Name, der auf kein Tool passt, bleibt wirkungslos: kein Fehler, keine Warnung, das Tool wird einfach zurückgestellt. test/tooling/resident_tool_names_test.dart fängt das ab und hält außerdem jeden Modus unter 40 residenten Tools. Genau das ist der Sinn — jenseits dieses Bandes wird die Tool-Auswahl messbar schlechter.

Die erforderlichen und verankerten Verben eines Modus kommen automatisch dazu, du musst das eigene Ausgabe-Verb eines Modus also nie selbst eintragen.

Eine schlechte Tool-Wahl diagnostizieren

Hat ein Agent das falsche Tool benutzt oder behauptet, etwas gehe nicht, kläre, welches von drei Dingen passiert ist.

1. Hat er nachgesehen?

Jeder Lauf zeichnet die zurückgestellten Tools auf, die er geladen hat, und wodurch — ein direkter Aufruf über den Namen oder eine Abfrage mit search_tools. Öffne den Ereignisstrom des Laufs (Einstellungen → Arbeitsbereich → Agenten → der Agent → Protokolle → Ansicht) und such nach [harness] loaded N deferred tool(s).

• Nichts protokolliert, und der Agent sagte, die Fähigkeit fehle — er hat nie nachgesehen. Das ist ein Prompt-Problem, kein Nachschlageproblem: Der zurückgestellte Index steht in seinem System-Prompt, mit der Anweisung, eine Fähigkeit nicht als fehlend zu erklären, bevor eine Suche leer zurückgekommen ist.
• Eine Suche protokolliert, aber nichts geladen — ein echter Fehltreffer beim Nachschlagen. Weiter mit Schritt 2.
• Tools geladen, das falsche benutzt — die gefundenen Tools sind sich zu ähnlich. Weiter mit Schritt 3.

2. Einen Fehltreffer beim Nachschlagen beheben

search_tools sucht in Namen, Beschreibungen und Argumentnamen. Ein Fehltreffer heißt fast immer, dass die Beschreibung die Wörter nicht enthält, die der Agent benutzt hat.

Ergänze sie. Beschreibungen sind der Abrufindex, also verlängere sie, statt sie zu kürzen — schreib das Vokabular, das ein Operator wirklich eintippen würde („assign“, „hand off“, „give to“), nicht nur das interne Nomen. Eine Beschreibung zu kürzen, um Token zu sparen, kostet dich den Suchtreffer und die Auswahlgenauigkeit und spart neben dem Schema fast nichts.

Steht das richtige Tool weit unten, ist das Argument limit genau dafür da; die eigene Beschreibung des Tools sagt dem Agenten, eine Suche zu verbreitern, die nah wirkt, aber danebenliegt.

3. Doppelgänger zusammenlegen

Lesen sich zwei Tools für jemanden gleich, der den Unterschied nicht schon kennt, rät das Modell. Fasse sie zu einem Tool mit einem unterscheidenden Argument zusammen.

ticket_relation und ticket_pr_link folgen diesem Muster: Jedes übernimmt Verknüpfen und Lösen über ein unterscheidendes Argument. Eine Wahl innerhalb eines Aufrufs, mit dem vollen Kontext der Anfrage, ist zuverlässiger als eine Wahl zwischen zwei Beschreibungen, die sich gleichen.

Lass Tools getrennt, wenn sie unterschiedliche Freigabe, unterschiedliches Audit oder unterschiedliche Darstellung brauchen — ein Zusammenlegen würde dich dann etwas Echtes kosten.

Prüfen, ob der Prompt-Cache arbeitet

Die Cache-Trefferquote erscheint unter Observability → Übersicht als Cache-Rate. Eine gesunde, lang laufende Unterhaltung liegt hoch; bleibt der Wert dauerhaft niedrig, schreibt etwas das Präfix bei jedem Turn um.

Häufige Ursachen, nach Wahrscheinlichkeit geordnet:

• Alles Nichtdeterministische früh im Prompt. Ein Zeitstempel, eine Anfrage-ID oder eine Menge, die in wechselnder Reihenfolge durchlaufen wird, reicht schon.
• Ein Wechsel von Modell oder Aufwand mitten in der Unterhaltung. Beides ändert das Präfix. Bei Subagenten geht das besonders leicht schief: Kinder mit niedrigerem Aufwand laufen zu lassen, um Geld zu sparen, kann durch das verlorene gemeinsame Präfix mehr kosten, als es spart.
• Häufige Verdichtung. Verdichtung schreibt den Verlauf absichtlich um, die Kosten sind also echt; die Abhilfe ist, selten und tief zu verdichten statt oft und flach.

Die Zurückstellung mit --tool-deferral=off auszuschalten ist ein gültiger A/B-Vergleich, um zu isolieren, ob eine Verhaltensänderung von der zweistufigen Oberfläche kam. Der Server erzeugt dann genau die Anfrage von vor der Zurückstellung. Bleibt das Verhalten auch so, ist die Oberfläche nicht die Ursache.