De toolcontext van een agent afstemmen

Deze gids behandelt het praktische werk rond het tooloppervlak met twee niveaus: zien wat een run verstuurt, dat wijzigen en een agent diagnosticeren die naar de verkeerde tool greep. Lees Toolcontext en promptcaching voor het waarom achter dit ontwerp.

Bekijk wat een run echt verstuurt

Open een gesprek en tik in de kop van het gesprek op de indicator voor contextgebruik. Die bouwt het exacte oppervlak op dat de volgende dispatch zou versturen, zonder iets uit te voeren. Meer weergeven (of het commando /context) opent de volledige contextverkenner, waar je elke tool kunt inspecteren.

Twee segmenten zijn hier van belang:

• Tooldefinities en MCP & dynamische tools — de residente set, met de echte tokenkosten van elke tool.
• Tools die op aanvraag laden — de uitgestelde index. Elke vermelding kost alleen zijn naam, want een naam is alles wat het verzoek meedraagt; open je er een, dan zie je nog steeds de volledige beschrijving en het schema, zodat je kunt zien wat die zou kosten als de run hem erbij haalde.

Als het uitgestelde segment leeg is, staat uitstelling uit voor deze server. Controleer --tool-deferral op de cc_server CLI.

Wijzig welke tools vooraf laden

De residente set is beleid, geen configuratie — hij staat in ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) en geldt voor elke run:

• residentBuiltins — het bestands- en shellvocabulaire.
• residentDiscovery — search_tools en list_my_tools. Verwijder deze niet; zo bereikt een agent al het overige.
• residentMcpTools — het handjevol Control Center-tools waarvan het schema bij elk verzoek de moeite waard is.
• Een blok per modus, voor de tools die een bepaalde modus in bijna elke beurt gebruikt.

Twee regels bij het bewerken ervan:

Voeg een tool alleen toe als de meeste runs hem gebruiken. Elke naam kost zijn schema bij elk verzoek van elke run, voor altijd. Een tool die belangrijk is wanneer hij wordt gebruikt, maar over het geheel genomen zeldzaam, hoort in de uitgestelde helft — de agent vindt hem nog steeds.

Gebruik de echte naam van de tool. Een residente naam die op geen enkele tool matcht, is inert: geen fout, geen waarschuwing, de tool wordt simpelweg uitgesteld. test/tooling/resident_tool_names_test.dart vangt dit af en houdt elke modus ook onder 40 residente tools, en dat is precies het doel van de oefening — voorbij die band gaat de toolselectie meetbaar achteruit.

De vereiste en vastgezette werkwoorden van een modus worden automatisch toegevoegd, dus je hoeft het eigen outputwerkwoord van een modus nooit te vermelden.

Diagnosticeer een slechte toolkeuze

Wanneer een agent de verkeerde tool gebruikte of beweerde iets niet te kunnen, zoek dan uit welke van drie dingen er is gebeurd.

1. Heeft hij gekeken?

Elke run legt vast welke uitgestelde tools hij heeft geladen en wat de aanleiding was — een rechtstreekse aanroep op naam, of een zoekopdracht via search_tools. Open de gebeurtenissenstroom van de run (Instellingen → Werkruimte → Agenten → de agent → Logboeken → Bekijken) en zoek naar [harness] loaded N deferred tool(s).

• Niets gelogd, en de agent zei dat de capaciteit ontbrak — hij heeft nooit gekeken. Dat is een promptprobleem, geen ophaalprobleem: de uitgestelde index staat in zijn systeemprompt, met de instructie om een capaciteit pas als ontbrekend te bestempelen nadat een zoekopdracht leeg is teruggekomen.
• Een zoekopdracht gelogd, maar niets geladen — een echte gemiste ophaling. Ga naar stap 2.
• Tools geladen, de verkeerde gebruikt — de tools die hij vond, lijken te veel op elkaar. Ga naar stap 3.

2. Een gemiste ophaling verhelpen

search_tools matcht op namen, beschrijvingen en argumentnamen. Een gemiste ophaling betekent bijna altijd dat de beschrijving niet de woorden bevat die de agent gebruikte.

Voeg ze toe. Beschrijvingen vormen de ophaalindex, dus maak ze langer in plaats van ze in te korten — schrijf het vocabulaire dat een operator daadwerkelijk zou intypen (“toewijzen”, “overdragen”, “geven aan”), niet alleen het interne zelfstandig naamwoord. Een beschrijving inkorten om tokens te sparen kost je zowel de zoektreffer als de selectienauwkeurigheid, en levert naast het schema bijna niets op.

Als de juiste tool bestaat maar laag scoort, is dat waarvoor het argument limit dient; de eigen beschrijving van de tool zegt de agent een zoekopdracht te verbreden die dichtbij lijkt maar er net naast zit.

3. Dubbelgangers aanpakken

Als twee tools beschrijvingen hebben die hetzelfde zouden lezen voor iemand die het verschil niet al kent, dan gokt het model. Voeg ze samen tot één tool met een onderscheidend argument.

ticket_relation en ticket_pr_link volgen dit patroon: elk regelt het koppelen en ontkoppelen via een onderscheidend argument. Een keuze binnen één aanroep, met de volledige context van het verzoek, is betrouwbaarder dan een keuze tussen twee gelijkende beschrijvingen.

Houd tools gescheiden wanneer ze een andere goedkeuringspoort, een andere auditlogging of een andere weergave nodig hebben — dat zijn redenen waarom samenvoegen je iets echts zou kosten.

Controleer of de promptcache werkt

Het percentage cachetreffers is te zien in Observeerbaarheid → Overzicht als Cache-percentage. Een gezond, lang lopend gesprek staat hoog; staat het aanhoudend laag, dan herschrijft iets bij elke beurt het voorvoegsel.

Veelvoorkomende oorzaken, in volgorde van waarschijnlijkheid:

• Alles wat vroeg in de prompt niet-deterministisch is. Een tijdstempel, een verzoek-id of een set die in wisselende volgorde wordt doorlopen, is genoeg.
• Een wijziging van model of inspanning midden in een gesprek. Beide wijzigen het voorvoegsel. Bij subagenten gaat dit extra makkelijk mis: kinderen op een lagere inspanning laten draaien om geld te sparen kan meer kosten aan verloren cachedeling dan het oplevert.
• Frequente compactie. Compactie herschrijft de geschiedenis per ontwerp, dus de kosten zijn reëel; de oplossing is om zelden en diep te compacteren in plaats van vaak en oppervlakkig.

Uitstelling uitzetten met --tool-deferral=off is een geldige A/B-test om te isoleren of een gedragswijziging van het oppervlak met twee niveaus kwam. Het reproduceert het verzoek van vóór de uitstelling exact, dus als het gedrag met uitstelling uit aanhoudt, is het oppervlak niet de oorzaak.