El resultado también es un prompt

Vuelve a mirar ese campo message. No es para el usuario, y no son datos. Es una instrucción, entregada al modelo a mitad de turno, en el momento en que es más relevante.

La versión grande aparece en la herramienta que crea algo:

'next_action' => 'IMMEDIATELY present the provisioning details to the user:
share everything in site_details, the expected_url, and the account_url.
Tell them provisioning is underway and typically takes less than 60 seconds.
Then ask if they would like you to check the status. Only call
GetSiteStatusTool when the user asks.',

Existe por un comportamiento real: tras arrancar un trabajo largo, el modelo consultaba la herramienta de estado en bucle y narraba cada comprobación —sigue cociéndose, vuelvo a mirar— lo cual era ruido y contradecía la tarjeta de progreso en pantalla cada vez que ambas discrepaban.

El arreglo no estuvo en el prompt de sistema. Estuvo aquí, en el resultado, donde el modelo lo lee justo en el momento en que decide qué hacer a continuación. Las instrucciones aterrizan mejor cerca de la decisión que gobiernan.

Ordena el conjunto de herramientas

Las herramientas individuales se describen a sí mismas. La relación entre ellas va a nivel de servidor:

#[Instructions('Recommended flow: 1) CollectSiteInformationTool gathers all
business details, 2) SendVerificationEmailTool sends a code to the email,
3) VerifyEmailTool confirms it, 4) CheckUrlAvailabilityTool checks the URL,
5) CreateSiteTool creates the site. CRITICAL: sites are LIVE AND PUBLIC upon
creation. If the user abandons before step 5, their info is already captured.')]
class AgentServer extends Server
{
    protected array $tools = [
        CollectSiteInformationTool::class,
        SendVerificationEmailTool::class,
        VerifyEmailTool::class,
        CheckUrlAvailabilityTool::class,
        SuggestPalettesTool::class,
        SuggestOptionsTool::class,
        CreateSiteTool::class,
        GetSiteStatusTool::class,
        // Note: ResetLeadTool intentionally excluded from public tools.
        // It's internal-only for debugging/development.
    ];
}

Dos cosas que llevarse.

El flujo se enuncia una vez, arriba. Repetir «llama a esta después de aquella» en ocho descripciones garantiza que se contradirán en menos de un mes.

No toda herramienta pertenece al conjunto. ResetLeadTool existe, funciona y deliberadamente no está registrada. Una herramienta que reinicia el estado de un contacto es valiosísima en desarrollo y es, para un modelo al que hayan convencido de usarla, una forma de borrar una verificación. Registrar es una decisión, no una consecuencia de que el fichero exista.

Ese último punto merece capítulo propio, y lo tiene: el 11.

Lo que sostiene este capítulo

• Una herramienta es un endpoint cuyo llamante no puede leer tu documentación. La descripción es toda la guía de integración.
• Describe cuándo llamarla y qué no hacer después, no sólo qué hace. Si tu interfaz renderiza el resultado, dilo, o el modelo lo repetirá en prosa.
• Esquema y validación son ambos obligatorios. El esquema es cómo pides; el validador es cómo insistes.
• Las descripciones de campo son superficie de prompt. «Ordénalas de más a menos probable» no es comprobable por máquina y mejora la salida igualmente.
• Acepta escalares planos, monta la estructura en el servidor. El JSON anidado es un impuesto de fiabilidad.
• Usa reglas condicionales para que una herramienta sirva a dos formas en lugar de partirse en dos.
• Quita en la frontera los campos que no aplican, para que un campo despistado ocasional nunca se convierta en un rechazo aguas abajo del que el modelo tenga que recuperarse.
• Normaliza los campos opcionales una vez, en la herramienta, en lugar de defenderte de su ausencia en cada consumidor.
• Nombra las claves de resultado por la herramienta que las produjo, para que la segunda herramienta con opciones no choque con la primera.
• El resultado de una herramienta es un prompt entregado a mitad de turno. Las instrucciones aterrizan mejor cerca de la decisión que gobiernan.
• Ordena el conjunto a nivel de servidor, y trata el registro como una decisión: algunas herramientas deben existir y no ofrecerse nunca.