Planilha de Parâmetros defer_loading da Ferramenta de Busca de Ferramentas
Referê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.
Como Usar Esta Planilha
- Procure a string
typeexata para a variante de busca que você deseja antes de escrever o arraytools- um erro de digitação no sufixo da data é uma fonte comum de erros de "tipo de ferramenta desconhecido". - Verifique a tabela de restrições antes de implantar - os dois modos de falha graves (adiar a própria ferramenta de busca, adiar todas as ferramentas) são silenciosos até o momento da solicitação.
- Use a tabela de decisão para escolher entre regex e BM25 com base em como sua biblioteca de ferramentas está organizada.
- Releia a nota sobre economia de tokens quando o número de suas ferramentas ultrapassar algumas dezenas -
defer_loadingsó compensa quando o volume do schema se torna o gargalo.
Variantes da Ferramenta de Busca de Ferramentas
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...
]Referência de 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ções e Armadilhas
| 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. |
Formato Mínimo da Solicitação
{
"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?"}],
)Escolhendo Regex vs BM25
| 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 |
FAQs
O que `defer_loading` realmente economiza?
- Mantém o schema JSON completo de uma ferramenta fora do payload da solicitação inicial.
- Claude só vê o nome e a descrição da ferramenta (através da ferramenta de busca) até decidir que a ferramenta é relevante.
- Em bibliotecas de ferramentas grandes, é aqui que vêm as economias de ~85% de tokens - você para de pagar para reenviar centenas de schemas não utilizados em cada turno.
Posso definir `defer_loading: true` em todas as ferramentas no meu array `tools`?
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.
A própria ferramenta de busca pode ser adiada?
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.
Como sei quando Claude usou a ferramenta de busca?
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á.
Chamar a ferramenta de busca quebra o cache de prompt?
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.
Devo adiar todas as ferramentas que não estão no caminho óbvio da solicitação atual?
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.
Preciso de um cabeçalho beta para usar a Ferramenta de Busca de Ferramentas?
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.
Como passo `defer_loading` no SDK Python?
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.
Qual é a diferença entre descoberta por regex e BM25?
- Regex (
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. - BM25 (
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.
Posso misturar ferramentas adiadas e sempre carregadas na mesma solicitação?
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.
Qual modelo devo usar em exemplos de solicitação?
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.
Vale a pena usar `defer_loading` em uma biblioteca de ferramentas pequena?
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.
Relacionados
- Escalando para Centenas de Ferramentas com a Ferramenta de Busca de Ferramentas - o guia completo que esta planilha resume.
- Conectando-se a Ferramentas Remotas via Conector MCP - outra maneira de escalar uma grande superfície de ferramentas.
- Referência de Opções de Escolha de Ferramentas - controlando quando e quais ferramentas Claude chama.
- Melhores Práticas - orientação mais ampla sobre uso de ferramentas na qual esta planilha se encaixa.
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.