# Tools

### 🧰 Cadastro de Ferramentas (Tools) no Assistente de IA

Ao cadastrar uma Ferramenta (Tool) no Assistente de IA, é fundamental preencher corretamente os campos abaixo. Essas informações são utilizadas diretamente pelo modelo de IA para decidir **quando**, **como** e **com quais dados** a ferramenta será executada.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FLBVRXjyHvhcdYorHllal%2Fimage.png?alt=media&#x26;token=af1ad421-7729-4617-b09e-50c2b4aa4eff" alt=""><figcaption><p>Imagem 1 - Novo módulo inserido na plataforma.</p></figcaption></figure>

***

### 1️⃣ Nome da Ferramenta

**Campo:** Nome da ferramenta

#### 🎯 Propósito

É o **identificador único** que o modelo de IA utiliza para “chamar” a função externa.\
Esse nome deve ser inequívoco e fácil de interpretar pelo modelo.

#### 📐 Regras de nomenclatura (padrão `snake_case`)

* Utilize apenas:
  * Letras minúsculas
  * Números
  * Sublinhado (`_`)
* ❌ Não utilize:
  * Espaços
  * Letras maiúsculas
  * Caracteres especiais (exceto `_`)

#### ✅ Recomendação

* Use nomes **descritivos e objetivos**
* Prefira o padrão **verbo\_substantivo**

**Exemplos:**

* `get_weather`
* `send_email`
* `search_database`
* `create_order`

***

### 2️⃣ Descrição

**Campo:** Descrição \*

#### 🎯 Propósito

Este é o **campo mais importante** da Tool.\
A descrição é o texto que o modelo de IA lê para decidir **se** e **quando** a ferramenta deve ser utilizada.

Se a descrição for vaga ou ambígua, o modelo pode:

* Não usar a ferramenta quando deveria
* Usá-la em contextos incorretos

#### 🧠 Boas práticas

* Explique claramente **o que a ferramenta faz**
* Descreva **quando ela deve ser utilizada**
* Informe **limitações ou restrições**
* Use linguagem direta e orientada a intenção do usuário

#### ❌ Exemplo ruim

> “Busca dados.”

#### ✅ Exemplo bom

> “Busca a previsão do tempo atual para uma cidade e estado. Deve ser utilizada sempre que o usuário perguntar sobre clima, temperatura ou condições meteorológicas de um local específico.”

***

### 3️⃣ Parâmetros (JSON Schema)

**Campo:** Parâmetros (JSON Schema)

#### 🎯 Propósito

Define a **estrutura de dados em JSON** que o modelo de IA deve gerar como entrada para a função externa.

O modelo irá:

* Interpretar a intenção do usuário
* Gerar automaticamente esse JSON
* Enviar os dados para o fluxo configurado na Tool

***

#### 📦 Formato esperado

Os parâmetros devem seguir o padrão **JSON Schema**, contendo obrigatoriamente:

**🔹 `type`**

* Define o tipo do objeto raiz
* Deve ser sempre:

```json
"type": "object"
```

**🔹 `properties`**

* Lista todos os parâmetros esperados pela função
* Cada propriedade representa um campo que será enviado no JSON

**🔹 `required`**

* Array com os nomes dos campos que são obrigatórios
* Deve conter apenas propriedades definidas em `properties`

***

#### 📌 Exemplo simplificado de JSON Schema

```json
{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "Nome da cidade"
    },
    "state": {
      "type": "string",
      "description": "Sigla do estado"
    }
  },
  "required": ["city", "state"]
}
```

***

### ✨ Gerar JSON Schema automaticamente com IA

Para facilitar a configuração das Ferramentas (Tools), não é necessário escrever o JSON Schema manualmente.\
Você pode utilizar o recurso **Gerar com IA**, que cria o schema automaticamente a partir de uma descrição em linguagem natural.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FrTInmI9iZJVUNgc0TEHu%2Funknown.png?alt=media&#x26;token=f1fdafce-29e3-4222-9fce-60273c88af62" alt=""><figcaption><p>Imagem 2 - Gerando JSONSchema com IA.</p></figcaption></figure>

#### 🧠 Como funciona

A IA analisa a descrição informada e gera um **JSON Schema válido e otimizado**, incluindo:

* Estrutura correta (`type: object`)
* Definição dos parâmetros (`properties`)
* Tipos de dados (`type`)
* Descrições (`description`)
* Campos obrigatórios (`required`)

#### ✅ Passo a passo

1. Clique em **Gerar com IA**
   * O botão fica localizado **acima da área de texto do JSON Schema**.
2. Descreva os parâmetros da ferramenta

   * Na caixa de diálogo, informe:
     * Quais parâmetros a ferramenta precisa
     * Quais são obrigatórios
     * Regras ou restrições (como valores permitidos, enums, formatos, etc.)

   **Exemplo de descrição:**

   > “Uma ferramenta que obtém dados meteorológicos. Ela precisa do nome da cidade como parâmetro obrigatório e de um parâmetro opcional de unidade, que pode ser `celsius` ou `fahrenheit`.”
3. Clique em **Gerar**
   * A IA processará a descrição e preencherá automaticamente o campo de JSON Schema.

#### 🚀 Benefícios

* Evita erros de sintaxe no JSON Schema
* Acelera a configuração da Tool
* Garante um formato compatível com a interpretação do Assistente de IA
* Reduz a necessidade de conhecimento técnico avançado

📌 **Dica:** Após a geração automática, revise o JSON Schema para garantir que ele esteja alinhado exatamente com os dados esperados pelo fluxo configurado na Tool.

Se quiser, posso complementar com:

* exemplos prontos de descrições bem escritas para gerar schemas
* um checklist rápido de validação do schema
* ou um comparativo entre schema manual vs. gerado por IA

***

#### ⚠️ Atenção

* Parâmetros mal definidos podem causar:
  * Erros na execução da Tool
  * Chamadas incompletas
  * Respostas inconsistentes do Assistente de IA
* Sempre alinhe o **JSON Schema** com o que o fluxo realmente espera receber.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FJq9NJXr78TJzA4qhtv9n%2Funknown.png?alt=media&#x26;token=73fc7941-d34d-4c1b-ada0-511aea78c662" alt=""><figcaption><p>Imagem 3 - Configuração de ferramenta MCP</p></figcaption></figure>