Uma definição de ferramenta tem duas tarefas e só uma delas é JSON. O esquema diz que formato os argumentos têm; as descrições dizem para que a ferramenta serve e o que cada argumento significa. Um esquema pode ser perfeitamente válido e ainda assim produzir uma ferramenta chamada na hora errada com bobagem plausível dentro, porque nada no JSON explica o que é o quê. Este criador escreve o esquema e confere as duas metades: a estrutura e se alguma coisa foi de fato descrita. O modo estrito também é tratado como deve: ele exige que toda propriedade conste como obrigatória e proíbe extras, o que pega as pessoas de surpresa porque o esquema no mais fica igual.
Recursos
Parâmetros com tipos, descrições e conjuntos fechados de valores opcionais
A regra de “tudo obrigatório” do modo estrito aplicada, não descoberta depois
additionalProperties definido corretamente com o modo estrito ligado
Arrays recebem um esquema de items automaticamente
Avisa sobre parâmetro sem descrição
Pega nomes de parâmetro duplicados
Aponta um enum com um único valor, que é uma constante
Emite a definição inteira, não só o esquema
Como usar Esquema de ferramenta MCP
Nomeie a ferramenta e descreva quando ela deve ser usada
Acrescente cada parâmetro com tipo e descrição
Marque quais são obrigatórios, ou ligue o modo estrito
Copie a definição para o seu array de ferramentas
Exemplo
Entrada
"strict": true
Saída
Error: strict mode requires every property to be listed as required
O modo estrito não aceita propriedades opcionais: permita null no lugar.
Erros comuns e solução de problemas
O modo estrito é rejeitado. — Ele exige todas as propriedades obrigatórias e additionalProperties false. Marque as opcionais como obrigatórias permitindo null, ou desligue o modo estrito.
A ferramenta é chamada com argumentos errados. — Normalmente parâmetros sem descrição. Um nome sozinho deixa o significado por dedução, e “id” poderia ser qualquer coisa.
A ferramenta é chamada na hora errada. — Isso é a descrição da ferramenta, não o esquema. Diga quando usar e o que ela devolve, não só o que faz.
Um parâmetro de array é rejeitado. — Arrays precisam de um esquema de items dizendo o que contêm. Aqui um é acrescentado automaticamente.
Perguntas frequentes
O que o modo estrito muda de fato?
Ele garante que os argumentos validam contra o esquema exatamente. O preço é que toda propriedade precisa constar como obrigatória e nenhuma extra é aceita, então um argumento realmente opcional precisa ser modelado como obrigatório mas anulável.
Quão detalhada deve ser a descrição de um parâmetro?
O suficiente para alguém que leia só o esquema saber o que colocar ali: o formato, as unidades, de onde vem o valor. “O e-mail do cliente com que o pedido foi feito” vale muito mais que “e-mail”.
Quando devo usar um enum?
Quando o conjunto de valores válidos for realmente fechado e curto. Ele elimina uma classe inteira de respostas erradas. Um enum de valor único é apontado porque é uma constante, não um parâmetro.
Serve para ferramentas MCP e de API?
O esquema é o mesmo subconjunto de JSON Schema nos dois casos. O invólucro muda um pouco conforme o contexto, mas o esquema de entrada — a parte fácil de errar — é idêntico.
O que faz uma boa descrição de ferramenta?
Três coisas em duas frases: o que ela faz, quando recorrer a ela e o que devolve. A última é a mais omitida e a mais útil, porque diz a quem chama se uma chamada só vai bastar.
Ferramentas relacionadas
Verificador de esquemas — Cole uma definição e descubra por que ela é rejeitada ou chamada errado.