> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ferramentas

> Catálogo das tools expostas pelo servidor MCP da Morada.ai, agrupadas por domínio.

## Visão geral

O servidor MCP `morada-platform` expõe **14 ferramentas** organizadas por domínio. A primeira chamada de qualquer fluxo deve ser `list_workspaces` para descobrir o `workspaceId` usado pelas demais.

| Domínio        | Ferramentas                                                            | Escopo                                              |
| -------------- | ---------------------------------------------------------------------- | --------------------------------------------------- |
| Workspaces     | `list_workspaces`                                                      | —                                                   |
| Conversas      | `list_conversations`, `get_conversation`, `list_conversation_messages` | `conversations:view`                                |
| Deals          | `list_deals`, `get_deal`                                               | `deals:view`                                        |
| Agentes        | `list_agents`, `get_agent`                                             | `instances:view`                                    |
| Integrações    | `list_integrations`, `get_integration`                                 | `integrations:view`                                 |
| Analytics      | `get_analytics`                                                        | `dashboard:view`                                    |
| Talk Analytics | `get_talk_analytics`                                                   | `talk-dashboard:view`                               |
| Mensagens      | `send_active_message`                                                  | `talk:edit`                                         |
| Templates      | `list_message_templates`, `create_message_template`                    | `message-templates:view` / `message-templates:edit` |

## Workspaces

### `list_workspaces`

Lista todos os workspaces (partners) aos quais o usuário autenticado tem acesso. **Primeiro passo de qualquer fluxo** — o `id` retornado aqui é usado como `workspaceId` em todas as outras tools.

**Retorno:** array de workspaces com `id`, `name` e `role`.

## Conversas

### `list_conversations`

Lista conversas de um workspace com filtros opcionais por status, intervalo de datas, agente, tags ou busca por pessoa. Resultado paginado.

**Parâmetros principais:** `workspaceId`, `status`, `dateFrom`, `dateTo`, `agentId`, `tags`, `search`, `limit`, `offset`.

### `get_conversation`

Retorna os detalhes completos de uma conversa específica: pessoa, agente atribuído, tags, status e timestamps.

**Parâmetros:** `workspaceId`, `conversationId`.

### `list_conversation_messages`

Lista as mensagens de uma conversa com sanitização automática (imagens são marcadas, mensagens longas são truncadas em 2000 caracteres). Cada mensagem traz um campo `category` que separa pedido do cliente, resposta da IA, resposta de atendente humano, template e ações internas.

**Parâmetros:** `workspaceId`, `conversationId`, `dateFrom`, `dateTo`, `actor`, `limit`, `offset`.

## Deals

### `list_deals`

Lista deals de um workspace com filtros por `status` (`open`, `won`, `lost`, `closed`), data de criação e busca por nome ou telefone da pessoa.

**Parâmetros:** `workspaceId`, `status`, `dateFrom`, `dateTo`, `search`, `limit`, `offset`.

### `get_deal`

Retorna o contexto completo de um deal: pessoa, produtos, logs de etapas, rastreio de origem e usuário responsável.

**Parâmetros:** `workspaceId`, `dealId`.

## Agentes (Mia)

### `list_agents`

Lista todos os agentes (bots/instâncias) de um workspace. Retorna `id`, `name`, `type` e `partnerId`.

**Parâmetros:** `workspaceId`.

### `get_agent`

Retorna a configuração de um agente: tipo, instruções e demais propriedades. Use o parâmetro `fields` para pedir o valor completo de chaves específicas.

**Parâmetros:** `workspaceId`, `agentId`, `fields` (opcional).

## Integrações

### `list_integrations`

Lista todas as integrações (partner connections) configuradas em um workspace. Retorna `id`, `connectorCode`, `active` e metadados do conector.

**Parâmetros:** `workspaceId`.

### `get_integration`

Retorna detalhes de uma integração específica: conector, status ativo e propriedades de configuração.

**Parâmetros:** `workspaceId`, `integrationId`.

## Analytics

### `get_analytics`

Retorna KPIs do dashboard para um workspace em um intervalo de datas: volume de conversas, métricas de funil, tempos de resposta e indicadores de atividade de agentes.

**Parâmetros:** `workspaceId`, `from` (ISO), `to` (ISO), `timezone` (opcional, ex.: `America/Sao_Paulo`).

### `get_talk_analytics`

Retorna as métricas do dashboard do Talk (atendimento humano), uma seção por chamada: `kpis` (atendimentos criados, tempo até atribuição, tempo até 1ª resposta, tempo médio de atendimento e CSAT, com comparativo do período anterior), `tickets-by-day`, `status-distribution`, `tickets-by-attendant`, `times-by-day`, `csat`, `attendants`, `presence-status-history` e `presence-current`.

Aceita filtro por fila e por atendentes. A seção `queues` lista o catálogo de filas do workspace (`id`, `name`, `status`) para resolver nomes em ids; os ids de atendente vêm do campo `id` da seção `attendants`.

**Parâmetros:** `workspaceId`, `section`, `from` (ISO, inclusivo), `to` (ISO, exclusivo), `queueIds` (opcional, máx. 20), `attendantUserIds` (opcional, máx. 50).

## Mensagens

### `send_active_message`

Envia uma mensagem ativa (outbound) no WhatsApp usando um **template aprovado pela Meta**, via um agente com canal WhatsApp ativo. Cria ou retoma uma conversa com o destinatário.

<Warning>
  Operação de escrita que envia uma mensagem real. O assistente deve confirmar telefone, template e variáveis antes de executar.
</Warning>

**Parâmetros:** `workspaceId`, `agentId`, `templateName`, `phoneNumber`, `recipientName` (opcional), `email` (opcional), `replacements` (opcional).

**Retorno:** `success` e `conversationId`.

## Templates de mensagem

### `list_message_templates`

Lista os templates do WhatsApp disponíveis para um agente, consultando a Meta Graph API. Retorna nome, status (`APPROVED`, `PENDING`, etc.), idioma, categoria e componentes.

**Parâmetros:** `workspaceId`, `agentId`, `name` (filtro opcional).

### `create_message_template`

Cria um novo template de mensagem na conta do WhatsApp Business via Meta Graph API.

<Warning>
  Operação de escrita. O template entra em **revisão da Meta** antes de poder ser usado.
</Warning>

**Parâmetros:** `workspaceId`, `agentId`, payload de template no formato esperado pela Meta.

## Fluxos recomendados

### Investigar uma conversa

```
list_workspaces
  → list_conversations (com filtros)
    → get_conversation (id específico)
      → list_conversation_messages
```

### Mapear agentes

```
list_workspaces
  → list_agents
    → get_agent (informações básicas)
```

### Disparar uma mensagem ativa

```
list_workspaces
  → list_agents (escolher agente com Meta)
    → list_message_templates (escolher template APPROVED)
      → send_active_message
        → get_conversation (acompanhar)
```

### Relatório de período

```
list_workspaces
  → get_analytics (from / to)
    → list_deals (status=won, dateFrom, dateTo) para drill-down
```

## Boas práticas

<AccordionGroup>
  <Accordion title="Sempre liste antes de agir">
    Use as ferramentas `list_*` para descobrir IDs antes de chamar `get_*`. Isso evita tentativa-e-erro e mantém consistência entre chamadas.
  </Accordion>

  <Accordion title="Confirme operações de escrita">
    Para `send_active_message` e `create_message_template`, sempre apresente ao usuário o que será enviado **antes** de executar.
  </Accordion>

  <Accordion title="Reutilize workspaceId">
    Uma vez descoberto, reutilize o mesmo `workspaceId` em chamadas subsequentes para evitar trocas de contexto.
  </Accordion>

  <Accordion title="Filtre cedo para reduzir tokens">
    Em listas grandes (conversas, deals), use os filtros de data, status e busca para reduzir o payload retornado.
  </Accordion>
</AccordionGroup>