🔧 Herramientas y el Contrato de Herramienta
Enumerar las herramientas no basta. Tu IA llamará a la herramienta equivocada, ignorará dependencias o hará diez llamadas en fila cuando una llamada por lotes lo resolvería. La solución es el Contrato de herramienta: para cada herramienta, indica cuándo llamar, qué va antes, qué nunca usar y cómo agrupar. Te vas de aquí con seis cláusulas listas para pegar.
Contenido detallado
Desencadenante de uso: cuándo llamar
En el módulo de la biblioteca viste el bloque herramientas decir lo que existeEsto es solo la mitad. La otra mitad —la que hace que la IA deje de tantear— es el disparador de usola condición clara que dice cuándo entra esa herramienta. «Tienes una búsqueda web» es una capacidad. «Usa la búsqueda cuando necesites un dato posterior a tu fecha de corte de conocimiento» es un contrato. La diferencia es abismal.
🎯 La idea en una frase
El Contrato de Herramientas dice cuándo y en qué orden llamar a cada herramienta — no solo el qué existe. Enumerar es la Declaración de Capacidades; contratar es el paso siguiente, y es lo que separa a un agente que ejecuta con disciplina de uno que llama a la herramienta equivocada en el momento equivocado.
El corazón de cada cláusula es el activador: "úsalo cuando {condición}". Sin él, el modelo adivina —y adivina mal: llama a la búsqueda para cosas que ya sabe o no la llama cuando realmente hacía falta.
Qué es el disparador
Una frase que vincula la herramienta a una situación observable«usa la calculadora cuando la cuenta tenga más de un paso», «usa la búsqueda cuando el usuario pida algo actual», «usa el lector de archivos cuando necesites el contenido, no el nombre». El disparador responde la única pregunta que importa al momento de actuar: ¿esto aplica ahora?
Por qué el disparador lo cambia todo
Porque, sin una condición de activación, la herramienta se vuelve una tentación. El modelo la usa en exceso (la llama para todo y gasta tiempo y tokens) o la ignora (responde de memoria cuando debería haber buscado). El activador convierte «puedes» en «debes, exactamente aquí»: es la parte del contrato que más reduce las llamadas erróneas.
Requisito previo: el paso obligatorio antes
Algunas herramientas tienen un orden sagrado: antes de hacer X, haz Y. El ejemplo clásico, que aparece literalmente en las reglas de herramientas reales, es leer antes de editar: no puedes editar un archivo que nunca leíste, porque si no viste el contenido actual, la edición es una apuesta. El prerrequisito es la cláusula que hace explícita esa dependencia.
You MUST use the Read tool at least once before editing.
Una frase. Mayúsculas en DEBE, el orden explícito ("al menos una vez antes de editar"). No es una sugerencia: es la puerta que debe abrirse antes de continuar.
🔗 Por qué importa declarar el orden
- ① La IA no infiere la dependencia por sí sola. Para ella, editar y leer son dos herramientas separadas. Tienes que vincular una con la otra.
- ② Omitir el paso causa daño silencioso. Editar sin leer sobrescribe lo que no viste, y el error solo aparece después, cuando ya es tarde.
- ③ La regla es breve y cuesta poco. Una línea en el contrato evita toda una clase de fallas. ROI altísimo.
La plantilla del prerrequisito
Requisito previo: antes de {ação}, {paso obligatorio}. Ejemplos: "antes de editar, lee el archivo"; "antes de enviar el correo, muestra el borrador"; "antes de ejecutar el deploy, ejecuta las pruebas". Siempre antes de + la puerta que debe estar abierta.
Exclusión: usa X, nunca Y
Cuando dos herramientas parecen servir para el mismo caso, la IA elige — y a veces elige la peor. La cláusula de exclusión le quita la elección de las manos: "para este caso, usa X, nunca Y". El ejemplo que define el estándar viene de Cursor: usa la herramienta dedicada para archivos, nunca la terminal.
Use specialized tools instead of terminal commands when possible… don't use cat/head/tail to read files, don't use sed/awk to edit files… Reserve terminal commands exclusively for actual system commands.
Observa la forma: dice qué usar (la herramienta dedicada), lo que no usar (cat, head, tail, sed, awk) y reserva la terminal para lo que de verdad es un comando del sistema. Opción descartada.
✓ Exclusión que funciona
- ✓"Para leer un archivo, usa el lector — nunca la terminal"
- ✓Nombra a la ganadora Y a la prohibida, sin ambigüedades
- ✓Se aplica solo al caso («para esto»), no a todo
- ✓Resuelve una confusión real que ya viste ocurrir
✗ Exclusión que estorba
- ✗"No uses la terminal" — sin decir qué usar en su lugar
- ✗Prohíbe sin un caso ("nunca, jamás"), bloqueando usos legítimos
- ✗Crea exclusión entre herramientas que no se solapan
- ✗Inventa una regla para un conflicto que nunca ocurrió
<ferramentas> Para ler/editar arquivos, use a ferramenta dedicada — nunca o terminal. Reserve o terminal só para comandos de sistema de verdade (git, mkdir, mover). </ferramentas>
Ejecución por lotes y paralelismo
Aquí hay una enorme ganancia de velocidad que casi nadie escribe en el prompt: cuando necesitas varias cosas que no dependen una de la otra, pide todas de una vez, en el mismo bloque, en paralelo. ¿Leer tres archivos distintos? ¿Buscar dos cosas diferentes? No hay motivo para hacerlo en fila. La regla de paralelismo de Claude Code lo dice directamente.
If you intend to call multiple tools and there are no dependencies between the calls, make all of the independent calls in the same block.
La condición es «no hay dependencias entre las llamadas"; la acción es "make all of the independent calls in the same block". Independiente → juntas. Dependiente → no (ese es el siguiente tema).
Sin contrato: en la cola, sin motivo
La IA lee el archivo A, espera, lee el B, espera, lee el C. Tres idas y vueltas.
Nada dependía de nada — A, B y C son independientes. Pero sin la regla, el modelo los serializa por costumbre. El usuario espera el triple de lo necesario, y la tarea se vuelve lenta sin motivo.
Con contrato: todos en el mismo bloque
La IA ejecuta las tres lecturas a la vez y lee las tres respuestas que recibe.
Una sola ida. El contrato de batching dice: llamadas independientes → en el mismo bloque, en paralelo. El resultado es el mismo, pero llega en una fracción del tiempo. Velocidad gratis.
La prueba de independencia
Antes de agrupar, pregúntate: "¿La llamada B necesita el resultado de la A?" Si la respuesta es no para todas, van todas juntas. Si alguna la necesita, esa queda fuera del bloque y espera. El batching solo aplica a lo que es genuinamente independiente; no fuerces la ejecución en paralelo cuando hay dependencias.
No menciones el nombre de la herramienta al usuario
Una pequeña cláusula de etiqueta, con un gran efecto en la experiencia: al hablar con el usuario, describe la acción en lenguaje natural — no recites el nombre interno de la herramienta. El usuario quiere saber «estoy buscando esto por ti», no «voy a invocar la función web_search con el parámetro query". El nombre de la herramienta es un asunto interno.
✓ Dilo así (lenguaje natural)
- ✓"Déjame buscarlo por ti…"
- ✓"Voy a leer el archivo para ver qué contiene"
- ✓"Calculé y el total es R$ 1.240"
- ✓Describe la intención, no el mecanismo
✗ No lo digas así (revela lo que pasa entre bastidores)
- ✗"Llamando a la tool search_web…"
- ✗"Ejecutando read_file(path=…)"
- ✗"Voy a usar la función calculator ahora"
- ✗Expone nombres internos que no significan nada para el usuario
Não cite o nome da ferramenta ao falar com o usuário; diga em linguagem natural o que está fazendo.
Por qué esto importa de verdad
El nombre de la herramienta es un detalle de implementación. Mencionarlo contamina la conversación, confunde a quien no es técnico y ata tu prompt a nombres que pueden cambiar. La regla mantiene a la IA hablando de resultados, no de plomería, y la experiencia queda limpia.
Encadenamiento: usar el resultado anterior
Lo contrario del batching: a veces la llamada B solo tiene sentido con lo que devolvió la AEn ese caso no se puede paralelizar: debe hacerse en serie, y B necesita consumir el output exacto de A. Ese es el encadenamiento: el contrato que dice "toma tal campo del resultado anterior y pásalo al siguiente". Sin él, la IA inventa el vínculo y rompe el pipeline.
A — buscar: "encuentra el ID del pedido por el correo electrónico del cliente"
devuelve: pedido_id = 8842
B — detallar: "abre los detalles del pedido {pedido_id}"
contrato: usa exactamente el pedido_id que A devolvió — no adivines un número.
Observa el patrón: la cláusula de encadenamiento nombra qué campo sale de A y para dónde entra en B. Cuanto más exacto sea el formato declarado ("el pedido_id en el formato numérico"), menos improvisa la IA. Es el hermano de la exclusión: uno dice qué herramienta, el otro dice con qué dato.
⚠️ Los tres errores de encadenamiento
Cuando el pipeline falla, casi siempre es por una de estas razones:
- 1.Paralelizar lo que depende de otra cosa. B se ejecuta junto con A y usa un valor que todavía no existe → error o basura.
- 2.Inventar el vínculo. La IA no toma el campo real de A; inventa un valor plausible y sigue → resultado incorrecto, sin aviso.
- 3.Formato impreciso. El contrato no indica qué campo ni en qué formato → la IA toma la parte equivocada del output.
🛠️ Manos a la obra: tu entregable
Toma una IA tuya que use herramientas y escribe el contrato de estas. En 15 minutos completas las seis cláusulas.
- 1 Enumera las herramientas que tu IA realmente tiene. Para cada una, escribe el disparador«usa cuando {condición}».
- 2 Marca los prerrequisitos (¿alguna necesita un paso previo? ej.: leer antes de editar) y las exclusiones (¿se confunden las dos? "usa X, nunca Y").
- 3 Escribe la regla de batching ("independientes → en el mismo bloque") y marca los encadenamientos (¿qué campo de A necesita B?).
- 4 Agrega la línea de etiqueta ("no menciones el nombre de la herramienta al usuario"). Pega todo en el bloque <ferramentas>, ejecuta una tarea real y fíjate si la IA elige y agrupa correctamente.
📝 Resumen del Módulo
- ✓O Contrato de herramienta dice cuándo y en qué orden llamar — no solo lo que existe
- ✓Desencadenante: vincula la herramienta a una condición observable — «úsala cuando {condição}»
- ✓Requisito previo: el paso obligatorio antes — p. ej.: leer antes de editar
- ✓Exclusión: "usa X, nunca Y" para el caso — elimina la opción equivocada
- ✓Ejecución por lotes: llamadas independientes → en el mismo bloque, en paralelo; dependientes → encadenadas en serie
- ✓Etiqueta: al usuario, dile la acción en lenguaje natural — no cites el nombre de la herramienta
➡️ Siguiente Módulo
2.5 — 🔁 El ciclo operativo. Contrataste las herramientas; ahora vamos a darle a la IA el ciclo de trabajo que usa esos contratos con disciplina: aterrizar, razonar, actuar, observar, verificar, narrar — el cerebro del agente.