# 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="/files/6HwusrGOJyw3TuAFuHyz" 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="/files/NVAuHty3sIYOCWnnLFlD" 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="/files/Ct0jo3BU7zg4nTmn3LXW" alt=""><figcaption><p>Imagem 3 - Configuração de ferramenta MCP</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.hyperflow.global/docs/builder-de-chatbots/gatilho/tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.