Referência de ferramentas

Esta página é uma referência para as ferramentas que a Anthropic fornece e as propriedades opcionais que você pode definir em qualquer definição de ferramenta. Para uma introdução conceitual ao "tool use" (uso de ferramentas), consulte Uso de ferramentas com Claude. Para orientação sobre como implementar o uso de ferramentas na sua aplicação, consulte Definir ferramentas.

Ferramentas fornecidas pela Anthropic

A Anthropic fornece dois tipos de ferramentas: ferramentas de servidor ("server tools"), que são executadas na infraestrutura da Anthropic, e ferramentas de cliente ("client tools"), nas quais a Anthropic define o schema, mas sua aplicação cuida da execução. Ambos os tipos aparecem no array tools da sua requisição, junto com quaisquer ferramentas definidas pelo usuário.

Para compatibilidade de modelos, consulte a página de cada ferramenta. Os modelos suportados variam por ferramenta e por versão da ferramenta.

Versionamento de ferramentas

A maioria das ferramentas fornecidas pela Anthropic carrega um sufixo _YYYYMMDD na string type. Uma nova versão é lançada quando o comportamento, o schema ou o suporte a modelos da ferramenta muda. Versões mais antigas permanecem disponíveis para que integrações existentes continuem funcionando.

Quando uma ferramenta tem várias versões ativas, a relação entre elas varia:

• Por capacidade: web_search_20260209 e web_fetch_20260209 adicionam filtragem dinâmica de conteúdo em relação às suas predecessoras; web_fetch_20260309 adiciona uma opção de ignorar o cache; web_search_20260318 e web_fetch_20260318 adicionam controle de inclusão na resposta. code_execution_20260120 adiciona chamada programática de ferramentas de dentro do sandbox; code_execution_20260521 informa o limite de tempo por célula na descrição da ferramenta. Em cada caso, tanto a versão nova quanto a antiga são atuais; qual delas você usa depende de você precisar ou não da nova capacidade.
• Por modelo: text_editor_20250728 é para modelos Claude 4 e posteriores, e text_editor_20250124 é para modelos anteriores. A versão que você usa depende do modelo que você tem como alvo.
• Variante, não versão: tool_search_tool_regex_20251119 e tool_search_tool_bm25_20251119 são dois algoritmos de busca lançados juntos. Nenhum substitui o outro.
• Legado: code_execution_20250522 suporta apenas Python. code_execution_20250825 adiciona Bash e operações de arquivo.
• Sucessora: computer_toolset_20260801 é a sucessora estável das versões beta computer_20251124 e computer_20250124, que permanecem disponíveis para integrações existentes e para modelos que não suportam o conjunto de ferramentas (Versões anteriores da ferramenta). browser_toolset_20260801 é a primeira versão da ferramenta de uso de navegador. Ambas são conjuntos de ferramentas de cliente.

O tipo mcp_toolset não é versionado por data; o versionamento é carregado no cabeçalho anthropic-beta.

Conjuntos de ferramentas de cliente

A ferramenta de uso de computador e a ferramenta de uso de navegador são "client toolsets" (conjuntos de ferramentas de cliente) definidos pela Anthropic: uma entrada em tools declara um conjunto fixo de ferramentas membro cujos nomes, descrições e schemas de entrada a Anthropic define, e sua aplicação executa cada chamada. A entrada não recebe name, porque o type datado fixa os nomes dos membros. configs, cache_control e allowed_callers (que aceita apenas ["direct"]) são opcionais.

Conjuntos de ferramentas de cliente são ferramentas da Messages API. Atualmente, eles não estão disponíveis como ferramentas de agente no Claude Managed Agents, que fornece seu próprio conjunto de ferramentas de agente integrado, conjuntos de ferramentas MCP e ferramentas personalizadas.

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

configs ajusta membros individuais:

• As chaves são nomes de membros, e cada valor aceita apenas enabled e defer_loading.
• Um membro que você omite mantém seus padrões. Um valor ausente, {} e um padrão reafirmado são equivalentes.
• Um nome de membro desconhecido ou qualquer outro campo no valor de um membro é rejeitado, assim como um configs que desabilita todos os membros (omita a entrada em vez disso).
• Um membro desabilitado é removido das ferramentas que Claude vê. Se Claude ainda assim o nomear, retorne um tool_result de erro.

Defina defer_loading por membro, nunca na entrada, e dê a todos os membros habilitados o mesmo valor: sob a busca de ferramentas, o conjunto de ferramentas é carregado e expandido como uma única definição. Quando todos os membros habilitados são adiados, apenas uma ferramenta de busca de ferramentas que não esteja ela mesma adiada pode revelar o conjunto de ferramentas, então declare uma na mesma requisição. Não coloque cache_control em uma entrada de conjunto de ferramentas cujos membros são adiados; defina o ponto de interrupção em uma ferramenta não adiada, porque definições adiadas não fazem parte do prefixo em cache.

cache_control vai apenas na entrada; para saber onde o ponto de interrupção é posicionado, incluindo marcadores dentro de uma ação em lote, consulte Uso de ferramentas com cache de prompt.

Trate chamadas de ferramentas membro. Claude chama um membro com um bloco tool_use cujo name é o nome do membro e cujo toolset_name é computer ou browser; input contém os parâmetros daquele membro e nenhum campo action. Faça o despacho com base no par toolset_name e name, porque uma ferramenta personalizada pode compartilhar o nome de um membro e os dois conjuntos de ferramentas compartilham nomes como screenshot. Apenas resultados de membros ecoam toolset_name. Várias chamadas de membros em um turno formam uma ação em lote que você executa em ordem (uso de computador, uso de navegador). Novos membros chegam apenas com um novo type datado.

Não suportado em entradas de conjunto de ferramentas. A API rejeita cada um destes com um invalid_request_error:

• strict: true ou input_examples.
• defer_loading na entrada, ou membros habilitados cujos valores de defer_loading diferem (defina-o por membro em configs, todos com o mesmo valor).
• Um chamador de execução de código em allowed_callers (sem chamada programática de ferramentas).
• O cabeçalho beta legado fine-grained-tool-streaming-2025-05-14. Quando você usa streaming, o input de cada membro chega como um único input_json_delta completo.
• Um tool_choice do tipo tool que nomeia o conjunto de ferramentas ou um membro (use auto, any ou none).
• Duas entradas do mesmo conjunto de ferramentas, ou outra ferramenta que carregue o nome daquele conjunto de ferramentas: uma ferramenta chamada computer junto com computer_toolset_20260801, ou uma ferramenta chamada browser junto com browser_toolset_20260801. Os dois conjuntos de ferramentas podem ser declarados juntos.

Propriedades de definição de ferramentas

Toda ferramenta no array tools, incluindo ferramentas definidas pelo usuário, aceita propriedades opcionais que controlam como a ferramenta é carregada, quem pode chamá-la e como suas entradas são validadas. Essas propriedades se compõem: você pode definir defer_loading, cache_control e strict na mesma ferramenta.

Valores de allowed_callers

allowed_callers é um array que aceita qualquer combinação de:

Tanto "code_execution_20260120" quanto "code_execution_20260521" são aceitos em allowed_callers e são intercambiáveis: uma requisição usando qualquer uma das versões da ferramenta de execução de código satisfaz ferramentas que listam qualquer um dos chamadores. Os blocos de resposta sempre marcam o chamador como code_execution_20260120, independentemente de qual versão a requisição declarou.

Omitir "direct" do array (por exemplo, "allowed_callers": ["code_execution_20260120"]) orienta Claude a chamar a ferramenta apenas de dentro da execução de código. O bloco tool_use da resposta inclui um campo caller que identifica qual chamador chamou a ferramenta. Consulte Chamada programática de ferramentas para o tratamento completo, incluindo o formato de resposta de caller e o comportamento de erro.

defer_loading e cache de prompt

Ferramentas com defer_loading: true são removidas da seção de ferramentas renderizada antes que a chave de cache seja calculada. Elas não aparecem de forma alguma no prefixo do prompt do sistema. Quando a busca de ferramentas descobre uma ferramenta adiada e retorna um tool_reference para ela, a definição completa da ferramenta é expandida inline naquele ponto do corpo da conversa, não no prefixo.

Isso significa que defer_loading: true preserva seu cache de prompt. Você pode adicionar ferramentas adiadas a uma requisição sem invalidar uma entrada de cache existente, e o cache permanece válido ao longo do turno em que a ferramenta é descoberta e do turno em que ela é chamada.

Para saber como combinar defer_loading com pontos de interrupção de cache_control, consulte a orientação de cache de prompt da ferramenta de busca de ferramentas.