Definindo Schemas de Ferramentas com name, description e input_schema
Uma definição de ferramenta é a única informação que o Claude tem sobre o que sua função faz e quando usá-la. Acertar o schema e o Claude a chamará corretamente; torná-lo vago e o Claude o ignorará ou preencherá com suposições.
Resumo
Toda ferramenta que você fornece ao Claude é um objeto JSON com três campos obrigatórios: name, description e input_schema. O Claude nunca executa seu código diretamente - ele lê essa definição e decide se emite um bloco tool_use e, em caso afirmativo, quais argumentos colocar nele.
O campo description carrega a maior parte do peso. O Claude confia nele para decidir se deve chamar a ferramenta e como preencher seus parâmetros, então uma descrição de uma linha que apenas reafirma o nome da função não é suficiente.
input_schema é um JSON Schema padrão, com escopo para as propriedades que esta ferramenta realmente aceita. Cada propriedade deve carregar sua própria description, e qualquer parâmetro com um pequeno conjunto fixo de valores legais deve usar enum em vez de texto livre.
Para ferramentas de produção, adicione "strict": true no nível superior da definição da ferramenta. Isso força o schema a ser exato - additionalProperties: false mais uma lista explícita required - e garante que o que quer que o Claude retorne em tool_use.input valide contra seu schema, sem necessidade de verificação posterior.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
from anthropic import Anthropic
client = Anthropic()
tools = [
{
"name": "get_weather",
"description": (
"Get current weather for a location. Call this when the user "
"asks about current conditions, temperature, or forecast for "
"a specific place."
),
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and state, e.g., San Francisco, CA",
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit",
},
},
"required": ["location"],
},
}
]Quando usar isso:
- Ao definir qualquer nova ferramenta que o Claude poderá chamar.
- Uma ferramenta tem parâmetros opcionais e você precisa que o Claude saiba quais deles realmente importam.
- Um parâmetro aceita apenas um pequeno conjunto conhecido de valores (status, categorias, unidades).
- Você está depurando por que o Claude chama uma ferramenta com os argumentos errados ou a ignora completamente.
- Você deseja que a saída do Claude seja segura para máquinas sem escrever sua própria camada de validação (use
strict: true).
Exemplo de Trabalho
from anthropic import Anthropic
client = Anthropic()
search_database_tool = {
"name": "search_database",
"description": (
"Search the internal product catalog by keyword and optional "
"category filter. Call this when the user asks to find, look up, "
"or compare products - do not call it for general product "
"knowledge questions that don't need a live lookup."
),
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Free-text search keywords, e.g., 'wireless mouse'",
},
"category": {
"type": "string",
"enum": ["electronics", "home", "outdoor", "apparel"],
"description": "Restrict results to one product category",
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return",
},
},
"required": ["query"],
},
}
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
tools=[search_database_tool],
messages=[
{"role": "user", "content": "Find me a wireless mouse under home electronics"}
],
)
for block in response.content:
if block.type == "tool_use":
print(f"Tool called: {block.name}")
print(f"Arguments: {block.input}")O que isso demonstra:
- Uma
descriptionque declara tanto o que a ferramenta faz quanto quando chamá-la, não apenas sua função. categoryrestrita a um conjunto fechado de valores legais comenum, em vez de texto livre que o Claude poderia errar.max_resultsdeixado opcional (ausente derequired) porque a ferramenta tem um padrão razoável sem ele.- Leitura de
response.contentpara um blocotool_usee inspeção deblock.name/block.input, os argumentos que o Claude gerou de acordo com seu schema.
Mergulho Profundo
Como Funciona
- O Claude recebe seu array
toolsjunto com a conversa e trata cadadescriptioncomo documentação que ele lê antes de decidir agir. - Quando uma solicitação corresponde ao propósito declarado de uma ferramenta, o Claude emite um bloco de conteúdo
tool_usecontendo onameda ferramenta e um objetoinputque ele gerou para satisfazer seuinput_schema. - Os campos
descriptionem nível de propriedade moldam como o Claude preenche os argumentos - um campo de localização descrito como "Cidade e estado, por exemplo, São Paulo, SP" produz um formato mais consistente do que um simples"type": "string". requireddiz ao Claude quais campos ele deve preencher antes de chamar a ferramenta; tudo o mais ele preenche apenas quando a conversa fornece um valor.- Modelos mais novos, como o Claude Sonnet 5, são mais conservadores em relação ao uso de ferramentas do que os anteriores, portanto, uma cláusula explícita "chame esta ferramenta quando..." na descrição melhora mensuravelmente a precisão de deveria chamar - não é apenas uma decoração de prosa.
Campos Obrigatórios em Resumo
| Campo | Tipo | Propósito |
|---|---|---|
name | string | Identificador exclusivo e descritivo que o Claude ecoa de volta em tool_use.name |
description | string | O que a ferramenta faz e, criticamente, quando chamá-la |
input_schema | object (JSON Schema) | Define a forma dos argumentos que o Claude deve produzir |
Modo Estrito
Defina "strict": true como um campo de nível superior na definição da ferramenta (ao lado de name, description, input_schema) para forçar tool_use.input a validar exatamente contra seu schema, sem necessidade de cabeçalho beta.
strict_tool = {
"name": "create_ticket",
"description": "Create a support ticket. Call this when the user reports a bug or requests help that needs to be tracked.",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string", "description": "Short ticket title"},
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "urgent"],
"description": "Ticket priority",
},
},
"required": ["title", "priority"],
"additionalProperties": False,
},
}O modo estrito requer additionalProperties: false e um array required explícito no schema. Ele suporta tipos básicos (object, array, string, integer, number, boolean, null), enum, const, anyOf, allOf, $ref/$def, e formatos de string (date-time, date, email, uri, uuid e similares). Ele não suporta schemas recursivos, restrições numéricas (minimum, maximum, multipleOf), restrições de comprimento de string (minLength, maxLength), restrições complexas de array ou additionalProperties definido como qualquer coisa diferente de false.
Notas Python
# input_schema is a plain dict - build it with helpers if it grows large,
# but keep it inline for small tools so name/description/schema stay
# reviewable together.
def weather_tool(units: list[str]) -> dict:
return {
"name": "get_weather",
"description": (
"Get current weather for a location. Call this when the user "
"asks about current conditions."
),
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City and state"},
"unit": {"type": "string", "enum": units, "description": "Temperature unit"},
},
"required": ["location"],
},
}Parâmetros e Valores de Retorno
| Parâmetro | Tipo | Descrição |
|---|---|---|
name | str | Identificador exclusivo da ferramenta; o Claude retorna isso em tool_use.name |
description | str | Explica o que a ferramenta faz e, prescritivamente, quando chamá-la |
input_schema | dict | Objeto JSON Schema descrevendo os argumentos aceitos |
input_schema.properties | dict | Definições por parâmetro, cada uma com sua própria description |
input_schema.required | list[str] | Nomes dos parâmetros que o Claude deve sempre fornecer |
strict | bool (opcional) | Quando True, garante que tool_use.input corresponda exatamente ao schema |
Armadilhas
- Nomes vagos como
helperouw. O Claude não tem nada para desambiguar entre ferramentas quando os nomes não descrevem seu propósito. Correção: use nomes específicos e orientados à ação comoget_weatherousearch_database. - Uma descrição que apenas reafirma o nome.
"description": "Obtém o clima"não diz nada ao Claude sobre quando usá-lo em vez de responder com conhecimento geral. Correção: declare o propósito e adicione uma cláusula explícita "Chame esta ferramenta quando...". - Descrições ausentes por propriedade. Um simples
{"type": "string"}não dá ao Claude nenhuma pista sobre o formato esperado, então ele adivinha a formatação (por exemplo,"NYC"vs"Nova York, NY"). Correção: adicione umadescriptioncom um exemplo a cada propriedade. - Strings de texto livre para campos de escolha fixa. Sem
enum, um campounitpode retornar como"F","Fahrenheit"ou"fahrenheit"dependendo da formulação. Correção: restrinja parâmetros de escolha fixa comenum. - Marcar tudo como
required. Forçar o Claude a inventar valores para parâmetros que a conversa nunca mencionou produz argumentos de baixa qualidade e inventados. Correção: liste apenas os parâmetros emrequiredque a ferramenta genuinamente não pode executar sem. - Usar
strict: truecom restrições não suportadas.minLength,maximumou um$refrecursivo em um schema de modo estrito falharão na validação, não se tornando silenciosamente mais flexíveis. Correção: mova as verificações de comprimento/intervalo para seu próprio código de execução de ferramenta e mantenha o schema estrito no subconjunto suportado. - Muitas ferramentas sobrepostas. Um grande conjunto de ferramentas com descrições vagas e semelhantes faz com que o Claude escolha a ferramenta errada ou hesite e não chame nenhuma. Correção: mantenha o conjunto de ferramentas focado e dê a cada ferramenta uma descrição específica o suficiente para ser inconfundível ao lado de suas vizinhas.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
Schema solto, sem strict | Prototipagem, ou seu próprio código já valida tool_use.input antes do uso | Você precisa de uma garantia forte de que a entrada do Claude corresponde exatamente ao seu schema |
strict: true | Ferramentas de produção alimentando diretamente chamadas de função tipadas ou APIs externas | Seu schema precisa de intervalos numéricos, limites de comprimento de string ou estruturas recursivas |
Uma grande ferramenta multipropósito com um parâmetro action enum | Um punhado de operações intimamente relacionadas (por exemplo, create/update/delete em um recurso) | As operações recebem argumentos fundamentalmente diferentes - ferramentas separadas mantêm os schemas mais limpos |
| Várias ferramentas pequenas e de propósito único | Cada operação tem um nome, descrição e formato de argumento distintos que o Claude nunca deve confundir | Você tem dezenas de ferramentas quase duplicadas - considere a ferramenta de busca de ferramentas em vez disso (ferramenta de busca de ferramentas) |
FAQs
Quais três campos toda definição de ferramenta precisa?
name- um identificador exclusivo e descritivodescription- o que a ferramenta faz e quando chamá-lainput_schema- um objeto JSON Schema definindo os argumentos aceitos
Por que a descrição importa tanto?
O Claude lê a description da mesma forma que um desenvolvedor lê a documentação antes de decidir se e como chamar uma função. Uma descrição vaga leva a chamadas perdidas (o Claude não percebe que a ferramenta se aplica) ou argumentos errados (o Claude não tem orientação de formato).
Devo descrever quando chamar a ferramenta ou apenas o que ela faz?
Ambos. Declarar uma condição como "Chame esta ferramenta quando o usuário perguntar sobre preços atuais ou eventos recentes" melhora mensuravelmente se o Claude alcança a ferramenta no momento certo, especialmente em modelos mais novos que chamam ferramentas de forma mais conservadora por padrão.
Preciso de uma descrição em cada propriedade dentro de input_schema, ou apenas na descrição de nível superior da ferramenta?
Ambos os níveis importam. A description de nível superior decide se/quando chamar a ferramenta; a description de cada propriedade molda como o Claude preenche esse argumento específico (formato, unidades, exemplos).
Quando devo usar enum em vez de um tipo string simples?
Sempre que um parâmetro tiver apenas um pequeno conjunto conhecido de valores legais - unidades, status, categorias. enum impede que o Claude retorne variantes inconsistentes como "F" vs "fahrenheit".
Como decido o que vai em required?
Liste apenas os parâmetros que a ferramenta não pode executar sem. Todos os outros devem ser opcionais para que o Claude não precise inventar um valor quando a conversa não forneceu um.
O que strict: true realmente garante?
Que tool_use.input valida exatamente contra seu input_schema - sem campos obrigatórios ausentes, sem propriedades extras. Ele requer additionalProperties: false e um array required explícito, e não precisa de cabeçalho beta.
Onde strict vai na definição da ferramenta?
tool = {
"name": "create_ticket",
"description": "...",
"strict": True,
"input_schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": False},
}É um campo de nível superior ao lado de name/description/input_schema, não algo definido em tool_choice.
Quais recursos do JSON Schema estão fora de uso no modo estrito?
Schemas recursivos, restrições numéricas (minimum/maximum/multipleOf), restrições de comprimento de string (minLength/maxLength), restrições complexas de array e qualquer valor de additionalProperties diferente de false.
Ainda posso usar minLength ou maximum se precisar deles?
Não sob strict: true. Ou descarte o modo estrito e valide essas restrições você mesmo após receber tool_use.input, ou imponha-as em seu código de execução de ferramenta em vez do schema.
O que acontece se eu der a duas ferramentas descrições muito semelhantes?
O Claude pode escolher a errada, ou hesitar e não chamar nenhuma, porque as descrições não fornecem sinal suficiente para desambiguar. Mantenha a descrição de cada ferramenta específica o suficiente para ser inconfundível ao lado de suas vizinhas.
input_schema deve ser algo diferente de type: object?
Não - input_schema sempre descreve um objeto cujas properties são os argumentos nomeados da ferramenta. Propriedades individuais podem ser qualquer tipo de JSON Schema (string, integer, array, etc.), mas a raiz do schema é sempre object.
Quantas ferramentas são muitas para definir de uma vez?
Não há um limite rígido, mas um grande conjunto de ferramentas com descrições vagas ou sobrepostas confunde a seleção de ferramentas muito antes de você atingir qualquer limite técnico. Mantenha o conjunto de ferramentas ativo focado no que é relevante para a conversa.
Relacionados
- Noções Básicas de Uso de Ferramentas - o ciclo completo mínimo de
tool_use/tool_resultao qual este schema se conecta. - Como o Claude Decide Quando Chamar uma Ferramenta - como a redação da descrição afeta a precisão de deveria chamar.
- Lidando com Solicitações de Uso de Ferramentas e Retornando Blocos de Resultado de Ferramenta - o que fazer com o
tool_use.inputque este schema produz. - Melhores Práticas - orientação mais ampla para projetar agentes confiáveis que usam ferramentas.
Versões da Stack: Escrito contra a linha de modelos Claude atual em aproximadamente 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.