Esquemas JSON e Descrições
Nesta página
A Linguagem das Ferramentas: Esquema JSON
Para que o Grok possa chamar as suas funções, precisa de saber o que elas fazem e quais os parâmetros que esperam. É essa a função dos esquemas JSON. Cada ferramenta é descrita por um objeto estruturado que contém três elementos essenciais: um nome, uma descrição e um esquema de parâmetros.
Anatomia de uma Definição de Ferramenta
Eis a estrutura completa de uma ferramenta, tal como a API do Grok a espera:
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a given city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name (e.g., Paris, Lyon)"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius"
}
},
"required": ["city"]
}
}
Vamos analisar cada campo:
O Campo type
Sempre "function" para funções personalizadas. Existem outros tipos para ferramentas integradas (web_search, code_interpreter), mas para as suas próprias funções, é invariavelmente "function".
O Campo name
O nome técnico da sua função. Deve ser:
- Único entre todas as ferramentas no pedido
- Descritivo:
get_weatherem vez defn1 - Em snake_case por convenção:
search_products,create_ticket - Curto mas explícito: o modelo usa este nome para decidir qual a ferramenta a chamar
O Campo description
Este é o campo mais importante para a qualidade da chamada. O modelo baseia-se principalmente na descrição para decidir quando e como utilizar uma ferramenta. Uma boa descrição:
- Explica o que a função faz numa frase
- Especifica quando a utilizar (se não for óbvio)
- Menciona casos limite, se necessário
Compare estas duas descrições:
❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."
A segunda fornece ao modelo contexto suficiente para saber exatamente quando chamar esta função e o que receberá em retorno.
O Bloco parameters
Os parâmetros seguem o formato JSON Schema. Os tipos suportados incluem:
string— cadeias de caracteresnumber/integer— númerosboolean— verdadeiro/falsoarray— listasobject— objetos aninhadosenum— lista de valores permitidos
O array required lista os parâmetros obrigatórios. Os outros são opcionais — o modelo pode optar por os omitir.
Descrições de Parâmetros
Cada parâmetro deve ter a sua própria description. É isto que permite ao modelo compreender que valor passar:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Sem uma descrição, o modelo tem de adivinhar o formato esperado — o que leva a erros.
Parâmetros Avançados
Enums para Restringir Valores
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Os enums são particularmente úteis: indicam ao modelo os valores exatos que pode utilizar, eliminando erros de formato.
Valores Padrão
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
O modelo compreende que pode omitir este parâmetro se o valor padrão for adequado.
Objetos Aninhados
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Melhores Práticas para Descrições
A descrição é o único canal através do qual o modelo compreende a sua ferramenta — cada palavra conta. Priorize a especificidade: “Pesquisar produtos por nome ou categoria no catálogo” indica ao modelo exatamente quando esta ferramenta se aplica, enquanto “Pesquisar produtos” deixa-o a adivinhar. Em seguida, os formatos: especificar “Data no formato ISO 8601 (AAAA-MM-DD)” numa descrição de parâmetro elimina metade dos erros de argumentos, porque o modelo replica o formato que lhe mostra. Os limites fazem parte do contrato: “Máximo de 50 resultados por chamada” impede que o modelo prometa ao utilizador uma completude que a ferramenta não fornecerá. E descrever o retorno — “Devolve um objeto com preço, disponibilidade e descrição” — ajuda o modelo a planear antecipadamente: sabe com o que contará antes mesmo de efetuar a chamada.
Pontos-chave
- Cada ferramenta é definida por um
name, umadescriptioneparameters - A descrição é o fator nº 1 na qualidade da chamada — invista tempo nela
- Os nomes devem ser únicos e em snake_case
- Utilize
enumpara restringir os valores possíveis - Cada parâmetro deve ter a sua própria descrição com o formato esperado
- O array
requireddistingue os parâmetros obrigatórios dos opcionais