flowchart LR
A[Leer / buscar / recuperar] --> B[Calcular / transformar]
B --> C[Escribir]
C --> D[Ejecutar]
Qué es una tool
Qué significa exponer una capacidad operacional a una aplicación basada en modelos y cómo distinguir leer, buscar, recuperar, calcular, transformar, escribir y ejecutar.
Ya podemos decir que una tool no es una metodología.
Pero todavía necesitamos responder la pregunta más básica:
¿Qué es exactamente una tool dentro de una aplicación basada en modelos?
La palabra puede resultar engañosa porque en lenguaje cotidiano una herramienta es cualquier cosa que nos ayuda a trabajar. Un procesador de textos es una herramienta. Un modelo también puede llamarse herramienta. Una checklist puede ser una herramienta metodológica.
Aquí utilizaremos el término de manera más estrecha.
Idea central
En el marco pedagógico de este handbook, una tool es una capacidad operacional delimitada que la aplicación puede invocar para obtener información, ejecutar una computación o producir una acción.
La tool extiende lo que el sistema puede hacer más allá de la generación ordinaria del modelo.
Una tool es una operación, no todo el sistema
Imaginemos un DMS que permite cientos de acciones.
Una aplicación basada en modelos no necesita recibir acceso indistinto a todo el DMS.
Podemos exponer una capacidad concreta:
buscar_documentos(proveedor, tipo_documento)Esa operación puede apoyarse internamente en muchas piezas técnicas: autenticación, API, consultas, permisos, tratamiento de errores.
Desde el punto de vista de la aplicación, sin embargo, aparece como una capacidad acotada.
Esto es importante porque permite diseñar una interfaz operacional con una finalidad reconocible.
El contrato operacional mínimo
Una herramienta útil debería poder describirse, al menos conceptualmente, mediante cinco preguntas.
| Elemento | Pregunta |
|---|---|
| Nombre | ¿Cómo se identifica? |
| Finalidad | ¿Para qué sirve? |
| Entrada | ¿Qué necesita recibir? |
| Salida | ¿Qué devuelve? |
| Efecto | ¿Sólo observa o modifica algo? |
Por ejemplo:
Nombre:
buscar_documentos
Finalidad:
Localizar contratos y anexos asociados a un proveedor.
Entradas:
- proveedor
- tipo_documento
- rango_fecha
Salida:
Lista de documentos encontrados.
Efecto:
Sólo lectura.No necesitamos saber programar para comprender esta estructura.
Y ya permite hacer preguntas muy útiles.
Leer
La operación más sencilla consiste en leer un objeto identificado.
Por ejemplo:
obtener_documento(id_documento)Si el sistema recibe:
id_documento = "DOC-1842"la tool podría devolver el contenido o una representación del archivo correspondiente.
En trabajo jurídico, leer puede significar obtener:
- un contrato;
- un anexo;
- una política;
- un correo;
- una ficha de proveedor;
- un registro;
- una resolución.
La operación parece pasiva porque no modifica nada.
Pero eso no significa que sea neutral desde el punto de vista de seguridad o confidencialidad.
Leer información a la que el usuario no debería acceder sigue siendo un problema.
Por eso conviene separar desde el comienzo:
TIPO DE OPERACIÓN
lectura
ALCANCE AUTORIZADO
qué puede leer esa identidadBuscar
A veces no conocemos todavía qué objeto concreto necesitamos.
Entonces debemos buscar.
Imaginemos:
buscar_documentos(
proveedor = "ACME",
tipo_documento = "anexo_seguridad"
)La salida podría ser:
DOC-011 | Anexo_Seguridad_ACME_2024.pdf | reemplazado
DOC-019 | Anexo_Seguridad_ACME_2026_draft.pdf | borrador
DOC-021 | Anexo_Seguridad_ACME_2026.pdf | firmadoLa tool ha resuelto una pregunta de localización.
Todavía no ha resuelto cuál documento debe utilizarse.
Eso puede requerir criterios adicionales.
Esta diferencia es importante:
una herramienta puede funcionar correctamente y devolver resultados que todavía necesitan interpretación.
Recuperar
Buscar y recuperar suelen aparecer juntos, pero conviene distinguirlos.
Buscar localiza candidatos.
Recuperar obtiene el objeto o contenido seleccionado.
Podemos representar el patrón así:
BUSCAR
↓
identificar candidatos
↓
SELECCIONAR
↓
RECUPERAR
↓
incorporar contenido a la tareaEn la sección anterior estudiamos RAG y recuperación de información. No necesitamos volver aquí a embeddings, chunking o bases vectoriales.
El delta conceptual es diferente.
Ahora observamos la recuperación como capacidad operacional invocable.
Una aplicación puede disponer de una tool que recupere un recurso cuando lo necesita.
Calcular
No todas las operaciones externas consisten en leer datos.
También podemos utilizar una tool para calcular.
Supongamos que debemos comparar:
cap contractual = 800.000
exposición estimada = 2.400.000Una función podría recibir:
calcular_ratio(
numerador = 800000,
denominador = 2400000
)y devolver:
0.333333La herramienta ha ejecutado el cálculo.
Pero no ha resuelto todavía qué significa jurídicamente.
La interpretación puede ser:
El cap equivale aproximadamente a un tercio de la exposición estimada.Y la evaluación puede ser:
Según la política interna, esa diferencia requiere escalamiento.Conviene mantener separadas las tres capas:
CÁLCULO
resultado numérico
INTERPRETACIÓN
descripción de qué representa
EVALUACIÓN
aplicación de un criterio jurídico o de riesgoTransformar
Una tool también puede transformar información.
Por ejemplo:
convertir_docx_a_pdf()
extraer_texto_pdf()
comparar_versiones()
validar_json()
normalizar_fechas()
redimensionar_imagen()Muchas de estas operaciones no requieren inteligencia artificial.
Y ésa es precisamente una enseñanza útil.
Una aplicación basada en modelos no debería utilizar generación probabilística para todo simplemente porque dispone de un LLM.
Si una transformación puede realizarse de forma determinista, verificable y económica mediante software convencional, puede ser mejor delegarla a una función especializada.
Huyen presenta esta arquitectura híbrida de forma natural: el modelo puede apoyarse en herramientas para ampliar sus capacidades en vez de intentar resolver mediante generación cada parte de la tarea.
Escribir
Hasta ahora las operaciones podían limitarse a obtener o transformar información.
Con escribir cambia la situación.
Una tool podría hacer:
crear_borrador_revision(
proveedor,
estado,
resumen
)La operación genera un objeto persistente en otro sistema.
Por ejemplo:
proveedor = ACME
estado = REQUIERE_NEGOCIACION
resumen = "Desviación material en responsabilidad"El efecto ya no desaparece cuando cerramos la conversación.
Puede quedar almacenado.
Puede ser leído por otras personas.
Puede desencadenar otras operaciones.
Por eso el paso desde lectura hacia escritura no es solamente una diferencia técnica.
Cambia el perfil de riesgo.
Ejecutar
Finalmente aparecen operaciones que producen efectos más directos o potencialmente relevantes.
Por ejemplo:
enviar_correo(...)
crear_evento(...)
aprobar_solicitud(...)
cancelar_proceso(...)
modificar_permisos(...)Agruparemos estas capacidades bajo la idea general de ejecutar una acción.
No significa que todas tengan el mismo impacto.
Enviar una notificación interna puede ser relativamente reversible.
Modificar permisos de acceso sobre un repositorio confidencial puede ser crítico.
Aprobar una contratación puede representar una decisión institucional.
La categoría nos sirve para detectar que el sistema ya puede producir efectos sobre el entorno.
Leer, escribir y ejecutar no son equivalentes
Podemos ordenar las operaciones inicialmente mediante su efecto.
El diagrama no pretende afirmar que el riesgo siempre crece linealmente de izquierda a derecha.
Leer una base con millones de datos sensibles puede ser más grave que modificar una etiqueta inocua.
Pero existe una intuición correcta:
cuanto mayor sea el efecto externo, la sensibilidad de la información o la dificultad de revertir una acción, más atención requiere el control.
Tool no significa necesariamente “Internet”
Otra confusión frecuente consiste en imaginar que una tool siempre conecta el modelo con un servicio remoto.
No es necesario.
Podemos tener una tool local:
calcular_hash(archivo)Otra que ejecuta código en un entorno aislado:
ejecutar_python(codigo)Otra que consulta una base interna:
consultar_registro_proveedores(id)Y otra que utiliza un servicio externo:
buscar_web(consulta)Lo que las agrupa no es dónde están.
Lo que las agrupa es que exponen una operación a la aplicación.
Tool no significa necesariamente “acción autónoma”
También debemos evitar otra inferencia.
Una tool puede existir aunque el modelo nunca decida usarla.
El usuario podría seleccionar manualmente:
[Calcular exposición]La aplicación podría ejecutar la función automáticamente en una etapa fija.
O un workflow podría exigir la operación siempre que aparezca determinada condición.
La herramienta es la capacidad.
La lógica que decide cuándo utilizarla puede estar en otra parte.
Describir bien una tool
Aunque estudiaremos tool calling en una página propia, conviene introducir aquí una idea mínima.
Para que una herramienta pueda utilizarse correctamente, su descripción debe hacer visible su finalidad.
Comparemos:
Mala descripción:
Llama endpoint /v3/documents con payload JSON.con:
Buena descripción:
Busca contratos y anexos asociados al proveedor dentro de los repositorios autorizados.La primera describe detalles técnicos.
La segunda comunica qué problema resuelve.
Google destaca que los esquemas de entrada y salida y las descripciones de herramientas cumplen dos funciones: documentan la capacidad para que el modelo pueda utilizarla adecuadamente y permiten validación durante la ejecución.
Entradas y salidas mínimas
Podemos mirar una tool como una pequeña transformación operacional.
ENTRADA
proveedor = ACME
↓
TOOL
buscar_documentos
↓
SALIDA
lista de documentosUna herramienta bien delimitada hace observables las entradas y salidas.
Eso facilita responder preguntas como:
¿qué dato recibió?
¿qué operación hizo?
¿qué devolvió?
¿produjo un efecto?Estas preguntas serán importantes más adelante para trazabilidad y auditoría.
Un caso completo
Supongamos que nuestra revisión contractual necesita resolver cuatro problemas.
Problema 1: falta el anexo
buscar_documentos(
proveedor = "ACME",
tipo = "anexo_seguridad"
)Resultado:
3 candidatosProblema 2: necesitamos el firmado
obtener_documento("DOC-021")Resultado:
contenido del anexo firmadoProblema 3: necesitamos un cálculo
calcular_ratio(800000, 2400000)Resultado:
0.333333Problema 4: queremos dejar preparado el hallazgo
crear_borrador_revision(
proveedor = "ACME",
estado = "REQUIERE_NEGOCIACION"
)Resultado:
BORRADOR-774 creadoLas cuatro herramientas son operacionales.
Pero no hacen lo mismo.
Las dos primeras obtienen información.
La tercera computa.
La cuarta modifica estado.
Esa diferencia conduce directamente al siguiente nodo.
Qué puede salir mal
El hecho de que una tool sea acotada no significa que sea infalible.
Puede fallar porque:
- recibe argumentos incorrectos;
- el recurso no existe;
- devuelve varios candidatos ambiguos;
- el sistema externo no está disponible;
- los permisos son insuficientes;
- la operación se ejecuta dos veces;
- la salida se interpreta incorrectamente.
Lo importante es que la tool hace el fallo más localizable que una función monolítica.
Podemos preguntar:
¿la herramienta hizo aquello que su contrato operacional decía que debía hacer?
Por qué importa jurídicamente
Cuando evaluamos una aplicación conectada, no basta saber que “tiene herramientas”.
Necesitamos preguntar:
¿Qué tools existen?
¿Qué información reciben?
¿Qué devuelven?
¿Qué sistemas consultan?
¿Cuáles sólo leen?
¿Cuáles escriben?
¿Cuáles producen efectos externos?
¿Qué permisos necesita cada una?Estas preguntas ayudan a traducir arquitectura técnica a cuestiones de confidencialidad, control, trazabilidad y responsabilidad.
Una tool tiene una frontera de responsabilidad
Cuando diseñamos una herramienta conviene definir no sólo qué hace, sino también qué no hace.
Por ejemplo:
buscar_documentospuede responsabilizarse de:
recibir criterios de búsqueda
consultar un repositorio autorizado
devolver candidatos y metadatospero no necesariamente de:
decidir cuál documento es jurídicamente vigente
interpretar una cláusula
aprobar una contrataciónEsta frontera es útil porque evita que una operación aparentemente simple acumule decisiones heterogéneas.
Podemos expresar la idea mediante tres niveles:
OPERACIÓN
qué hace la tool
RESULTADO
qué devuelve
INTERPRETACIÓN
qué significa ese resultado para la tareaLa herramienta controla principalmente el primer nivel.
Entradas mínimas y entradas excesivas
Una tool también puede diseñarse con demasiados parámetros.
Comparemos:
buscar_contrato(proveedor)con una función genérica que exige:
sistema
tabla
consulta
filtro
campo
operador
orden
límiteLa segunda puede ser más flexible, pero también más difícil de utilizar correctamente y de gobernar.
Para sistemas basados en modelos suele ser útil exponer la mínima cantidad de libertad necesaria para la tarea.
Esto no significa eliminar flexibilidad arbitrariamente. Significa diseñar capacidades alrededor de finalidades reconocibles.
Una tool estrecha puede reducir:
- errores de argumentos;
- ambigüedad de selección;
- superficie de permisos;
- dificultad de evaluación.
La salida también debe diseñarse
No basta con definir qué recibe la tool.
También debemos decidir qué devuelve.
Una búsqueda podría retornar cien campos técnicos del DMS. Pero el modelo quizás sólo necesita:
id
nombre
estado
fechaReducir la salida a información pertinente puede disminuir ruido y exposición innecesaria de datos.
Por eso una tool se diseña en dos direcciones:
ENTRADA
qué necesita realmente para operar
SALIDA
qué necesita realmente devolverEsta idea reaparecerá cuando estudiemos tool calling: descripciones y schemas claros ayudan tanto a seleccionar la herramienta como a comprobar que la operación se realizó en una forma esperada.
Qué debes recordar
Una tool es una capacidad operacional delimitada.
Puede:
LEER
obtener un objeto
BUSCAR
localizar candidatos
RECUPERAR
traer contenido seleccionado
CALCULAR
realizar una operación determinista
TRANSFORMAR
convertir o procesar información
ESCRIBIR
crear o modificar estado
EJECUTAR
producir un efecto sobre el entornoEstas operaciones pertenecen a una misma familia general de capacidades, pero no tienen la misma finalidad ni el mismo perfil de riesgo.
El problema que todavía queda abierto
Ya sabemos qué operaciones puede exponer una tool.
Ahora necesitamos una forma más sencilla de ordenar ese universo.
¿Podemos agrupar herramientas según el tipo de capacidad que añaden al sistema?
Las clases utilizan tres grandes familias: información, computación y acción.
El siguiente nodo desarrolla esa clasificación y muestra por qué resulta útil para pensar diseño, riesgo y control.