Después de crear tu función de herramienta, el siguiente paso es escribir un esquema JSON para describirla. Este esquema le indica a Claude qué argumentos espera tu función y cómo usarla correctamente. Aunque la configuración pueda parecer intimidante al principio, en realidad es sencilla una vez que entiendes el proceso.
Entendiendo JSON Schema
JSON Schema no es algo inventado solo para herramientas de IA: existe desde hace años como una forma estándar de validar datos. El esquema tiene dos partes principales: el nombre y la descripción en la parte superior (que ayudan a Claude a entender cuándo usar la herramienta), y el esquema real que describe los argumentos de la función.
La sección superior contiene el nombre y la descripción de la herramienta, lo que ayuda a Claude a entender cuándo usarla. La sección inferior es el esquema real que describe en detalle los argumentos de tu función.
Creando un JSON Schema: Paso a Paso
Esta es la forma más sencilla de crear un esquema JSON para cualquier función:
Paso 1: Escribe un Diccionario con Datos de Ejemplo
Toma tu función y crea un diccionario con todos los argumentos de palabra clave con datos de ejemplo. Por ejemplo, si tienes una función como esta:
def process_data(ids, profile, primary_id, value):
passCrea un diccionario con valores de ejemplo:
Paso 2: Convierte a JSON
Convierte tu diccionario de Python al formato JSON adecuado. La principal diferencia es cambiar el True de Python al true de JSON.
Paso 3: Usa un Convertidor en Línea
Busca "JSON to JSON Schema converter" y usa una de las muchas herramientas gratuitas en línea. Pega tus datos JSON y deja que genere el esquema automáticamente.
La herramienta analizará tus datos de ejemplo y creará una estructura de esquema adecuada. Elimina cualquier declaración $schema del resultado: no las necesitas.
Paso 4: Agrega Descripciones
El paso más importante es agregar descripciones detalladas a cada propiedad. Estas descripciones ayudan a Claude a entender exactamente qué hace cada argumento y cómo usarlo.
Escribiendo Buenas Descripciones
Al escribir descripciones para tus herramientas y propiedades, sigue estas mejores prácticas:
- Explica qué hace la herramienta, cuándo usarla y qué devuelve
- Apunta a 3-4 oraciones en la descripción de tu herramienta
- Proporciona descripciones súper detalladas para cada propiedad
- Si te quedas atascado, pega tu función en Claude y pídele que escriba las descripciones por ti
Aquí hay un ejemplo de un esquema de herramienta bien descrito:
Observa cómo la descripción explica claramente qué hace la herramienta del clima, cuándo usarla, qué datos devuelve, y proporciona ejemplos específicos de formatos de ubicación válidos.
Poniéndolo Todo Junto
Tu esquema JSON final debería verse algo así, con el toolSpec conteniendo el nombre, la descripción, y el inputSchema con las especificaciones detalladas de los argumentos:
El esquema actúa como un contrato entre tu código y Claude, asegurando que cuando Claude decida usar tu herramienta, sepa exactamente qué información proporcionar y en qué formato. Esta comunicación clara es lo que hace que el uso de herramientas sea confiable y efectivo.