Definindo Schemas de Ferramentas com name, description e input_schema

Q: Quais três campos toda definição de ferramenta precisa?

name - um identificador exclusivo e descritivo description - o que a ferramenta faz e quando chamá-la input_schema - um objeto JSON Schema definindo os argumentos aceitos

Q: 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).

Q: 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).

Q: 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.

Q: Onde strict vai na definição da ferramenta?

É um campo de nível superior ao lado de name/description/input_schema, não algo definido em tool_choice.

Q: 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.

Q: 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.

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 description que declara tanto o que a ferramenta faz quanto quando chamá-la, não apenas sua função.
category restrita a um conjunto fechado de valores legais com enum, em vez de texto livre que o Claude poderia errar.
max_results deixado opcional (ausente de required) porque a ferramenta tem um padrão razoável sem ele.
Leitura de response.content para um bloco tool_use e inspeção de block.name / block.input, os argumentos que o Claude gerou de acordo com seu schema.

Mergulho Profundo

Como Funciona

O Claude recebe seu array tools junto com a conversa e trata cada description como 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_use contendo o name da ferramenta e um objeto input que ele gerou para satisfazer seu input_schema.
Os campos description em 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".
required diz 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 helper ou w. 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 como get_weather ou search_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 uma description com um exemplo a cada propriedade.
Strings de texto livre para campos de escolha fixa. Sem enum, um campo unit pode retornar como "F", "Fahrenheit" ou "fahrenheit" dependendo da formulação. Correção: restrinja parâmetros de escolha fixa com enum.
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 em required que a ferramenta genuinamente não pode executar sem.
Usar strict: true com restrições não suportadas. minLength, maximum ou um $ref recursivo 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 descritivo
description - o que a ferramenta faz e quando chamá-la
input_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_result ao 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.input que 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 anthropic para 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.

Resumo

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 description que declara tanto o que a ferramenta faz quanto quando chamá-la, não apenas sua função.
category restrita a um conjunto fechado de valores legais com enum, em vez de texto livre que o Claude poderia errar.
max_results deixado opcional (ausente de required) porque a ferramenta tem um padrão razoável sem ele.
Leitura de response.content para um bloco tool_use e inspeção de block.name / block.input, os argumentos que o Claude gerou de acordo com seu schema.

Mergulho Profundo

Como Funciona

O Claude recebe seu array tools junto com a conversa e trata cada description como 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_use contendo o name da ferramenta e um objeto input que ele gerou para satisfazer seu input_schema.
Os campos description em 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".
required diz 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

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,
    },
}

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 helper ou w. 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 como get_weather ou search_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 uma description com um exemplo a cada propriedade.
Strings de texto livre para campos de escolha fixa. Sem enum, um campo unit pode retornar como "F", "Fahrenheit" ou "fahrenheit" dependendo da formulação. Correção: restrinja parâmetros de escolha fixa com enum.
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 em required que a ferramenta genuinamente não pode executar sem.
Usar strict: true com restrições não suportadas. minLength, maximum ou um $ref recursivo 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 descritivo
description - o que a ferramenta faz e quando chamá-la
input_schema - um objeto JSON Schema definindo os argumentos aceitos

Por que a descrição importa tanto?

Devo descrever quando chamar a ferramenta ou apenas o que ela faz?

Preciso de uma descrição em cada propriedade dentro de input_schema, ou apenas na descrição de nível superior da ferramenta?

Quando devo usar enum em vez de um tipo string simples?

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?

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?

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?

input_schema deve ser algo diferente de type: object?

Quantas ferramentas são muitas para definir de uma vez?

Relacionados

Noções Básicas de Uso de Ferramentas - o ciclo completo mínimo de tool_use/tool_result ao 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.input que 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 anthropic para 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.

Definindo Schemas de Ferramentas com name, description e input_schema

Buscar na documentação

Definindo Schemas de Ferramentas com name, description e input_schema