Tool use: cómo Claude llama funciones externas

Claude no puede decirte la hora exacta, el clima de hoy ni qué hay en tu base de datos ahora mismo. Aquí aprenderás qué es tool use en Claude y cómo darle acceso a datos reales con Python, algo clave para desarrolladores que quieren conectar la IA con el mundo exterior.

El problema es simple: Claude vive dentro de la conversación. No tiene reloj, no tiene Internet abierto y no puede asomarse a tu sistema. Solo conoce lo que le escribes y lo que aprendió cuando lo entrenaron. Sabe razonar, pero le faltan manos para actuar.

Por qué Claude no puede darte datos en tiempo real

Cuando le preguntas la hora, el clima o algo de tu base de datos, Claude se queda corto porque no tiene forma de salir de la conversación. Su conocimiento está congelado en el momento del entrenamiento.

Ahí entra tool use, la funcionalidad que le da a Claude manos y no solo voz. La idea central es que tú le declaras de antemano qué herramientas tiene disponibles: consultar el clima, buscar en una base de datos, lo que necesites.

¿Qué es tool use en Claude? Es la capacidad de darle a Claude herramientas externas que tú defines. Claude decide cuándo usarlas y te pide ejecutarlas, pero nunca toca tu código: quien ejecuta siempre eres tú.

El flujo funciona en pasos claros:

• Le preguntas algo que necesita una herramienta.
• Claude no inventa la respuesta, te devuelve una petición del tipo llama a la función del clima en Buenos Aires.
• Tu código ejecuta esa función y consigue el dato real.
• Le devuelves el resultado a Claude.
• Recién ahí Claude arma la respuesta final con información de verdad.

Lo importante aquí es la separación de responsabilidades: Claude decide qué herramienta hace falta y cuándo, pero la ejecución siempre corre por tu cuenta.

Cómo se define una herramienta en el código

El primer paso es preparar los imports junto con la librería de Anthropic y definir el modelo, tal como se venía haciendo en clases anteriores. Lo nuevo aparece al crear la estructura de la herramienta.

Guardamos un objeto con tres campos clave [1:52]:

• name: le llamamos get_weather.
• description: "Obtiene el clima actual para una ciudad".
• input_schema: un tipo objeto con la propiedad city de tipo string, cuya descripción es "ciudad a consultar".

La ciudad se marca como campo requerido. Es decir, la herramienta siempre debe recibir una ciudad para funcionar.

python get_weather_tool = { "name": "get_weather", "description": "Obtiene el clima actual para una ciudad", "input_schema": { "type": "object", "properties": { "city": { "type": "string", "description": "ciudad a consultar" } }, "required": ["city"] } }

La función main mantiene lo de siempre: el API key con su manejo de error, el client de Anthropic y la llamada al endpoint messages.create con el modelo, un máximo de tokens y los mensajes [3:04]. En este caso, el rol usuario pregunta "¿Cómo está el clima en Bogotá?".

Cómo le decimos a Claude qué herramientas tiene

La clave está en agregar el parámetro tools dentro de la llamada. Es un array que, en este ejemplo, contiene una sola herramienta: la que definimos arriba [4:22].

Dentro de la respuesta revisamos el tipo de bloque:

• Si es un bloque de tipo tool_use, imprimimos que Claude quiere usar esa herramienta con el input correspondiente.
• Si es un bloque de tipo texto, imprimimos ese texto.

Al ejecutar con Python, el proceso se detiene justo donde detecta que necesita una herramienta [4:58]. La respuesta es reveladora: "Voy a consultar el clima de Bogotá ahora mismo. Claude quiere utilizar get_weather con el input city Bogotá".

Eso significa que antes de irse a buscar en su entrenamiento, Claude ve la herramienta disponible y pide autorización para usarla.

Cómo completar el ciclo para obtener una respuesta real

Detenerse en la petición no basta. Queremos que Claude reciba el dato y genere una respuesta final. Para eso, generamos información hardcodeada que simula el resultado de la herramienta [6:05].

Primero ajustamos los imports: sumamos annotations desde __future__, json, el módulo del sistema operativo y Callable desde collections.abc, que permite marcar el tipo de una función ejecutable [6:24].

Luego definimos dos cosas:

• Una función que recibe una city como string y retorna la ciudad con una temperatura fija en 18 grados y condición "lluvia ligera" [7:00].
• Una constante available_tools que conecta el nombre de la herramienta con la función real que la ejecuta.

¿Por qué se usan datos hardcodeados en este ejemplo? Para efectos de la clase, la función devuelve valores fijos (18 grados, lluvia ligera) en lugar de consultar una API real. Así se prueba el ciclo completo sin depender de servicios externos.

El paso decisivo es actualizar los mensajes. No basta con el response: hay que agregar al historial lo que viene del asistente y el resultado del uso de la herramienta [8:03]. Así unimos la petición de Claude con el dato obtenido y el flujo continúa hasta la respuesta final.

Un error común: dónde ubicar la variable message

Para que la prueba tenga sentido, cambiamos la pregunta a "¿necesito usar paraguas hoy en Bogotá?" [8:45]. Con los datos de 18 grados y lluvia ligera, Claude debe tomar una decisión.

Al ejecutar aparece un error: message no está definido [9:07]. La causa es la ubicación: message estaba dentro de la llamada de response. La solución es mover su definición hacia arriba, antes de la ejecución, y dentro de la llamada al endpoint usar messages con ese valor.

Así el message.append se lee directamente sin importar que se use dentro de la función. Guardamos y ejecutamos de nuevo.

Ahora sí llega la respuesta [9:41]: "Sí, te recomiendo llevar paraguas hoy. Temperatura dieciocho grados, condición lluvia ligera. Bogotá tiene un clima muy variable, es mejor llevarlo por precaución".

Y aquí viene lo interesante: los datos del clima salen de la herramienta, pero el comentario final sobre el clima variable lo agrega Claude desde su entrenamiento. Primero se basa en la herramienta y su dato local, luego complementa con lo que ya sabe.

Qué diferencia hay entre herramientas propias y las de la API

En este ejercicio tú armaste todo: escribiste la función, la corriste en tu máquina y le devolviste el resultado a Claude. Pero no todas las herramientas funcionan así.

Algunas ya viven dentro de la API de Claude, listas para usar, y se ejecutan sin que tú escribas la función detrás. La búsqueda web es una de ellas. Ahí el ciclo cambia, porque la herramienta no la ejecutas tú, sino el propio Claude.

¿Ya probaste conectar tu primera herramienta con Claude? Cuéntame en los comentarios qué función te gustaría darle acceso a datos reales.