> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/gatilho/tool.md).

# Tool

O módulo **Tool** define uma ferramenta — uma função com nome, descrição e parâmetros — que pode ser chamada por uma inteligência artificial para executar uma ação específica, como consultar uma informação ou realizar uma tarefa. Essa ferramenta pode ser usada por um módulo **Agente IA** dentro do próprio Hyperflow, ou disponibilizada para sistemas de IA externos através de um **Servidor MCP**.

A lógica real da ferramenta é construída com os módulos que você conecta **depois** do módulo Tool no fluxo — o Tool é apenas o ponto de entrada.

## 🧭 Como acessar

{% stepper %}
{% step %}
No menu lateral, clique em **Gerenciamento de aplicativos**.
{% endstep %}

{% step %}
Em seguida, clique em **Fluxos**.
{% endstep %}

{% step %}
Abra ou crie um fluxo e acesse a área de trabalho do fluxo.
{% endstep %}

{% step %}
No painel de módulos, localize a categoria **Integração** (identificada pela cor azul).
{% endstep %}

{% step %}
Arraste o módulo **Tool** para a área de trabalho do fluxo.
{% endstep %}
{% endstepper %}

<figure><img src="/files/6HwusrGOJyw3TuAFuHyz" alt=""><figcaption><p>Imagem 1 - Novo módulo inserido na plataforma.</p></figcaption></figure>

## 🔍 Conhecendo o módulo

Ao clicar duas vezes no módulo na área de trabalho do fluxo, um painel de configuração é aberto na lateral da tela.

### 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.

{% hint style="info" %}
Clique em **Gerar com IA** para descrever em poucas palavras o que a ferramenta precisa receber, e deixar que a inteligência artificial monte o schema JSON automaticamente para você.
{% endhint %}

### 🔀 Saída do módulo

O módulo tem uma única saída, que dá início à lógica da ferramenta propriamente dita. Os módulos conectados depois processam a chamada e devem gerar a resposta que será devolvida a quem chamou a ferramenta.

<figure><img src="/files/Ct0jo3BU7zg4nTmn3LXW" alt=""><figcaption><p>Imagem 3 - Configuração de ferramenta MCP</p></figcaption></figure>

## 💡 Caso de uso

**Cenário:** uma empresa quer que seu Agente de IA consiga consultar a previsão do tempo de uma cidade quando o cliente perguntar sobre isso.

**Configuração:**

{% stepper %}
{% step %}
Adicione o módulo **Tool** a um fluxo.
{% endstep %}

{% step %}
No campo **Nome**, defina `consultar_previsao_tempo`.
{% endstep %}

{% step %}
Na **Descrição**, escreva algo como "Consulta a previsão do tempo atual de uma cidade informada".
{% endstep %}

{% step %}
Em **Parâmetros**, use **Gerar com IA** descrevendo "cidade e unidade de temperatura (Celsius ou Fahrenheit)".
{% endstep %}

{% step %}
Conecte a saída do módulo a um módulo de **Requisição HTTP**, que consulta um serviço externo de previsão do tempo e devolve o resultado.
{% endstep %}

{% step %}
No módulo **Agente IA**, na aba de ferramentas, selecione essa Tool para que o agente possa usá-la durante a conversa.
{% endstep %}
{% endstepper %}

**Resultado:** sempre que o cliente perguntar sobre o clima de uma cidade, o Agente de IA identifica a intenção, chama a ferramenta com os dados corretos e responde com a previsão consultada.

## 📌 Dicas úteis

* Escreva descrições objetivas — elas são o principal critério que a inteligência artificial usa para saber quando chamar a ferramenta.
* Use o botão **Gerar com IA** para economizar tempo ao montar o schema de parâmetros.
* Se remover ou renomear um módulo Tool que já está sendo usado por um Agente IA ou por um Servidor MCP, esses locais deixam de encontrar a ferramenta — revise essas referências antes de fazer alterações.
* Uma mesma Tool pode ser usada tanto por um Agente IA interno quanto disponibilizada externamente através de um Servidor MCP.

## 📝 Resumo

* O módulo **Tool** define uma ferramenta (nome, descrição e parâmetros) que pode ser chamada por uma inteligência artificial.
* A lógica da ferramenta é implementada pelos módulos conectados após o Tool no fluxo.
* Pode ser usada por um módulo **Agente IA** ou exposta a sistemas externos através de um **Servidor MCP**.
* O botão **Gerar com IA** ajuda a montar automaticamente o schema de parâmetros.