Schemas de Ferramentas (Tools & JSON Schema)

1. Visão geral do conceito e propósito

Imagine que você contratou um novo assistente para o escritório e disse a ele: "Aqui está nosso software especial, use-o". Mas não explicou quais botões fazem o quê nem quais campos precisam ser preenchidos. Naturalmente, o assistente ficaria perdido.

Para que um modelo de linguagem saiba quais ferramentas digitais estão à sua disposição, os desenvolvedores fornecem a ela uma Tool Schema (Esquema de Ferramenta).

Trata-se de uma descrição compacta, elaborada conforme o padrão JSON Schema:

• Name: nome curto da ferramenta (por exemplo, book_hotel).
• Description: explicação em linguagem natural sobre a finalidade dessa ação.
• Parameters: dados necessários para executar a operação (cidade, data de check-in, número de hóspedes).

Modelo mental: é como uma descrição de cargo para IA: uma lista de ferramentas no cinto do artesão, com instruções claras sobre quando usar o martelo e quando usar a chave de fenda.

2. Como é uma Tool Schema real

{
  "name": "calculate_mortgage",
  "description": "Розраховує щомісячний платіж за іпотечним кредитом.",
  "parameters": {
    "type": "object",
    "properties": {
      "loan_amount": {
        "type": "number",
        "description": "Повна сума кредиту в гривнях, наприклад 1500000"
      },
      "years": {
        "type": "integer",
        "description": "Термін кредиту в роках від 1 до 30"
      },
      "interest_rate": {
        "type": "number",
        "description": "Річна відсоткова ставка у відсотках, наприклад 7.5"
      }
    },
    "required": ["loan_amount", "years"]
  }
}

3. As quatro regras de ouro para criar bons esquemas

1. Escreva descrições como se estivesse orientando um estagiário: indique não apenas o que a ferramenta faz, mas também quando NÃO deve ser chamada.
2. Inclua exemplos no campo de descrição: "formato de data estritamente YYYY-MM-DD, por exemplo, 2026-05-18".
3. Restrinja opções usando enum: se o status do pedido só pode ter três valores, defina rigorosamente: ["pending", "shipped", "delivered"].
4. Marque campos obrigatórios no array required: se a função não funciona sem o email do cliente, não permita que o modelo a execute às cegas.

4. Conclusão prática

A qualidade e a autonomia do seu AI-agent dependem em 80% não do tamanho do modelo, mas da qualidade e clareza das descrições nos seus Tool Schemas. Quanto mais precisa for a descrição, menos erros o agente cometerá.