avanzado
Diseño de herramientas para agentes
Cubre: Herramientas que el prompt define o dirige
Respuesta rápida:
Una herramienta es la parte del prompt que se ejecuta. El modelo no lee tu documentación: lee un nombre, una descripción, un esquema y las líneas que hayas escrito sobre el orden en que se usan. Con eso decide en cada turno si llama y qué hace con lo que vuelve.
Se arregla en dos sitios: la definición, que el modelo ve siempre, y el prompt, el único donde caben la ruta entre llamadas y la regla de recuperación. Aquí no hay ningún campo de proveedor: el formato cambia, el contenido no.
La descripción es el prompt que se lee en cada decisión
El esquema declara la forma de la llamada; la descripción declara para qué existe. Al elegir, el modelo lee el nombre y la descripción; el esquema lo consulta para rellenar los argumentos. Una descripción que repite el nombre no aporta nada: «envía un correo» no dice cuándo.
Sirve cuando contesta cuatro preguntas en orden: qué hace, cuándo se usa, cuándo no, y qué devuelve. La primera va con el objeto y sus límites: «los pedidos abiertos del cliente, del más reciente al más antiguo, máximo veinte» dice más que «consulta pedidos». La segunda y la tercera nombran a la herramienta vecina, y eso evita la llamada equivocada.
Y una herramienta, una responsabilidad. search_orders y refund_order son dos; un manage_order que busca, reembolsa o cancela según un argumento son tres con gabardina. Cuando dos se solapan —get_customer frente a lookup_user— el modelo duda en cada llamada: fusiónalas o escribe la diferencia en las dos. Si el prompt es el único sitio donde viven las herramientas, la definición va completa; si ya existen, basta un contrato corto, y nunca puede contradecirlas.
text
search_orders
Qué hace: pedidos abiertos del cliente, del más reciente al más antiguo,
máximo 20. Cada uno con order_id, placed_at, status y total con moneda.
Cuándo usarla: historial de pedidos y estado de un pedido.
Cuándo no: seguimiento de envío, que tiene track_shipment.
Devuelve: lista de pedidos, o [] si no hay ninguno abierto.
El nombre lleva el verbo y el objeto
verbo_objeto, en minúsculas, sin gracia: create_invoice, fetch_weather, send_email. El nombre dice qué se hace y sobre qué, y es la primera pista de selección.
Lo que rompe un nombre es lo vago y lo que se parece a otro. process, handle y manage no dicen qué se hace; pg_query nombra la implementación; y dos nombres casi iguales para comportamientos distintos —delete_file y remove_file— obligan a leer la descripción entera, que es justo lo que el nombre ahorra. Si dos herramientas se distinguen por alcance, que se distingan por el mismo eje: list_tickets y update_ticket, no tickets y modify.
text
verbo_objeto en minúsculas: search_orders, refund_order, send_email.
Prohibidos process, handle, manage y cualquier nombre que necesite una
frase para explicarse.
Cada parámetro dice tipo, unidad y qué pasa si falta
Un parámetro sin unidad es una llamada mal hecha esperando: timeout invita a segundos donde la API espera milisegundos, y amount a euros donde el sistema cuenta céntimos. Cada uno lleva tipo, significado y restricción: obligatorio u opcional, valores admitidos, valor por defecto, unidad y formato.
Unos pocos parámetros bien nombrados valen más que un bloque libre: un payload en texto donde cabe cualquier cosa esconde la forma y le deja al modelo la adivinación que hacías tú. Si un parámetro admite varias formas, lístalas: «period: day, week o month» se acierta; «period: el periodo» no. Donde el formato importa, pon el ejemplo, y valida en el servidor: el esquema no es una regla de negocio.
text
refund_order
order_id string, obligatorio. El order_id que devolvió search_orders.
amount_cents integer, obligatorio, en céntimos. Sin decimales.
reason string, obligatorio. Uno de: damaged, not_received, wrong_item.
restock boolean, opcional, por defecto true.
Lo que devuelve decide la llamada siguiente
Lo que devuelve una herramienta es la entrada de la decisión siguiente, así que se diseña con el mismo cuidado que la entrada de un prompt. Devuelve los campos que el modelo necesita, con nombres estables, unidades pegadas al número y nulos explícitos: un campo que a veces falta se lee como cero. Y devuelve poco: un volcado sin límite entierra la señal y encarece los turnos siguientes.
Los errores son la otra mitad del contrato. Cada uno lleva código, mensaje y si la llamada cambió algo, y hay tres clases, cada una con su reacción: lo que el modelo puede corregir, lo que no puede —permiso denegado, recurso inexistente— y lo que no es un error —una lista vacía—. Sin esa distinción todo es «error» y el modelo no sabe si reintentar o cambiar de enfoque.
La regla de recuperación va en el prompt, no en la herramienta, con una prohibición: nunca dejes que conteste como si la llamada hubiera funcionado.
text
Errores, tres clases y una respuesta para cada una:
- corregible (argumento inválido): corrige el argumento y reintenta una vez.
- transitorio (timeout, límite de peticiones): espera y reintenta una vez.
- permanente (sin permiso, no existe): no reintentes; explica qué falta.
Una lista vacía no es un error: es «no hay resultados».
Nunca respondas como si la llamada hubiera funcionado.
Antes de encender una herramienta, mira si lee o escribe
Cada herramienta lleva etiqueta de efecto: solo lectura, escritura idempotente o efecto no idempotente. Esa etiqueta decide si un reintento es gratis. Una lectura se repite sin coste; una escritura que fija un valor se repite sin daño; un envío, un cobro o una publicación, no.
Para el tercer tipo hacen falta una clave de idempotencia o una comprobación previa, y una confirmación de intención antes de actuar. La descripción dice qué es irreversible y cuál es la alternativa segura: el modelo lo necesita al elegir, no después. Y una herramienta que lee y escribe a la vez se razona y se reintenta peor: sepárala.
text
Efecto, en la descripción de cada herramienta:
- solo lectura: reintenta libremente.
- escritura idempotente: repetir el mismo valor no cambia nada.
- efecto no idempotente: enviar, cobrar, publicar. Requiere idempotency_key
y confirmación de intención.
Antes de llamar a una de efecto no idempotente, di en una línea qué vas a
hacer y sobre qué. Si falta el identificador o el importe, no la llames.
Cuántas herramientas a la vez
Cada herramienta añadida hace más difícil elegir. El conjunto se queda en lo que el trabajo necesita —a menudo menos de diez activas— y lo que crece se agrupa por oficio, diciendo qué grupo aplica a qué petición. Si el catálogo es grande, la salida no es exponerlo entero: es una herramienta de descubrimiento que devuelva las tres o cuatro que aplican.
Para una necesidad simple el problema es selección; para una compuesta, encadenamiento: ordenar las llamadas y pasar el resultado de una a la siguiente. Cuando la ruta se conoce, se escribe; cuando no, la regla de parada. En paralelo, solo lecturas independientes.
text
Ruta conocida:
1. search_orders con el cliente.
2. Para cada pedido abierto, get_shipment con su order_id.
3. Si no hay pedidos abiertos, para: no busques envíos.
Regla de parada: sigue hasta poder responder, no hasta gastar llamadas.
Nunca lances dos llamadas en paralelo si la segunda necesita un dato de la
primera.
Cuando llama a la herramienta equivocada
La primera tentación es añadir otra herramienta, y casi siempre es la peor: agranda el catálogo y no toca la causa. Antes de añadir nada, lee lo que el modelo lee.
Cuatro comprobaciones, en orden. ¿La primera línea de la descripción, sola, distingue esta herramienta de su vecina? ¿Hay dos que se solapan sin decir en qué? ¿El nombre lleva la acción o hay que leer el párrafo? ¿Pedía una cadena y expusiste los pasos sueltos, sin orden?
Si acierta la herramienta y falla los argumentos, el problema es el parámetro: falta la unidad, el valor admitido o el ejemplo. Si llama a escribir cuando bastaba leer, la etiqueta de efecto no está en el prompt. Y la petición sin herramienta se escribe como una salida, no como una herramienta más.
text
Si ninguna herramienta sirve para la petición, no la fuerces con la más
parecida: di qué hace falta y para.
Si dos podrían servir, elige la de solo lectura y explica en una línea por
qué no usaste la otra.
Cuando se comporta mal
| Síntoma | Causa | Arreglo |
|---|---|---|
| Llama siempre a la misma, toque o no | su descripción no dice cuándo se usa | escribe «cuándo usarla» nombrando a la otra |
| Rellena un parámetro con la unidad equivocada | no declara unidad | añade unidad, ejemplo y rango |
| Reintenta un cobro tres veces | el efecto no está etiquetado | etiqueta no idempotente y exige clave |
| Responde «hecho» sin que la llamada funcionara | el prompt no lo prohíbe | añade la prohibición y el código de error |
Qué cambió y cuándo
- 1 de noviembre de 2026. Publicación de esta guía. No cita fuentes porque no depende de ningún proveedor: todo lo que hay aquí se escribe en el nombre, la descripción, el esquema y el prompt.
Resumen
Cuando el prompt define o dirige herramientas, la definición de cada una es la parte del prompt que se ejecuta en cada decisión: el modelo elige por el nombre y la descripción, no por el esquema. Lo que decide si la usa bien es lo que devuelve, si escribir es reversible y cuántas tiene delante a la vez.
Artículos relacionados
¿Listo para crear mejores prompts?
SystemPrompt Master aplica el método de estas guías para escribir el prompt del modelo que elijas y guarda cada versión.