Inicio / La API de Claude para quienes construyen

Las herramientas, Claude propone, el código dispone

Una herramienta se declara mediante un esquema llamado input_schema; Claude nunca la ejecuta él mismo, devuelve una solicitud de uso que el código ejecuta antes de devolver el resultado para que la conversación continúe.

Claude nunca ejecuta una herramienta él mismo. Devuelve una solicitud de uso, el código del desarrollador la ejecuta realmente, y luego devuelve el resultado para que la conversación continúe. Este ciclo se apoya en un único contrato: el esquema declarado por el campo input_schema.

La declaración de una herramienta

Una herramienta se declara mediante tres campos de primer nivel: name, description e input_schema, este último describiendo la forma esperada de los argumentos. Un cuarto campo, strict, se coloca junto a los tres primeros y no sobre la elección de herramienta: puesto a true, garantiza que la llamada producida por Claude corresponde exactamente al esquema declarado, a condición de que ese esquema también lleve additionalProperties a false junto a required, la forma que la documentación oficial aplica en todos sus ejemplos.

// Déclaration d'un outil, avec validation stricte du schéma
{
  "name": "verifier_stock",
  "description": "Renvoie la quantité disponible pour une référence produit.",
  "input_schema": {
    "type": "object",
    "properties": {
      "reference": { "type": "string" }
    },
    "required": ["reference"],
    "additionalProperties": false
  },
  "strict": true
}

El ciclo completo, de la solicitud al resultado

Cuando Claude decide usar una herramienta, devuelve un stop_reason de valor tool_use, acompañado de uno o varios bloques tool_use que llevan los argumentos elegidos. El código ejecuta entonces la llamada real descrita por ese bloque, y luego devuelve el resultado en un bloque tool_result, colocado dentro de un mensaje de rol user. Cuando se solicitan varias herramientas en el mismo turno, lo que ocurre por defecto puesto que las llamadas paralelas están activas, todos sus bloques tool_result vuelven juntos en ese único mensaje.

// Demande d'usage renvoyée par Claude
{
  "stop_reason": "tool_use",
  "content": [
    { "type": "tool_use", "id": "toolu_01", "name": "verifier_stock",
      "input": { "reference": "REF-042" } }
  ]
}

// Résultat renvoyé par le code dans le tour suivant
{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 unités disponibles" }
  ]
}

El campo tool_choice controla qué herramienta puede elegir Claude: auto por defecto deja que Claude decida, any fuerza el uso de una herramienta sin imponer su nombre, tool impone una herramienta precisa, y none le impide usar ninguna. Elegir none sin declarar ninguna herramienta no añade ningún token de sistema adicional a la petición. El bloque tool_result devuelto aquí sigue la misma estructura de mensaje que la petición base, con un array messages que sigue alternando los roles.