Referencia de herramientas

Esta página es una referencia de las herramientas que Anthropic proporciona y de las propiedades opcionales que puedes establecer en cualquier definición de herramienta. Para una introducción conceptual al "tool use" (uso de herramientas), consulta Uso de herramientas con Claude. Para obtener orientación sobre cómo implementar el uso de herramientas en tu aplicación, consulta Definir herramientas.

Herramientas proporcionadas por Anthropic

Anthropic proporciona dos tipos de herramientas: herramientas de servidor ("server tools") que se ejecutan en la infraestructura de Anthropic, y herramientas de cliente ("client tools") en las que Anthropic define el esquema pero tu aplicación se encarga de la ejecución. Ambos tipos aparecen en el array tools de tu solicitud junto con cualquier herramienta definida por el usuario.

Para conocer la compatibilidad con modelos, consulta la página de cada herramienta. Los modelos compatibles varían según la herramienta y la versión de la herramienta.

Versionado de herramientas

La mayoría de las herramientas proporcionadas por Anthropic llevan un sufijo _YYYYMMDD en la cadena type. Se publica una nueva versión cuando cambia el comportamiento, el esquema o la compatibilidad con modelos de la herramienta. Las versiones anteriores siguen disponibles para que las integraciones existentes continúen funcionando.

Cuando una herramienta tiene varias versiones activas, la relación entre ellas varía:

• Según la capacidad: web_search_20260209 y web_fetch_20260209 añaden filtrado dinámico de contenido respecto a sus predecesoras; web_fetch_20260309 añade una opción para omitir la caché; web_search_20260318 y web_fetch_20260318 añaden control de inclusión en la respuesta. code_execution_20260120 añade la llamada programática de herramientas desde dentro del sandbox; code_execution_20260521 indica el límite de tiempo por celda en la descripción de la herramienta. En cada caso, tanto la versión nueva como la anterior están vigentes; cuál uses depende de si necesitas la nueva capacidad.
• Según el modelo: text_editor_20250728 es para Claude 4 y modelos posteriores, y text_editor_20250124 es para modelos anteriores. La versión que uses depende del modelo al que te dirijas.
• Variante, no versión: tool_search_tool_regex_20251119 y tool_search_tool_bm25_20251119 son dos algoritmos de búsqueda publicados juntos. Ninguno reemplaza al otro.
• Heredada: code_execution_20250522 solo admite Python. code_execution_20250825 añade Bash y operaciones con archivos.
• Sucesora: computer_toolset_20260801 es la sucesora estable de las versiones beta computer_20251124 y computer_20250124, que siguen disponibles en los modelos indicados para ellas en Versiones anteriores de la herramienta. browser_toolset_20260801 es la primera versión de la herramienta de uso de navegador. Ambas son conjuntos de herramientas de cliente.

El tipo mcp_toolset no está versionado por fecha; en su lugar, el versionado se lleva en el encabezado anthropic-beta.

Conjuntos de herramientas de cliente

La herramienta de uso de computadora y la herramienta de uso de navegador son "client toolsets" (conjuntos de herramientas de cliente) definidos por Anthropic: una entrada en tools declara un conjunto fijo de herramientas miembro cuyos nombres, descripciones y esquemas de entrada define Anthropic, y tu aplicación ejecuta cada llamada. La entrada no lleva name, porque el type con fecha fija los nombres de los miembros. configs, cache_control y allowed_callers (que solo acepta ["direct"]) son opcionales.

Los conjuntos de herramientas de cliente son herramientas de la Messages API. Actualmente no están disponibles como herramientas de agente en Claude Managed Agents, que proporciona su propio conjunto de herramientas de agente integrado, conjuntos de herramientas MCP y herramientas personalizadas.

{
  "type": "browser_toolset_20260801",
  "configs": {
    "javascript_exec": { "enabled": true }
  },
  "cache_control": { "type": "ephemeral" }
}

configs ajusta miembros individuales:

• Las claves son nombres de miembros, y cada valor acepta solo enabled y defer_loading.
• Un miembro que omitas conserva sus valores predeterminados. Un valor ausente, {} y un valor predeterminado reiterado son equivalentes.
• Se rechaza un nombre de miembro desconocido o cualquier otro campo en el valor de un miembro, al igual que un configs que deshabilite todos los miembros (en su lugar, omite la entrada).
• Un miembro deshabilitado se elimina de las herramientas que Claude ve. Si Claude aun así lo nombra, devuelve un tool_result de error.

Establece defer_loading por miembro, nunca en la entrada, y asigna a todos los miembros habilitados el mismo valor: con la búsqueda de herramientas, el conjunto de herramientas se carga y se expande como una sola definición. Cuando todos los miembros habilitados se difieren, solo una herramienta de búsqueda de herramientas que no esté diferida puede mostrar el conjunto de herramientas, así que declara una en la misma solicitud. No pongas cache_control en una entrada de conjunto de herramientas cuyos miembros se difieran; establece el punto de interrupción en una herramienta no diferida, porque las definiciones diferidas no forman parte del prefijo almacenado en caché.

cache_control va solo en la entrada; para saber dónde queda el punto de interrupción, incluidos los marcadores dentro de una acción por lotes, consulta Uso de herramientas con almacenamiento en caché de prompts.

Maneja las llamadas a herramientas miembro. Claude llama a un miembro con un bloque tool_use cuyo name es el nombre del miembro y cuyo toolset_name es computer o browser; input contiene los parámetros de ese miembro y ningún campo action. Despacha según el par toolset_name y name, porque una herramienta personalizada puede compartir el nombre de un miembro y los dos conjuntos de herramientas comparten nombres como screenshot. Solo los resultados de miembros repiten toolset_name. Varias llamadas a miembros en un mismo turno forman una acción por lotes que ejecutas en orden (uso de computadora, uso de navegador). Los nuevos miembros llegan solo con un nuevo type con fecha.

No admitido en entradas de conjuntos de herramientas. La API rechaza cada uno de estos con un invalid_request_error:

• strict: true o input_examples.
• defer_loading en la entrada, o miembros habilitados cuyos valores de defer_loading difieran (establécelo por miembro en configs, todos con el mismo valor).
• Un llamador de ejecución de código en allowed_callers (sin llamada programática de herramientas).
• El encabezado beta heredado fine-grained-tool-streaming-2025-05-14. Cuando usas streaming, el input de cada miembro llega como un único input_json_delta completo.
• Un tool_choice de tipo tool que nombre el conjunto de herramientas o un miembro (usa auto, any o none).
• Dos entradas del mismo conjunto de herramientas, u otra herramienta que lleve el nombre de ese conjunto de herramientas: una herramienta llamada computer junto con computer_toolset_20260801, o una herramienta llamada browser junto con browser_toolset_20260801. Los dos conjuntos de herramientas pueden declararse juntos.

Propiedades de definición de herramientas

Cada herramienta del array tools, incluidas las herramientas definidas por el usuario, acepta propiedades opcionales que controlan cómo se carga la herramienta, quién puede llamarla y cómo se validan sus entradas. Estas propiedades se combinan: puedes establecer defer_loading, cache_control y strict en la misma herramienta.

Valores de allowed_callers

allowed_callers es un array que acepta cualquier combinación de:

Tanto "code_execution_20260120" como "code_execution_20260521" se aceptan en allowed_callers y son intercambiables: una solicitud que use cualquiera de las dos versiones de la herramienta de ejecución de código satisface a las herramientas que listen cualquiera de los dos llamadores. Los bloques de respuesta siempre etiquetan al llamador como code_execution_20260120, independientemente de la versión que haya declarado la solicitud.

Omitir "direct" del array (por ejemplo, "allowed_callers": ["code_execution_20260120"]) orienta a Claude a llamar a la herramienta solo desde dentro de la ejecución de código. El bloque tool_use de la respuesta incluye un campo caller que identifica qué llamador llamó a la herramienta. Consulta Llamada programática de herramientas para el tratamiento completo, incluida la forma de la respuesta caller y el comportamiento ante errores.

defer_loading y almacenamiento en caché de prompts

Las herramientas con defer_loading: true se eliminan de la sección de herramientas renderizada antes de que se calcule la clave de caché. No aparecen en absoluto en el prefijo de la indicación del sistema. Cuando la búsqueda de herramientas descubre una herramienta diferida y devuelve un tool_reference para ella, la definición completa de la herramienta se expande en línea en ese punto del cuerpo de la conversación, no en el prefijo.

Esto significa que defer_loading: true preserva tu caché de prompts. Puedes añadir herramientas diferidas a una solicitud sin invalidar una entrada de caché existente, y la caché sigue siendo válida tanto en el turno en que se descubre la herramienta como en el turno en que se llama.

Para aprender a combinar defer_loading con puntos de interrupción de cache_control, consulta la guía de almacenamiento en caché de prompts de la herramienta de búsqueda de herramientas.