Ajustar el contexto de herramientas de un agente

Esta guía abarca el trabajo práctico en torno a la superficie de herramientas de dos niveles: ver lo que envía una ejecución, cambiarlo y diagnosticar a un agente que eligió la herramienta equivocada. Para entender por qué funciona así, lee Contexto de herramientas y caché de prompts.

Observa lo que realmente envía una ejecución

Abre una conversación y toca el indicador de uso de contexto en el encabezado de la conversación. Reconstruye la superficie exacta que enviaría el siguiente despacho, sin ejecutar nada. Ver más (o el comando /context) abre el explorador de contexto completo, donde puedes inspeccionar cada herramienta.

Aquí importan dos segmentos:

• Definiciones de herramientas y MCP y herramientas dinámicas — el conjunto residente, con el costo real en tokens de cada herramienta.
• Herramientas cargadas bajo demanda — el índice diferido. A cada entrada solo se le cobra su nombre, porque un nombre es todo lo que lleva la solicitud; abrir una aún muestra la descripción y el esquema completos, así que puedes ver lo que costaría si la ejecución la trajera.

Si el segmento diferido está vacío, el diferimiento está desactivado para este servidor. Revisa --tool-deferral en la CLI de cc_server.

Cambia qué herramientas se cargan desde el inicio

El conjunto residente es política, no configuración — vive en ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) y se aplica a cada ejecución:

• residentBuiltins — el vocabulario de archivos y shell.
• residentDiscovery — search_tools y list_my_tools. No las quites; son la forma en que un agente llega a todo lo demás.
• residentMcpTools — el puñado de herramientas de Control Center que valen su esquema en cada solicitud.
• Un bloque por modo, para las herramientas que un modo dado usa en casi todos los turnos.

Dos reglas al editarlo:

Agrega una herramienta solo si la mayoría de las ejecuciones la usa. Cada nombre cuesta su esquema en cada solicitud de cada ejecución, para siempre. Una herramienta que es importante cuando se usa, pero poco frecuente en general, pertenece a la mitad diferida — el agente la encontrará de todos modos.

Usa el nombre real de la herramienta. Un nombre residente que no coincide con ninguna herramienta es inerte: no hay error, no hay advertencia, la herramienta simplemente se difiere. test/tooling/resident_tool_names_test.dart detecta esto y además mantiene cada modo por debajo de 40 herramientas residentes, que es el objetivo del ejercicio — pasada esa banda, la selección de herramientas se degrada de forma medible.

Los verbos obligatorios y fijados de un modo se agregan automáticamente, así que nunca necesitas enumerar el verbo de salida propio de un modo.

Diagnostica una mala elección de herramienta

Cuando un agente usó la herramienta equivocada o afirmó que no podía hacer algo, determina cuál de estas tres cosas ocurrió.

1. ¿Buscó?

Cada ejecución registra las herramientas diferidas que cargó y qué lo desencadenó — una llamada directa por nombre o una consulta a search_tools. Abre el flujo de eventos de la ejecución (Ajustes → Espacio de trabajo → Agentes → el agente → Registros → Vista) y busca [harness] loaded N deferred tool(s).

• No se registró nada y el agente dijo que faltaba la capacidad — nunca buscó. Eso es un problema de prompt, no de recuperación: el índice diferido está en su prompt del sistema con la instrucción de no declarar que falta una capacidad hasta que una búsqueda haya vuelto vacía.
• Se registró una búsqueda, pero no se cargó nada — un fallo de recuperación genuino. Ve al paso 2.
• Se cargaron herramientas, pero usó la equivocada — las herramientas que encontró son demasiado parecidas. Ve al paso 3.

2. Corrige un fallo de recuperación

search_tools hace coincidir nombres, descripciones y nombres de argumentos. Un fallo casi siempre significa que la descripción no contiene las palabras que usó el agente.

Agrégalas. Las descripciones son el índice de recuperación, así que alárgalas en lugar de recortarlas — escribe el vocabulario que un operador realmente teclearía («asignar», «delegar», «dar a»), no solo el sustantivo interno. Recortar una descripción para ahorrar tokens te cuesta tanto el acierto de búsqueda como la precisión de selección, y ahorra casi nada frente al esquema.

Si la herramienta correcta existe pero queda en un puesto bajo, para eso sirve el argumento limit; la propia descripción de la herramienta le indica al agente que amplíe una búsqueda que parece cercana pero falla.

3. Corrige las herramientas que se parecen

Si dos herramientas tienen descripciones que se leerían igual para alguien que aún no conoce la diferencia, el modelo está adivinando. Fusiónalas en una sola herramienta con un argumento discriminante.

ticket_relation y ticket_pr_link siguen este patrón: cada una maneja vincular y desvincular mediante un argumento discriminante. Una elección hecha dentro de una llamada, con el contexto completo de la solicitud, es más fiable que una elección hecha entre dos descripciones que se parecen.

Mantén las herramientas separadas cuando necesiten un control de aprobación distinto, una auditoría distinta o un renderizado distinto — esas son razones por las que una fusión te costaría algo real.

Comprueba que la caché de prompts funcione

La tasa de aciertos de caché aparece en Observabilidad → Resumen como Tasa de caché. Una conversación larga y saludable se mantiene alta; si está persistentemente baja, algo está reescribiendo el prefijo en cada turno.

Causas comunes, en orden de probabilidad:

• Cualquier cosa no determinista al inicio del prompt. Una marca de tiempo, un id de solicitud o un conjunto iterado en un orden variable bastan.
• Un cambio de modelo o de esfuerzo a mitad de la conversación. Ambos cambian el prefijo. Los subagentes son especialmente fáciles de equivocar aquí: ejecutar a los hijos con un esfuerzo menor para ahorrar dinero puede costar más en pérdida de caché compartida de lo que ahorra.
• Compactación frecuente. La compactación reescribe el historial por diseño, así que su costo es real; la solución es compactar de forma poco frecuente y profunda en lugar de frecuente y superficial.

Desactivar el diferimiento con --tool-deferral=off es una prueba A/B válida para aislar si un cambio de comportamiento provino de la superficie de dos niveles. Reproduce exactamente la solicitud previa al diferimiento, así que si el comportamiento persiste con el diferimiento desactivado, la superficie no es la causa.