Existem dois tipos de problema numa definição de ferramenta. O primeiro é estrutural: um tipo que não é tipo de JSON Schema, um nome obrigatório que não está entre as propriedades, um array sem items, o modo estrito sem as regras que o modo estrito impõe. Isso é rejeitado, geralmente com uma mensagem que nomeia o campo mas não o motivo. O segundo tipo valida perfeitamente e causa outro problema: a ferramenta é chamada na hora errada, ou com bobagem plausível num argumento, porque nada no esquema diz o que é o quê. Isto confere os dois, relata cada achado junto do caminho de onde veio e aceita o formato que você colar: uma ferramenta, um array, um fragmento de requisição ou um esquema solto.
Recursos
Aceita uma ferramenta, um array, um fragmento tools ou um esquema solto
Cada achado traz o caminho de onde veio
Pega tipos inválidos, inclusive em propriedades individuais
Pega um nome obrigatório que não é propriedade
Aplica as regras do modo estrito e diz que propriedades as violam
Aponta um esquema sob a chave errada
Pega nomes de ferramenta duplicados num array
Avisa sobre parâmetros sem descrição e enums vazios
Como usar Verificador de esquemas
Cole a definição, no formato que você tiver
Leia os achados junto dos caminhos
Corrija primeiro os erros, depois as descrições
Confira de novo até não sobrar nada
Exemplo
Entrada
"required": ["email", "customer_id"]
Saída
Error: “customer_id” is required but is not among the properties
Um nome obrigatório sem propriedade correspondente é rejeitado de saída.
Erros comuns e solução de problemas
A API rejeita a ferramenta sem nomear campo nenhum. — Cole aqui: os achados trazem caminho, então o nó problemático é nomeado em vez de deixado para você procurar.
Diz que meu esquema está sob a chave errada. — A API de mensagens lê input_schema. Definições escritas para outras convenções costumam usar parameters, que é JSON válido e simplesmente não é lido.
O modo estrito falha num esquema que parece certo. — Ele precisa de additionalProperties: false e de todas as propriedades como obrigatórias. Ambos são conferidos, com as propriedades problemáticas nomeadas.
Avisa sobre descrições em vez de erros. — Essa é a segunda classe de problema. Elas não impedem a ferramenta de ser aceita; são o motivo de ela ser chamada com os argumentos errados.
Perguntas frequentes
Que formatos posso colar?
Um objeto de ferramenta, um array deles, um fragmento {"tools": [...]} ou um esquema de entrada solto. Um esquema solto é reconhecido e apontado, já que uma ferramenta também precisa de nome e descrição.
Por que avisa sobre descrições faltando?
Porque são a causa mais comum de uma ferramenta ser chamada errado, e nunca produzem erro. Um parâmetro com nome e sem descrição deixa o significado para ser deduzido só do nome.
Confere meu esquema contra argumentos reais?
Não: confere a definição em si. Se um conjunto específico de argumentos valida é outra pergunta, e a API responde quando você faz a chamada.
Os $ref são suportados?
São apontados. Referências não são resolvidas de forma confiável em esquemas de ferramenta, então uma definição que dependa de uma costuma se comportar diferente do que quem a escreveu leu. Colocar a definição inline evita a questão.
Posso conferir várias ferramentas de uma vez?
Sim, cole o array inteiro. Nomes duplicados no conjunto são pegos, um problema que só aparece quando as ferramentas são olhadas juntas.
Ferramentas relacionadas
Esquema de ferramenta MCP — Defina uma ferramenta e obtenha o JSON Schema, com o modo estrito verificado.