Uso estricto de herramientas: deja de rechazar tus propias llamadas

La demostración en este video fue grabada en septiembre de 2026. Se ejecutó en Claude Haiku 4.5 (claude-haiku-4-5). Los resultados pueden diferir en modelos más nuevos.

Claude normalmente sigue el input_schema de una herramienta, pero nada lo hace cumplir por defecto. Así que a veces tu backend rechaza una llamada a herramienta que Claude hizo, porque la entrada de la llamada tiene uno de estos:

• La cadena "2" en lugar del entero 2
• Un campo requerido faltante

El uso estricto de herramientas soluciona esto. Una sola bandera, strict: true, hace que la entrada que escribe Claude coincida con tu esquema.

En Meridian, un asistente usa la herramienta queue_stamp_request para poner en cola conjuntos de planos para el sello de un ingeniero con licencia. El validador de Meridian es el código que verifica cada llamada a herramienta. Con strict desactivado, rechaza 79 de 100 solicitudes. Con strict activado y el esquema generado a partir del validador, no rechaza ninguna.

Cómo funciona el uso estricto de herramientas

Con strict: true, la API primero compila tu JSON Schema en una gramática. Una gramática es un conjunto de reglas que indica qué tokens pueden venir a continuación en cada punto de la entrada. Luego, cada vez que Claude elige el siguiente token de la llamada a herramienta, solo puede elegir un token que la gramática permita. Esto se llama muestreo restringido por gramática.



Esta es la definición de herramienta de Meridian, reducida. Strict necesita dos de sus líneas, la bandera y una configuración que la bandera requiere.

{
  "name": "queue_stamp_request",
  "description": "Queues a drawing set for a professional engineer's stamp.",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "drawing_set_id": {"type": "string"},
      "revision": {"type": "integer"}
    },
    "required": ["drawing_set_id", "revision"],
    "additionalProperties": false
  }
}

• "strict": true es la bandera. Se encuentra en el nivel superior, junto a name, description, y input_schema, fuera del esquema.
• "additionalProperties": false es la configuración. Significa que la entrada no puede llevar un campo que el esquema no nombre, y strict lo requiere en cada objeto.

Construye el esquema a partir de tu validador

El uso estricto de herramientas hace que la entrada que escribe Claude coincida con tu esquema, así que el esquema debe decir lo mismo que dice tu validador. Cuando escribes el esquema a mano, los dos se distancian. Una llamada a herramienta puede entonces coincidir con el esquema y aun así ser rechazada. En Meridian, un esquema escrito a mano hacía que el número de licencia fuera una cadena simple sin patrón. Así que "PE 46196" pasó el esquema y falló el validador, que requiere PE- y cinco dígitos.

Escribe las reglas una sola vez, en tu validador, y genera el esquema a partir de él. En Python, el validador suele ser una clase de Pydantic. En TypeScript, suele escribirse con Zod.

A continuación está la clase Pydantic de Meridian, StampRequest, con el código que la usa, y luego el esquema que devuelve StampRequest.model_json_schema(). Cada # ... representa código no mostrado, y el esquema muestra solo el número de licencia.

class StampRequest(BaseModel):
    model_config = {"extra": "forbid"}
    # ...
    pe_license_number: str | None = Field(pattern=r"^PE-\d{5}$")
    # ...
stamp_tool = {
    # ...
    "input_schema": StampRequest.model_json_schema(),
    "strict": True,
}
stamp_request = StampRequest.model_validate(call.input)

{
  "additionalProperties": false,
  "properties": {
    "pe_license_number": {
      "anyOf": [
        {"pattern": "^PE-\\d{5}$", "type": "string"},
        {"type": "null"}
      ],
      "title": "Pe License Number"
    }
  }
}

• "extra": "forbid" se convierte en "additionalProperties": false, la configuración que strict requiere.
• str | None se convierte en anyOf, así que el número de licencia es una cadena con ese pattern, o null.
• model_validate() verifica call.input, la entrada que escribió Claude, contra la misma clase.

Compara las ejecuciones con strict desactivado y activado

La prueba de Meridian envía 100 solicitudes de sello en lenguaje simple a Claude Haiku 4.5 con la herramienta queue_stamp_request, y StampRequest valida cada llamada a herramienta. Las mismas 100 solicitudes se ejecutan dos veces, primero con un esquema escrito a mano y strict desactivado, y luego con el esquema generado y strict activado.

Reproduce ambas ejecuciones a continuación.

El pattern del esquema indica qué formato está permitido, y strict hace que Claude lo cumpla.

Strict controla la forma de la entrada, pero no puede proporcionar un dato que la solicitud nunca dio. De las 100 solicitudes, 28 nunca mencionan una licencia. El esquema generado permite null para el número de licencia, y las 28 regresaron como null.

Límites del uso estricto de herramientas

Seis cosas que debes saber, a partir de octubre de 2026:

1. Mantén fuera la información de salud protegida (PHI). Los esquemas compilados no obtienen las mismas protecciones de PHI que los prompts y las respuestas, así que deja la PHI fuera de los nombres de propiedades, los valores de enum, los valores de const, y las expresiones de pattern.
2. Los límites no son compatibles. Una solicitud cuyo esquema use minimum, maximum, minLength, o maxLength devuelve un error 400. Verifica los límites en una función validadora, como @field_validator de Pydantic, y exprésalos en la descripción del campo.
3. Los límites se suman entre herramientas. Una solicitud puede contener como máximo 20 herramientas estrictas. Entre esas herramientas, puede contener como máximo 24 parámetros opcionales. También puede contener como máximo 16 parámetros que usen anyOf o un arreglo de tipos, que es lo que genera un campo anulable como str | None.
4. La entrada aún puede no coincidir con el esquema. Esto ocurre después de un rechazo, cuando una respuesta se corta en max_tokens, o cuando una cadena de enum o const regresa con una capitalización diferente.
5. Algunos modelos rechazan una llamada a herramienta forzada. Configurar tool_choice en any o tool fuerza una llamada a herramienta. Eso devuelve un error 400 en Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, y Claude Mythos 5.1. En esos modelos, deja tool_choice en auto, su valor predeterminado.
6. La llamada a herramientas programática no puede usar herramientas estrictas. En la llamada a herramientas programática, Claude escribe código que llama a tus herramientas. La lección 8 lo cubre.

Puntos clave

• strict: true hace que la entrada de la herramienta coincida con tu esquema, excepto después de un rechazo o una respuesta cortada, o cuando una cadena de enum o const cambia de mayúsculas/minúsculas.
• Genera el esquema a partir de tu validador, como una clase de Pydantic.
• Mantén los límites fuera del esquema, y cuenta las herramientas, los parámetros opcionales, y los parámetros anulables en toda la solicitud.