Busque em todas as páginas da documentação
defer_loading da Ferramenta de Busca de FerramentasReferência rápida para configurar a Ferramenta de Busca de Ferramentas: qual string de type declarar, o que defer_loading faz em uma ferramenta individual e as restrições que causarão um erro 400 na sua solicitação se você errar.
type exata para a variante de busca que você deseja antes de escrever o array tools - um erro de digitação no sufixo da data é uma fonte comum de erros de "tipo de ferramenta desconhecido".defer_loading só compensa quando o volume do schema se torna o gargalo.type | name | Método de descoberta | Ideal para |
|---|---|---|---|
tool_search_tool_regex_20251119 | tool_search_tool_regex | Correspondência de padrão Regex em nomes e descrições de ferramentas | Bibliotecas de ferramentas com convenções de nomenclatura previsíveis (ex: crm_get_*, crm_update_*) |
tool_search_tool_bm25_20251119 | tool_search_tool_bm25 | Classificação de relevância de palavra-chave BM25 | Grandes catálogos de ferramentas pouco relacionadas onde Claude precisa corresponder a intenção em linguagem natural com descrições de ferramentas |
Ambas são ferramentas do lado do servidor - você as declara no array tools como qualquer outra ferramenta, mas a Anthropic executa a busca. Nenhuma delas aceita um input_schema; Claude as chama da mesma forma que chama qualquer ferramenta, e você nunca implementa um handler para elas.
tools = [
{"type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25"},
# ...suas outras definições de ferramentas...
]defer_loading| Campo | Tipo | Padrão | Efeito |
|---|---|---|---|
defer_loading | booleano | false | Quando true em uma definição de ferramenta, seu schema completo é omitido do contexto da solicitação inicial. Claude descobre a ferramenta chamando a ferramenta de busca, e o schema correspondente é carregado no contexto sob demanda. |
{
"name": "get_weather",
"description": "Obtém o clima atual para uma localização.",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
"defer_loading": True,
}defer_loading é o mecanismo por trás da economia de tokens: em uma biblioteca de centenas de ferramentas, adiar a maioria raramente usada e manter apenas um punhado sempre carregado pode cortar ~85% dos tokens que seriam gastos reenviando todos os schemas de ferramentas em cada solicitação.
| Restrição | O que acontece se você violá-la |
|---|---|
A própria ferramenta de busca (tool_search_tool_regex / tool_search_tool_bm25) nunca deve ter defer_loading: true. | A ferramenta de busca precisa estar visível para Claude desde o primeiro turno - adiá-la significaria que nada poderia descobri-la. |
| Pelo menos uma ferramenta na solicitação deve permanecer não adiada. | Um array tools totalmente adiado retorna 400: All tools have defer_loading set. |
| Schemas descobertos são anexados à solicitação, não substituídos. | Isso é um recurso, não uma armadilha - significa que o prefixo do cache para tools e system permanece intacto após uma chamada de busca, então você não paga um custo total de cache miss toda vez que Claude busca. |
Resultados da busca chegam como um bloco de conteúdo tool_search_tool_result. | Código que verifica apenas os tipos de bloco tool_use / text ignorará silenciosamente os resultados da busca - crie um branch com tool_search_tool_result explicitamente se você estiver inspecionando o conteúdo da resposta. |
| Misturar ferramentas sempre carregadas e adiadas em uma solicitação é suportado e esperado. | Mantenha ferramentas de uso frequente e com schema pequeno sempre carregadas; adie ferramentas raramente usadas ou ferramentas que fazem parte de um grande catálogo. |
{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"tools": [
{"type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25"},
{"name": "get_weather", "description": "...", "input_schema": {"type": "object", "properties": {}}, "defer_loading": true}
],
"messages": [{"role": "user", "content": "..."}]
}Python equivalente, usando o SDK oficial anthropic:
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
tools=[
{"type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25"},
{
"name": "get_weather",
"description": "Obtém o clima atual para uma localização.",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
"defer_loading": True,
},
],
messages=[{"role": "user", "content": "Qual é o clima em Boston?"}],
)| Se sua biblioteca de ferramentas... | Use |
|---|---|
| Segue uma convenção de nomenclatura/prefixo consistente que você pode expressar como um padrão | tool_search_tool_regex_20251119 |
| É grande, organizada de forma flexível, ou correspondida melhor por intenção em linguagem natural do que por estrutura de nomenclatura | tool_search_tool_bm25_20251119 |
| É pequena o suficiente para que todos os schemas caibam confortavelmente no contexto | Nenhuma das duas - pule a Ferramenta de Busca de Ferramentas completamente e carregue todas as ferramentas normalmente |
Não. Pelo menos uma ferramenta deve permanecer não adiada, ou a solicitação retorna 400: All tools have defer_loading set. Na prática, isso significa a própria ferramenta de busca mais pelo menos uma outra ferramenta.
Não. tool_search_tool_regex e tool_search_tool_bm25 nunca devem ter defer_loading: true - Claude precisa da ferramenta de busca visível desde o início para poder descobrir qualquer outra coisa.
Procure por um bloco de conteúdo tool_search_tool_result na resposta. Este é um tipo de bloco distinto de tool_use e text - código que verifica apenas esses dois o perderá.
Não. Schemas de ferramentas descobertos são anexados à solicitação em vez de substituir o array tools existente, portanto, o prefixo em cache para tools e system é preservado durante a chamada de busca.
Não necessariamente. Mantenha ferramentas de uso frequente e com schema pequeno sempre carregadas para que solicitações comuns não precisem de uma viagem de ida e volta de busca. Reserve defer_loading para ferramentas raramente usadas ou que fazem parte de um grande catálogo onde o volume do schema é o problema real.
Declare a ferramenta com sua string type versionada (tool_search_tool_regex_20251119 ou tool_search_tool_bm25_20251119) no array tools como qualquer outra ferramenta do lado do servidor. Verifique a documentação da plataforma atual para requisitos de cabeçalho, pois o status beta pode mudar entre as versões do SDK.
Adicione "defer_loading": True como uma chave dentro do dicionário da ferramenta na lista tools que você passa para client.messages.create(...). Ela fica ao lado de name, description e input_schema na mesma definição de ferramenta.
tool_search_tool_regex_20251119) corresponde a nomes e descrições de ferramentas com um padrão - bom quando suas ferramentas seguem uma convenção de nomenclatura previsível.tool_search_tool_bm25_20251119) classifica ferramentas por relevância de palavra-chave - melhor quando os nomes das ferramentas não codificam claramente a intenção e Claude precisa corresponder linguagem natural a descrições.Sim, e este é o padrão de uso esperado. Mantenha um pequeno conjunto de ferramentas frequentemente usadas sempre carregadas e adie o restante de um grande catálogo.
claude-sonnet-5 é o modelo Claude padrão atual e funciona bem para cargas de trabalho com uso intensivo de ferramentas. Qualquer modelo atual que suporte uso de ferramentas pode usar a Ferramenta de Busca de Ferramentas.
Geralmente não. Se todos os seus schemas de ferramentas já cabem confortavelmente no contexto sem sobrecarga de tokens perceptível, pule a Ferramenta de Busca de Ferramentas completamente - a viagem de ida e volta da busca adiciona latência que você não precisa pagar.
Versões de Stack: Escrito com base na linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026