Domar los tool results

4.1El problema

Curaste el catálogo en L2 y des-precargaste el corpus en L3. Mediste la reducción del contexto estático: bajó, y mucho. Lanzas el sweep de N0 otra vez, confiado.

Y la curva todavía se dobla en los runs largos.

No tiene sentido a primera vista. Atacaste las dos partidas que disparaban el coste fijo: las 40 tools del flag y la biblioteca entera en el system prompt. Las dos cayeron. Pero el coste fijo nunca fue el problema completo. Era la mitad que se paga antes del primer turno. La otra mitad se paga durante, y crece con cada llamada.

Mira qué hace Magallanes en un run real. Llama a leer(doc-014). La tool devuelve el documento completo: un informe de 6.000 tokens. Ese bloque entra al historial. Tres turnos después, leer(doc-027): otros 5.000 tokens. El loop ReAct es append-only —lo mediste en N0·L3—: cada tool result se acumula en messages y se queda allí para siempre, aunque el agente ya no lo necesite.

Al turno 20, el historial arrastra una docena de documentos completos. La mayoría ya cumplieron su función: Magallanes extrajo lo que buscaba y siguió. Pero siguen ocupando el attention budget, turno a turno, contra el mismo presupuesto que todo lo demás.

El coste fijo lo dejaste fino. El crecimiento por turno sigue intacto. Esta lección lo doma.

4.2Qué vas a poder hacer

Al terminar serás capaz de:

• Diseñar la respuesta de una tool con límites por defecto, paginación, filtrado y truncado sensatos.
• Distinguir truncar con pérdida de truncar con referencia de recuperación, y elegir cuál aplica.
• Activar tool result clearing con la context editing API, protegiendo las tools que no deben borrarse.
• Decidir, ante un tool result concreto, qué técnica usa —truncar, paginar o clearing— y justificarlo.

Necesitas saber antes:

• De L3 (/cursos/context-engineering/tools-y-jit/just-in-time-y-progressive-disclosure): qué es una referencia ligera y qué te permite recuperar. Lo recuperamos en 4.3.
• Del nivel palancas y compaction (/cursos/context-engineering/palancas-y-compaction): qué preservaba tu compaction y qué descartaba primero.
• De N0·L3 (/cursos/context-engineering/diagnostico/el-presupuesto-de-tu-agente): qué partida del presupuesto crece por turno.
• El esqueleto congelado de Magallanes: sus 3 tools (buscar, leer, escribir_seccion) y la avería del flag lab_n3.

Un término que usarás desde la primera sección: la API de edición de contexto (context editing API) es la API beta de Anthropic que edita el historial activo durante la inferencia, bajo la beta context-management-2025-06-27. La activas en 4.5; aquí solo la nombramos.

4.3Recupera

Antes de seguir, responde de memoria. Esto reactiva lo anterior y lo engancha con lo nuevo.

1. De L3: una referencia ligera (file path, query guardada, doc_id). ¿Qué te permite hacer cuando la guardas en vez del contenido completo?
2. Del nivel palancas y compaction: tu compaction resumía lo irrecuperable. ¿Qué descartaba primero cuando tenía que liberar espacio?
3. De N0·L3: en Magallanes, ¿qué partida del presupuesto crece por turno y por culpa de qué tool?

4.4El concepto

El precedente que valida el problema

Empecemos por un dato que prueba que esto no es paranoia tuya. Claude Code limita las tool responses a 25.000 tokens por defecto. · fuente: corpus A.4 / D.1 (Anthropic, "Writing effective tools for agents", 11 sep 2025).

Lee eso despacio. Un equipo que construye agentes de primera línea decidió cortar las respuestas de las tools en seco a 25K tokens. No lo harían si las respuestas grandes fueran inofensivas. Existe el límite porque existe el problema: una tool que devuelve todo lo que tiene infla el contexto sin pedir permiso, y ese coste se acumula.

Tienes dos frentes para domar un tool result: rediseñar la respuesta para que nazca pequeña, y limpiar del historial las respuestas que ya cumplieron. Los vemos en ese orden.

Frente 1 — diseñar la respuesta

Una tool no tiene que devolver todo lo que sabe. Anthropic da cuatro técnicas para el diseño de la respuesta, con la consigna de elegir "sensible defaults" —valores por defecto sensatos— y priorizar "contextual relevance over flexibility" —relevancia contextual sobre flexibilidad—. · fuente: corpus D.1 (Anthropic, tools post, 11 sep 2025).

Las cuatro técnicas:

• Paginación. La tool devuelve una página de resultados, no todos. El resto se pide explícitamente con un cursor o un offset. buscar no vuelca 50 resultados: devuelve los primeros 5 y un puntero al siguiente lote.
• Filtrado. La tool devuelve solo los campos que importan para la tarea, no el objeto entero. Un resultado de búsqueda no necesita el documento completo: necesita doc_id, título y un snippet.
• Range selection (selección de rango). La tool devuelve un tramo del contenido —páginas 1–3 de un documento—, no el documento entero.
• Truncado. La tool corta la respuesta en un límite de tokens y señala que hay más.

La consigna "contextual relevance over flexibility" es la que decide los defaults. Una tool flexible deja que el agente pida cualquier cosa de cualquier forma. Una tool relevante devuelve, por defecto, lo que la tarea casi siempre necesita —y nada más—. Flexibilidad es comodidad para quien diseña; relevancia es presupuesto para quien ejecuta.

El error nº1: truncar sin referencia de recuperación

Normaliza esto, porque es el fallo que convierte una buena técnica en pérdida de datos. Truncar sin dejar forma de recuperar lo cortado es pérdida; truncar dejando el doc_id es paginación.

La diferencia es una sola pieza: la referencia de recuperación. Mira las dos versiones.

1# PÉRDIDA: corta el documento y tira lo que sobra. Irrecuperable.
2def leer(doc_id: str) -> str:
3    texto = cargar_documento(doc_id)
4    return texto[:2000]          # ¿y los otros 4000 tokens? Perdidos.
5
6# PAGINACIÓN: corta, pero devuelve cómo seguir. Recuperable.
7def leer(doc_id: str, pagina: int = 1) -> dict:
8    texto = cargar_documento(doc_id)
9    trozos = paginar(texto, tokens_por_pagina=2000)
10    return {
11        "doc_id": doc_id,                       # la referencia ligera de L3
12        "pagina": pagina,
13        "total_paginas": len(trozos),
14        "contenido": trozos[pagina - 1],
15        "hint": "Pide pagina=2 para seguir leyendo este doc_id.",
16    }

Las dos cortan en 2.000 tokens. La primera tira los otros 4.000 al vacío: si Magallanes los necesita luego, no hay vuelta. La segunda devuelve el doc_id, el número de página y cuántas quedan. Magallanes puede pedir leer(doc-014, pagina=2) y recuperar exactamente lo que se cortó.

Esa pieza —el doc_id que vuelve en la respuesta— es la referencia ligera de L3 trabajando aquí. L3 la usó para no precargar el corpus; L4 la usa para no arrastrar documentos enteros. El mismo identificador, dos ahorros.

Frente 2 — limpiar lo que ya cumplió

Diseñar respuestas pequeñas reduce el peso de cada result. Pero aun pequeños, se acumulan: 30 results de 200 tokens son 6.000 tokens que crecen turno a turno. Hace falta una segunda palanca que retire del historial los results que ya hicieron su trabajo.

Aquí entra una distinción que arrastras desde el nivel de palancas. Tu compaction de allí resumía lo irrecuperable: un párrafo de prosa que destila lo que ya no podrías reconstruir. El tool result clearing hace algo distinto: borra lo recuperable.

Define el término. El tool result clearing —limpieza de resultados de tool— elimina del historial los pares tool-use/tool-result más antiguos, dejando intactos los más recientes. No los resume: los quita. · fuente: corpus B.4 (paráfrasis del post de Anthropic, confianza media — el post lo describe como "una de las formas más seguras y ligeras de compaction"; lo presento como tal).

Por qué borrar y no resumir es seguro aquí: por la referencia ligera. Si clearing borra el result de leer(doc-014) y Magallanes lo vuelve a necesitar, re-lee con leer(doc-014). El documento no se perdió; salió del historial pero sigue en la biblioteca. La referencia de L3 es lo que hace que borrar sea reversible.

La analogía: clearing es vaciar la mesa de trabajo de papeles que ya consultaste, sabiendo que siguen en el archivador. Compaction es tomar notas a mano de una reunión que no se grabó. Dónde falla la analogía: clearing borra automáticamente por umbral de tokens, sin que nadie juzgue si "ya consultaste" cada papel; el criterio es la antigüedad, no la relevancia. Por eso necesitas proteger lo que no debe borrarse —lo vemos en 4.5—.

Regla para no confundirlas: clearing borra lo que puedes re-leer; compaction resume lo que no podrías reconstruir. Si hay una referencia ligera que recupera el dato, clearing. Si no, compaction.

Lo que NO es domar un tool result

No es bajar el max_tokens de la generación: eso recorta lo que Magallanes escribe, no lo que las tools le devuelven. Tampoco es borrar el historial entero al llegar a un umbral: eso tira las decisiones junto con los results, y las decisiones no se re-leen. Clearing borra results antiguos, no la línea de razonamiento.

4.5Míralo funcionar

Vamos a domar a Magallanes en dos pasos: rediseñar leer() para que pagine, y activar tool result clearing en el run con context_management. Es código de la context editing API; tiene varias claves anidadas.

Antes de leerlo línea a línea, lee el bloque entero una vez de corrido. Lo difícil no es ninguna clave suelta; es ver qué hace cada parte del context_management. Primero hazte una idea de la forma: un trigger que decide cuándo, un keep que decide cuánto se salva, un exclude que protege.

Paso 1 — leer() paginado con límite por defecto

1# leer() rediseñada: límite de tokens por defecto + paginación por doc_id.
2# El documento completo solo si se pide explícitamente, página a página.
3TOKENS_POR_PAGINA = 2000   # default sensato; NO el documento entero
4
5def leer(doc_id: str, pagina: int = 1) -> dict:
6    texto = cargar_documento(doc_id)
7    trozos = paginar(texto, tokens_por_pagina=TOKENS_POR_PAGINA)
8    return {
9        "doc_id": doc_id,                       # referencia ligera: permite re-leer
10        "pagina": pagina,
11        "total_paginas": len(trozos),
12        "contenido": trozos[pagina - 1],
13        "hint": "Pide pagina=N para más; el doc_id es estable.",
14    }

Tres cosas de este diseño:

• El default es una página de 2.000 tokens, no el documento de 6.000. La mayoría de los leer() solo necesitan el principio; pagar 6.000 cuando bastan 2.000 es lastre.
• El doc_id vuelve en la respuesta. Es la referencia ligera: si clearing borra esta página, Magallanes la recupera con leer(doc_id, pagina).
• El total_paginas y el hint le dicen a Magallanes que hay más y cómo pedirlo. Truncar a ciegas escondería esa información; aquí está explícita.

Paso 2bis — cómo la respuesta paginada llega al run

Antes de activar el clearing, ve dónde encaja la leer() del Paso 1. Magallanes corre su loop ReAct; cada leer(doc_id) produce un par tool-use/tool-result que se acumula en messages. Ese historial es lo que pasas al create con el clearing activo. La estrategia actúa sobre esos pares.

1# messages = historial de Magallanes con sus tool results de leer() paginada.
2# Cada par assistant/tool sigue el formato de la API; el clearing actúa sobre ellos.
3messages = historial_de_magallanes   # lista con tool_use + tool_result de leer()
4
5response = client.beta.messages.create(
6    model="claude-opus-4-5",
7    max_tokens=4096,
8    betas=["context-management-2025-06-27"],
9    messages=messages,            # ← los tool results paginados del Paso 1 entran aquí
10    context_management={...},     # ← la configuración del Paso 2, sobre estos pares
11)

La pieza que cierra el bucle: la leer() del Paso 1 hace que cada result nazca pequeño; el context_management del Paso 2 retira los results viejos de ese mismo messages. Las dos palancas trabajan sobre el mismo historial.

Paso 2 — tool result clearing en el run

Ahora detallamos el context_management que el Paso 2bis dejó como {...}. La API de edición de contexto es beta: requiere un header concreto y una estrategia con nombre versionado.

1import anthropic
2
3client = anthropic.Anthropic()
4
5# Firma EXACTA (corpus F.6.c / ÍTEM 2 del api-nivel3): beta header obligatorio,
6# estrategia clear_tool_uses_20250919 con sus parámetros.
7response = client.beta.messages.create(
8    model="claude-opus-4-5",
9    max_tokens=4096,
10    betas=["context-management-2025-06-27"],     # ← header requerido por la beta
11    messages=messages,                            # el historial de Magallanes (Paso 2bis)
12    context_management={
13        "edits": [
14            {
15                "type": "clear_tool_uses_20250919",
16                "trigger": {"type": "input_tokens", "value": 30000},     # cuándo limpiar; default 100000
17                "keep": {"type": "tool_uses", "value": 3},               # preserva los 3 más recientes; default 3
18                "clear_at_least": {"type": "input_tokens", "value": 5000},  # ahorro mínimo por activación
19                "exclude_tools": ["memory"],                              # tools inmunes al borrado
20                "clear_tool_inputs": False,                               # default: no toca los inputs
21            }
22        ]
23    },
24)

Lee cada parámetro como una decisión:

• trigger — cuándo se activa el clearing. Aquí, cuando el input supera 30.000 tokens. El default es 100.000. · fuente: corpus F.6.c / api-nivel3 ÍTEM 2.
• keep — cuántos pares tool-use/tool-result recientes se preservan. Aquí los 3 últimos, que es el default. Los más antiguos son los que se borran: los que ya cumplieron.
• clear_at_least — el mínimo de tokens que cada activación debe liberar. Si no puede liberar esa cantidad, la estrategia no se aplica. Evita activaciones que apenas ahorran. · fuente: api-nivel3 ÍTEM 2.
• exclude_tools — la lista de tools cuyos results nunca se borran. Aquí protege "memory".
• clear_tool_inputs — si también se borran los inputs de las tool calls. Por defecto False: borra los results, deja los inputs.

Cuando el clearing se activa, la respuesta incluye context_management.applied_edits con cuántos tool uses se limpiaron y cuántos tokens se liberaron. · fuente: api-nivel3 ÍTEM 2. Ese número es lo que mides antes/después.

Una nota de orden, por si combinas estrategias. Si usas clear_tool_uses_20250919 junto con clear_thinking_20251015, esta última debe ir primero en el array edits. · fuente: corpus F.6.c / api-nivel3 ÍTEM 2c (confirmado contra la doc oficial). En Magallanes solo activamos el clearing de tool uses, así que no aplica todavía.

El peso por turno: antes y después

Estos números son ilustrativos —tu run dará los suyos—; lo que importa es la forma:

turno | sin domar (tokens hist.) | con domar (tokens hist.)
------+--------------------------+-------------------------
   5  |          12.000          |          9.500
  10  |          28.000          |         14.000
  15  |          47.000          |         16.500   ← clearing se activó
  20  |          71.000          |         18.000

Lee la forma. Sin domar, el historial crece casi lineal: cada leer() añade un documento entero que se queda. Con domar, crece más despacio (paginación) y se estabiliza tras el turno 15 (clearing retira los results antiguos al cruzar el trigger). La pendiente que se doblaba en 4.1 se aplana.

Self-explanation

Antes de leer la respuesta, intenta tú: ¿por qué excluimos la tool de memoria del clearing con exclude_tools?

4.6Hazlo tú

Andamiaje decreciente: primero aplicas la receta a buscar con pasos dados; luego decides los defaults de las tres tools congeladas sin pasos.

Ejercicio 1 — paginar y filtrar buscar (con esqueleto)

buscar(query) de Magallanes devuelve la lista completa de resultados, cada uno con el documento entero embebido. Es lo contrario de "contextual relevance over flexibility". Complétala sobre este esqueleto: hay dos huecos marcados con # TODO que debes rellenar tú.

1def buscar(query: str, top_k: int = 5) -> dict:
2    resultados = motor_de_busqueda(query)   # devuelve muchos, con texto completo
3    # FILTRADO + PAGINACIÓN: queda con campos ligeros, solo los top_k mejores.
4    recortados = [
5        {
6            # TODO 1: ¿qué tres campos incluyes por resultado?
7            # Pista: necesitas identificar el doc, mostrar algo legible
8            # y dejar una referencia para recuperar el texto completo.
9            # NO incluyas r["texto"] entero — esa es la avería que arreglas.
10        }
11        for r in resultados[:top_k]            # paginación: solo top_k
12    ]
13    return {
14        "resultados": recortados,
15        # TODO 2: añade las claves que permitan a Magallanes saber
16        # si hay más resultados y cómo pedirlos (cobertura + cómo seguir).
17    }

Después de completarlo, compáralo con la solución y justifica por escrito:

1recortados = [
2    {
3        "doc_id": r["doc_id"],
4        "titulo": r["titulo"],
5        "snippet": r["texto"][:200],   # 200 chars ≈ 40-60 tokens; en producción usa count_tokens()
6    }
7    for r in resultados[:top_k]
8]
9return {
10    "resultados": recortados,
11    "total_encontrados": len(resultados),
12    "hint": "Sube top_k o usa leer(doc_id) para el texto completo.",
13}

Ejercicio 2 — los defaults de las tres congeladas (sin esqueleto)

Sin plantilla. Decide y justifica el default de cada una de las tres tools congeladas de Magallanes:

• buscar(query) — ¿qué top_k por defecto, qué longitud de snippet?
• leer(doc_id) — ¿qué tamaño de página por defecto?
• escribir_seccion(titulo, contenido) — ¿qué devuelve, y de qué tamaño?

Para cada una, escribe el default y la frase que lo justifica contra "contextual relevance over flexibility". Luego verifícalo con un run: el informe final tiene que salir igual de bien con los defaults pequeños que sin ellos. Si el informe empeora, un default era demasiado agresivo —recórtalo menos—.

Elaborative interrogation — antes de correrlo, predice: ¿cuál de las tres tools es la que más tolera un default pequeño, y cuál la que menos? ¿Por qué?

4.7Comprueba

Sin pistas. Gate de maestría: ante un tool result concreto, elegir la técnica y justificarla.

Magallanes llamó a una tool que devolvió un tool result de 8.000 tokens: el texto completo de un informe. La tarea solo necesitaba la sección de conclusiones (unos 600 tokens). El run va por el turno 12 y el historial ya pesa.

1. Decide qué técnica aplica: ¿truncar, paginar o clearing? (Puede ser más de una.)
2. Di qué se conserva y qué se va.
3. Justifica tu decisión contra "contextual relevance over flexibility".

4.8Conecta

Acabas de cerrar la cuarta partida del presupuesto de N0·L3: la que crecía por turno.

Recapitula el arco del nivel. L1 midió el coste de las tools y del corpus precargado. L2 curó el catálogo de 40 a ≤12. L3 des-precargó el corpus a referencias ligeras. Esas tres atacaron el coste fijo —lo que se paga antes y al margen del primer turno—. L4 ataca el crecimiento por turno —lo que entra por las respuestas y se acumula—. Con las dos mitades domadas, el agente que amaneció inflado en L1 opera ya con un contexto que no se dispara.

La referencia ligera de L3 fue la pieza que lo hizo posible. Sin ella, recortar un result sería perder; con ella, recortar es paginar y borrar es reversible. L3 te dio el identificador; L4 lo cobró dos veces.

L5 lo integra todo en el checkpoint C3: contexto estático reducido ≥50% medido, con la fiabilidad preservada en el sweep de N0. Reparte bien las contribuciones antes de medir. L1–L3 atacan las dims 1–4 de C3 —la reducción del contexto estático que mides con count_tokens antes del primer turno—. L4 ataca la dim 5 —fiabilidad preservada: la curva ya no se dobla aunque Magallanes procese el mismo volumen de documentos—. Lo que mediste aquí —el peso por turno antes y después— es esa evidencia; no lo busques en el count_tokens previo al primer turno, porque el clearing actúa durante el run, no antes.

Y mira hacia N4 (/cursos/context-engineering/aislamiento). Domar los results es hacer que una tool explore mucho y devuelva poco: lee un documento de 6.000 tokens, retorna una página de 2.000. Esa idea —explorar en un contexto amplio y devolver un resumen condensado— es la semilla del aislamiento. Un subagente hace lo mismo a escala: trabaja en su propia ventana y entrega solo lo destilado.

Cierra el arco que abrimos en 4.1: la curva se doblaba pese a haber curado y des-precargado. Ahora sabes por qué —el crecimiento por turno— y cómo aplanarla. Poner límites a las respuestas parece quitarle información al agente. El harness dirá si era información o lastre — y en el ejercicio 2 lo verificaste: el informe sale igual de bien.

4.9Reflexiona

Tómate un minuto. Responder esto por escrito consolida más que releer.

• ¿Qué aprendiste? Resume en una frase qué pieza separa "truncar con pérdida" de "paginar", y por qué esa pieza hace que el clearing sea seguro.
• ¿Qué sigue sin estar claro? ¿Tienes nítida la diferencia entre clearing (borra lo recuperable) y compaction (resume lo irrecuperable)? Si no, vuelve a 4.4, frente 2, y a la regla que las separa.
• ¿Qué harías distinto? La próxima vez que diseñes una tool nueva, ¿qué te preguntarás sobre su respuesta antes de que devuelva su primer resultado?

Esto requiere práctica. La intuición de "qué default es lastre y cuál es información" llega corriendo runs y mirando el harness, no leyendo. En L5 integrarás esta técnica con la curación de L2 y el JIT de L3 en el entregable de C3.