Diseña los parámetros de un Power

Un Power con la URL correcta pero parámetros mal diseñados falla de la forma más difícil de diagnosticar: no revienta, simplemente entrega datos incompletos o mal interpretados. Arko permite hasta diez parámetros por Power, cada uno con nombre, descripción, valor y si es obligatorio. Esas cuatro piezas son, en la práctica, todo lo que el modelo tiene para entender qué necesitas de él.

El nombre es para tu sistema, la descripción es para el modelo

El nombre del parámetro identifica el campo en la petición que recibe tu endpoint; la descripción es la instrucción que lee el agente para saber qué poner ahí. Son audiencias distintas y conviene tratarlas así: nombra el parámetro como lo esperaría tu API, pero describe qué es y de dónde sacarlo con el mismo cuidado con el que le explicarías el campo a una persona nueva en el equipo.

Marca lo obligatorio, no lo asumas

Un parámetro requerido bloquea la llamada hasta que el agente lo tiene; uno opcional se envía vacío si no hay dato. La diferencia importa: si un campo es indispensable para que tu endpoint funcione, márcalo como obligatorio para que el agente pregunte antes de actuar, en vez de disparar una petición incompleta que tu backend va a rechazar de todos modos.

• Describe el formato esperado cuando no es obvio: una fecha, un código, un identificador con un patrón concreto.
• Da un ejemplo dentro de la descripción cuando el campo se presta a ambigüedad.
• Evita nombres genéricos como valor o dato: el agente —y tú, seis meses después— agradecen la precisión.

Diez parámetros es un límite, no un objetivo

Que Arko permita hasta diez no significa que cada Power deba acercarse a esa cifra. Cada parámetro es una decisión adicional que el agente tiene que tomar correctamente antes de poder actuar; un Power con tres parámetros bien descritos falla menos que uno con nueve donde alguno queda ambiguo. Si tu endpoint necesita más de lo razonable, es una señal de que quizás conviene partirlo en dos Powers más específicos.

Valores por defecto, con cuidado

El campo de valor de un parámetro puede llevar un dato fijo que no depende de la conversación —una moneda, una región, un identificador de tu cuenta—. Úsalo para lo que de verdad es constante; si lo usas para lo que debería variar según el usuario, terminas con un Power que siempre actúa igual, sin importar lo que realmente se conversó.