dful.
Dful Dark
Tema
Explorar notas
En esta página

Uso de herramientas

Qué contiene una tool call, cómo se valida y ejecuta, y qué resultado necesita el modelo para continuar.
Actualizado 6 oct 2026

Una tool expone una operación que el modelo puede solicitar. La definición suele incluir un nombre, una descripción y un schema de parámetros; el modelo genera la call, mientras el harness o la aplicación decide si puede ejecutarse y realiza la operación.

Cómo se ejecuta una tool call El modelo solicita una tool con argumentos. El harness valida y ejecuta la operación y devuelve el resultado al modelo. Harness / runtime Petición del modelo Tool + argumentos Validar Argumentos + permiso Ejecutar la operación Fuera del modelo Fichero, shell o API El entorno objetivo Resultado Información para el turno siguiente devolver resultado Cómo se ejecuta una tool call El modelo solicita una tool con argumentos. El harness valida y ejecuta la operación y devuelve el resultado al modelo. Petición del modelo Tool + argumentos Harness / runtime Validar Argumentos + permiso Ejecutar la operación Fuera del modelo Fichero, shell o API El entorno objetivo Resultado Información para el turno siguiente devolver resultado
Figura 1. El modelo solicita una operación, el harness la valida y ejecuta, y el resultado vuelve al siguiente turno.

Un ejemplo mínimo de una tool de lectura podría ser:

{
  "name": "read_file",
  "description": "Read a range of lines from a text file",
  "parameters": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "start_line": { "type": "integer" }
    },
    "required": ["path"]
  }
}

La descripción ayuda al modelo a elegir la tool y el schema acota la forma de los argumentos. Si la operación borra datos, envía un mensaje o exige una precondición, esa información debería quedar clara antes de llegar a la ejecución.

Tool call y ejecución

Si el modelo necesita inspeccionar src/app.ts, puede generar una call a read_file con ese path. La aplicación valida los argumentos, comprueba los permisos aplicables, lee el fichero y devuelve las líneas solicitadas. El modelo utiliza ese resultado para decidir si necesita otra lectura, un cambio o una respuesta final.

El schema resuelve la forma de los argumentos, no toda la validez de la operación. Un path puede cumplir el tipo string y seguir apuntando fuera del scope; una call bien formada también puede requerir aprobación.

Resultados

El resultado debería contener lo necesario para la siguiente decisión y conservar el detalle que pueda cambiarla. Según la tool, puede ser texto de shell, JSON con campos estables o una referencia a un artefacto mayor.

El tamaño también importa porque la salida puede entrar en la siguiente inferencia. Para leer un fichero suele ser más manejable devolver rangos que enviar siempre el contenido completo. Con un log grande, el runtime puede guardar el original y entregar al modelo solo las coincidencias o la región relevante.

Los errores forman parte del mismo contrato. Si un fichero no existe, devolver ese fallo permite corregir el path. Una respuesta que parezca éxito pero oculte el error empeora la decisión siguiente.

Efectos secundarios y reintentos

read_file suele poder repetirse sin cambiar el entorno. send_message puede duplicar un envío después de un timeout, y delete_file puede encontrar un estado distinto al repetir la llamada.

Para operaciones con efectos conviene saber si la primera ejecución llegó a completarse antes de reintentar. Permisos, aprobación, IDs de operación o mecanismos de idempotencia pueden formar parte de esa comprobación según la tool y el sistema externo.

Referencias