Claude Tool Use: Cómo Doy Capacidades Reales a Mis Agentes de IA

Tabla de contenidos

Actualizado julio 2026.

TL;DR: Claude tool use permite que tu agente tome acciones — no solo generar texto. Defines herramientas como esquemas JSON, Claude decide cuándo llamarlas, y tu código ejecuta la acción en el mundo real. El bucle tiene tres pasos: enviar mensaje → recibir bloque tool_use → ejecutar y devolver resultado. He implementado esto en más de 15 agentes de producción en Cloudflare Workers. El fallo casi nunca es la IA — son los resultados ambiguos que regresan de las herramientas.

[Lectura del operador] Dirijo más de 30 agentes de IA en producción entre una marca de consultoría y Pickleland, una instalación de pádel pickleball en Pflugerville, TX. Aproximadamente la mitad usa tool use — la función de la API de Claude que permite al modelo llamar funciones que tu código define. Este es el patrón al que he llegado tras implementar e iterar en producción.

Por qué el tool use cambia lo que un agente puede hacer

Sin herramientas, un agente solo puede generar texto. Eso es útil para resumir, redactar y clasificar — pero no es lo que la mayoría de las automatizaciones empresariales realmente necesitan. Las automatizaciones necesitan buscar información, escribir en bases de datos, llamar a APIs, enviar mensajes.

El tool use es la forma en que le das a Claude ese acceso. Defines un conjunto de herramientas como esquemas JSON. Claude lee los esquemas, decide qué herramienta llamar y con qué argumentos, y devuelve un bloque de contenido tool_use estructurado. Tu código ejecuta la función real. Claude obtiene el resultado y decide qué hacer a continuación — incluido llamar a otra herramienta o producir una respuesta de texto final.

La clave: Claude decide cuándo y si llamar a una herramienta. Tú defines las capacidades. El modelo razona sobre cuándo usarlas.

Cómo funciona el flujo de la API

El bucle de tool use tiene tres pasos. Puedes ejecutar este bucle una o varias veces dependiendo de cuántas llamadas de herramienta haga el modelo.

Paso 1: Envía tu mensaje con las herramientas definidas

const response = await anthropic.messages.create({
  model: "claude-haiku-4-5-20251001",
  max_tokens: 1024,
  tools: [
    {
      name: "check_court_availability",
      description:
        "Check if a court is available at a given date, time, and duration",
      input_schema: {
        type: "object",
        properties: {
          date: {
            type: "string",
            description: "Date in YYYY-MM-DD format",
          },
          time: {
            type: "string",
            description: "Start time in HH:MM format (24h)",
          },
          duration_minutes: {
            type: "number",
            description: "Duration of the booking in minutes",
          },
        },
        required: ["date", "time", "duration_minutes"],
      },
    },
  ],
  messages: [
    {
      role: "user",
      content: "Is a court available tomorrow at 2pm for 90 minutes?",
    },
  ],
});

Paso 2: Comprueba si Claude quiere llamar a una herramienta

if (response.stop_reason === "tool_use") {
  const toolUseBlock = response.content.find(
    (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
  );

  if (!toolUseBlock) throw new Error("Expected tool_use block");

  // Run your actual function
  const toolResult = await checkCourtAvailability(
    toolUseBlock.input as CourtAvailabilityInput
  );

  // Step 3: Return the result to Claude
  const finalResponse = await anthropic.messages.create({
    model: "claude-haiku-4-5-20251001",
    max_tokens: 1024,
    tools: [
      /* same tools as before */
    ],
    messages: [
      {
        role: "user",
        content: "Is a court available tomorrow at 2pm for 90 minutes?",
      },
      { role: "assistant", content: response.content },
      {
        role: "user",
        content: [
          {
            type: "tool_result",
            tool_use_id: toolUseBlock.id,
            content: JSON.stringify(toolResult),
          },
        ],
      },
    ],
  });

  // finalResponse.content now has the text answer
}

Ese es el patrón completo. Tres interacciones con la API por llamada de herramienta: definir herramientas → recibir bloque tool_use → devolver resultado.

Ejemplo real: el verificador de disponibilidad de Pickleland

Pickleland es una instalación de pickleball. Recibimos consultas de reserva en Facebook Messenger, en comentarios y a través de un chatbot. La pregunta casi siempre es alguna variación de “¿están abiertos el sábado a las 3pm?” o “¿puedo reservar una cancha para mi grupo de 8 personas?”

El agente verificador de disponibilidad usa tool use para consultar el sistema de reservas real en tiempo real, en lugar de dar una respuesta enlatada.

Aquí está el agente completo — simplificado pero fiel a producción:

// workers/availability-checker.ts
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const AVAILABILITY_TOOLS: Anthropic.Tool[] = [
  {
    name: "check_availability",
    description:
      "Check court availability for a date, time, and group size. Returns available courts and their prices.",
    input_schema: {
      type: "object",
      properties: {
        date: { type: "string", description: "YYYY-MM-DD" },
        start_time: { type: "string", description: "HH:MM (24h)" },
        duration_minutes: { type: "number" },
        players: { type: "number", description: "Number of players" },
      },
      required: ["date", "start_time", "duration_minutes"],
    },
  },
  {
    name: "get_pricing",
    description:
      "Get current pricing for court rentals and open play sessions",
    input_schema: {
      type: "object",
      properties: {
        session_type: {
          type: "string",
          enum: ["court_rental", "open_play", "clinics"],
        },
      },
      required: ["session_type"],
    },
  },
];

export async function handleInquiry(
  userMessage: string,
  env: Env
): Promise<string> {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  // Agentic loop — keep going until stop_reason is "end_turn"
  while (true) {
    const response = await anthropic.messages.create({
      model: "claude-haiku-4-5-20251001",
      max_tokens: 512,
      system:
        "You are the booking assistant for Pickleland, a pickleball facility in Pflugerville, TX. " +
        "Use the tools to look up real availability and pricing. Never make up availability or prices. " +
        "If the customer wants to book, direct them to pickleland.com/book.",
      tools: AVAILABILITY_TOOLS,
      messages,
    });

    // Push the assistant's response into message history
    messages.push({ role: "assistant", content: response.content });

    if (response.stop_reason === "end_turn") {
      const textBlock = response.content.find(
        (b): b is Anthropic.TextBlock => b.type === "text"
      );
      return (
        textBlock?.text ??
        "I wasn't able to answer that — please call us directly."
      );
    }

    if (response.stop_reason === "tool_use") {
      // Process ALL tool calls in this response (Claude can request multiple at once)
      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of response.content) {
        if (block.type !== "tool_use") continue;

        let result: unknown;

        switch (block.name) {
          case "check_availability":
            result = await checkAvailability(
              block.input as AvailabilityInput,
              env
            );
            break;
          case "get_pricing":
            result = await getPricing(block.input as PricingInput, env);
            break;
          default:
            result = { error: `Unknown tool: ${block.name}` };
        }

        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: JSON.stringify(result),
        });
      }

      // Return all tool results in a single user message
      messages.push({ role: "user", content: toolResults });
    }
  }
}

Dos cosas a destacar aquí.

El bucle agéntico. Sigo hasta que stop_reason === "end_turn". Claude puede llamar a check_availability, decidir que también necesita precios, llamar a get_pricing, y luego producir la respuesta final — son tres llamadas a la API por un único mensaje del usuario. El bucle maneja esto sin lógica especial.

Múltiples llamadas de herramienta por turno. Claude puede devolver múltiples bloques tool_use en una sola respuesta. Proceso todos ellos y devuelvo todos los resultados en un único mensaje user. Si los procesas uno a la vez y los devuelves individualmente, rompes el flujo de la conversación y desperdicias tokens.

Ejemplo real: el agente de investigación de leads

Mi marca de consultoría usa un agente de investigación que enriquece los leads entrantes antes de hablar con ellos. Cuando alguien rellena el formulario de contacto, el agente investiga su empresa y extrae lo que necesito saber antes de la llamada.

Las definiciones de herramientas para este incluyen una herramienta de escritura — y aquí es donde el patrón se vuelve interesante:

const RESEARCH_TOOLS: Anthropic.Tool[] = [
  {
    name: "search_company",
    description: "Search for information about a company",
    input_schema: {
      type: "object",
      properties: {
        company_name: { type: "string" },
        website: { type: "string", description: "Company website if known" },
      },
      required: ["company_name"],
    },
  },
  {
    name: "save_research",
    description:
      "Save the completed research summary to Airtable. Call this when all research is complete.",
    input_schema: {
      type: "object",
      properties: {
        company_summary: { type: "string" },
        estimated_size: {
          type: "string",
          enum: ["1-10", "11-50", "51-200", "200+"],
        },
        likely_use_case: { type: "string" },
        priority: { type: "string", enum: ["high", "medium", "low"] },
        notes: { type: "string" },
      },
      required: [
        "company_summary",
        "estimated_size",
        "likely_use_case",
        "priority",
      ],
    },
  },
];

save_research es lo que llamo una herramienta de escritura — su propósito no es obtener información, sino confirmar el resultado de Claude en una base de datos en forma estructurada. Uso este patrón en lugar de intentar parsear JSON de una respuesta de texto. Claude sabe cuándo ha terminado la investigación y llama a save_research con campos correctamente tipados. No escribo ningún parser.

Esta es la aplicación más limpia del tool use: define una herramienta de “acción final” con el esquema exacto que quieres, y Claude entrega la salida estructurada a través de la llamada a la herramienta. Sin parseo de texto, sin regex, sin validación JSONSchema de salida en texto libre.

Una herramienta vs. muchas

El instinto al empezar con tool use es construir una herramienta gigante que lo haga todo. Resiste esto. Las herramientas pequeñas y enfocadas son mejores por tres razones:

1. Claude razona mejor sobre herramientas pequeñas. Una herramienta llamada get_court_status que devuelve disponibilidad es más fácil de razonar para el modelo que una herramienta llamada manage_facility que toma un parámetro mode y ramifica internamente.

2. Las herramientas pequeñas son más fáciles de probar. Cada herramienta es una función TypeScript que puedes testear unitariamente de forma independiente del LLM. Deberías hacerlo — los errores en las herramientas son difíciles de depurar dentro de una conversación activa.

3. Claude puede paralelizar herramientas pequeñas. Si dos herramientas no dependen entre sí, Claude puede llamarlas en la misma respuesta y tú las procesas en paralelo. Esto solo funciona si las herramientas son genuinamente independientes.

La excepción: herramientas que necesitan acceso a mucho estado interno compartido. Si la función necesita 10 variables de la misma fuente de datos, una herramienta con un esquema más rico supera a 10 herramientas que cada una accede a la base de datos por separado.

Mi regla general: empieza con una herramienta por capacidad distinta. Fusiona herramientas solo cuando veas que Claude las llama juntas en cada solicitud.

Implicaciones de coste

El tool use agrega tokens. Cada definición de herramienta va al contexto del prompt del sistema. Cada bloque tool_use y tool_result consume tokens en el historial de la conversación. Para un bucle agéntico multi-turno, esto se acumula rápidamente.

Para el verificador de disponibilidad de Pickleland, una conversación típica ejecuta 3–4 llamadas a la API en total (mensaje inicial + 1–2 llamadas de herramienta + respuesta final), cada una procesando 600–900 tokens. A los precios de Haiku, esto cuesta menos de $0,001 por consulta. Como explico en el post sobre el cálculo de costes de agentes de IA, Haiku maneja las tareas de llamada a herramientas bien definidas de forma fiable y es 10× más barato que Sonnet para el mismo volumen de tokens.

El agente de investigación de leads funciona con Sonnet porque las decisiones de juicio — priorizar un lead, estimar el ajuste — requieren más capacidad de razonamiento de la que Haiku ofrece de forma fiable en inputs abiertos. La matemática sigue funcionando porque se ejecuta con poca frecuencia (algunas veces por semana, no miles por día). La elección del modelo sigue la complejidad de la tarea, no la preferencia personal.

El fallo que nadie menciona

El fallo más común que veo en el tool use en producción no es que Claude llame a la herramienta equivocada. Es la herramienta que devuelve algo que Claude no puede razonar claramente.

Si tu herramienta devuelve un objeto de base de datos en crudo con 40 campos, Claude se confunde sobre qué campos importan. Si tu herramienta lanza una excepción (que aparece como un crash del Worker en lugar de un resultado de herramienta), el bucle se rompe silenciosamente. Si tu herramienta devuelve null cuando significa “sin resultados”, Claude no sabe si reintentar o rendirse.

Tres reglas para los resultados de herramientas:

Devuelve resultados concisos y explícitos. { available: true, courts: ["Court 3", "Court 5"], price_per_hour: 20 } — no la fila completa de la base de datos.

Captura errores dentro de la función de la herramienta y devuélvelos como resultados estructurados. { error: "booking system timeout", retry: true } — no una excepción lanzada que crashea el Worker.

Haz que “sin resultados” sea explícito. { available: false, next_available: "2026-07-23T14:00:00Z" } — no null ni un array vacío sin contexto.

Claude razona mucho mejor sobre señales claras que sobre valores de retorno ambiguos. Cada hora que he pasado depurando tool use en producción ha sido por resultados poco claros, no por razonamiento del modelo.

La conclusión del operador

El tool use es la función que convierte a Claude de un generador de texto en un operador. Define herramientas enfocadas con esquemas de entrada claros. Gestiona todos los bloques tool_use en una única respuesta al modelo. Ejecuta el bucle agéntico hasta que stop_reason === "end_turn". Devuelve resultados limpios y concisos desde tus funciones de herramienta — no objetos de datos en crudo, no excepciones lanzadas, no nulos ambiguos.

El modelo maneja el razonamiento. Tu código maneja las acciones en el mundo real. Mantén esos dos trabajos claramente separados y la arquitectura seguirá siendo mantenible incluso a medida que añadas herramientas.

Si estás construyendo tu primer agente con tool use, empieza con el patrón del verificador de disponibilidad anterior — una herramienta, un propósito, un bucle agéntico. Impleméntalo. Luego añade la segunda herramienta.

Relacionado: El stack de agentes que uso para ejecutar 30+ agentes en producción · Haiku vs Sonnet: el cálculo de costes para tareas de agentes · Agentes disparados por eventos vs programados: qué patrón usar

¿Construyendo un agente con tool use y te has atascado? Contáctame — diseño y construyo arquitecturas de agentes de producción para equipos de operadores.

Preguntas frecuentes

¿Funciona el tool use de Claude con todos los modelos?

Sí — el tool use es compatible con todos los modelos actuales de Claude. Claude Haiku maneja herramientas bien definidas con esquemas claros de forma fiable y es la opción más económica para tipos de tareas de alto volumen. Sonnet maneja mejor las decisiones de llamada a herramientas más ambiguas o abiertas. Empieza con Haiku; sube si la calidad de la salida no es suficiente.

¿Cuál es la diferencia entre el tool use de Claude y el function calling de OpenAI?

Mecánicamente idénticos. OpenAI acuñó “function calling”; Anthropic lo llama “tool use”. En ambos casos: defines esquemas JSON, el modelo devuelve llamadas estructuradas, tu código ejecuta la función. La forma de la API difiere, pero el concepto es el mismo.

¿Puede Claude llamar a múltiples herramientas en una sola respuesta?

Sí. Claude puede devolver múltiples bloques tool_use en una sola respuesta assistant. Procésalos todos y devuelve todos los resultados en un único mensaje user. Consulta el patrón del bucle agéntico en el ejemplo de Pickleland — el bucle for sobre response.content lo maneja correctamente.

¿Cuántas herramientas debo definir por agente?

Me mantengo por debajo de 8–10 herramientas por agente. Más allá de eso, he visto que Claude ocasionalmente elige la herramienta equivocada en el primer intento, lo que desperdicia tokens en un bucle de corrección. Si necesitas más de 10 capacidades, divide el agente en múltiples agentes con conjuntos de herramientas especializados en lugar de construir un agente que lo sepa todo.

¿Debo usar el tool use para obtener salida estructurada?

Sí — el patrón de herramienta de escritura save_research es más limpio que pedirle a Claude que devuelva JSON en un bloque de texto y luego parsearlo. Define una herramienta de “acción final” con el esquema exacto que quieres. Claude la llamará con campos correctamente tipados cuando haya terminado. No necesitas un parser.