Todo lo anterior ha tratado de lo que el modelo dice. Una herramienta es lo que le permite hacer algo: comprobar si un nombre está cogido, enviar un correo, crear un registro. En cuanto añades una, el modelo deja de ser un generador de texto pegado a tu producto y pasa a ser un llamante dentro de él.
Lo que significa que una herramienta es un endpoint de API cuyo consumidor no puede leer tu documentación, nunca verá tu página de error y decide por su cuenta si te llama siquiera. Todo lo peculiar de diseñar herramientas se deriva de ahí.
La descripción es la API
Tu guía de integración, tu documentación de parámetros, tu nota de «cuándo usar esto»: todo se colapsa en una sola cadena.
#[Description('Check if a site URL is available before creating a site.
Always call this before CreateSiteTool to avoid using taken URLs.')]
class CheckUrlAvailabilityTool extends Tool
Corta, porque la herramienta es simple, y aun así hace dos trabajos: dice qué hace la herramienta y dice cuándo llamarla en relación con otra.
Para una herramienta más sutil la descripción carga con mucho más, incluidas cosas que jamás pondrías en documentación para una persona:
#[Description('Offer the user a short list of ready-made answers to pick from
instead of making them compose one. The client renders these as tappable cards,
so this is how you ask for services, opening hours, or any other detail with a
small set of likely answers. YOU generate the options from what you already know
about the business — "Japanese restaurant" should yield Dine-in, Takeout,
Delivery, Catering, not a generic list. Use multi=true when several answers can
be true at once (services), multi=false when only one can (hours). The user\'s
pick comes back as their next message, so wait for it before moving on. Do not
also list the options in your own text; the cards already show them.')]
Cuatro trabajos distintos en un párrafo:
- Qué hace — ofrece respuestas ya preparadas.
- Qué verá el usuario — tarjetas pulsables, algo que el modelo no puede saber y que cambia cómo debe escribir.
- Cómo usarla bien — genera opciones específicas de este negocio, con un ejemplo resuelto. Sin eso, obtienes Opción A / Opción B / Otra.
- Qué no hacer después — no repitas las opciones en texto, y espera la respuesta.
Esa última categoría es la que se olvida. La descripción de una herramienta no es sólo un contrato: es guía de comportamiento para el turno posterior a la llamada. Si tu interfaz renderiza algo, dile al modelo que no lo duplique en prosa, porque lo hará.