# Referência das ferramentas MCP

> Source: https://eesier.com.br/mcp/ferramentas

O servidor MCP do eesier, em `https://mcp.eesier.com`, expõe 234 ferramentas para qualquer cliente MCP. Esta página é gerada a partir do servidor em execução, então lista exatamente o que o seu agente recebe.

- **Endereço do servidor**: `https://mcp.eesier.com`
- **Transporte**: Streamable HTTP
- **Autenticação**: `Authorization: Bearer <token>`
- **OAuth 2.1**: `/.well-known/oauth-protected-resource`
- **Obter um token**: Console do eesier → Conta → Agentes Externos (MCP) → Gerar Token. Os tokens são revogáveis e valem só para a sua conta.
- **Instruções para o agente**: `https://mcp.eesier.com/SKILL.md`

## Claude Code

```bash
claude mcp add eesier https://mcp.eesier.com/ -t http -H "Authorization: Bearer <TOKEN>"
```

## como a superfície se comporta

- **leitura, escrita, destrutiva** — Toda ferramenta é anotada. Leitura nunca altera nada. Escrita cria ou atualiza. Destrutiva remove ou cancela algo — trate como irreversível e confirme com a pessoa antes.
- **whoami primeiro** — Chame whoami no início de toda sessão. Ela devolve o perfil da conta, o plano e o timezone_offset_utc_hours, necessário para ler qualquer data corretamente.
- **paginação** — As ferramentas de listagem recebem page (começando em 0) e page_size (padrão 20, teto de 100) e devolvem o total junto com as linhas.
- **datas** — Toda data volta em UTC no formato ISO 8601 (2026-01-31T14:05:00Z). Os filtros de data também aceitam datas ISO.
- **erros** — Uma chamada que falha devolve um objeto JSON com um campo error explicando o que aconteceu, e não um erro HTTP. Leia e aja sobre ele — não tente de novo às cegas.
- **plano ativo** — Algumas ferramentas de escrita exigem plano ativo (pago ou teste). Elas devolvem uma mensagem clara dizendo isso, em vez de falhar em silêncio.
- **search_knowledge antes de responder** — Qualquer dúvida sobre como a própria plataforma funciona passa primeiro por search_knowledge — ela lê a base de conhecimento do eesier.
- **colocar em dia** — list_account_events é um feed com cursor do que aconteceu desde a última verificação. what_changed_since cobre o mesmo terreno em forma de resumo narrado.
- **nomes estáveis** — O nome da ferramenta é o contrato, e cada entrada desta página tem link próprio — dá para mandar alguém direto para uma ferramenta específica.

## as ferramentas

### Sessão

Identifica a conta conectada e lê as notificações pendentes. whoami é a primeira chamada de toda sessão — devolve o perfil, o plano e o fuso horário da conta.

#### `acknowledge_notification` (escrita)

Confirma o recebimento de uma notificação que você já exibiu ao usuário — ela deixa de aparecer em list_pending_notifications para você. Isso é apenas um marcador do lado do agente: a entrega da notificação ao usuário pela própria plataforma não é afetada.

| Parâmetros | | |
|---|---|---|
| `notification_id` | integer, obrigatório | ID da notificação (de list_pending_notifications) |

#### `list_notification_history` (leitura)

Lista as notificações do sistema passadas e pendentes do cliente (mais recentes primeiro, paginado) — incluindo aquelas já processadas pela plataforma ou já reconhecidas. Use list_pending_notifications para apenas as novas, ainda não vistas.

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Notificações por página (padrão 20, máximo 100) |

#### `list_pending_notifications` (leitura)

Lista todas as notificações do sistema pendentes (não processadas) na fila para o cliente. Estas são mensagens de aviso que a plataforma quer que o usuário veja — atualizações da plataforma ou confirmações de ações que ainda não foram apresentadas. Apresente-as ao usuário; você não pode marcá-las como processadas — elas permanecem na fila até que a plataforma as limpe internamente. Ordenadas pelas mais antigas primeiro. Depois de apresentar uma, chame acknowledge_notification para que ela pare de reaparecer aqui; para notificações passadas use list_notification_history.

Parâmetros: —

#### `whoami` (leitura)

Retorna as informações de perfil do cliente autenticado, incluindo nome, telefone, e-mail, idioma, deslocamento de fuso horário em relação ao UTC (em horas, pode ser nulo se não estiver definido), plano de assinatura e elegibilidade para prospecção.

Parâmetros: —

### Leads

Busca, lê, cadastra e atualiza leads. Assume um lead do agente, devolve para ele, interrompe, ou lista tudo que está esperando por uma pessoa agora.

#### `get_lead` (leitura)

Obtém o perfil completo de um lead, incluindo informações de contato, dados da empresa, status de prospecção e histórico de conversas. Os corpos das threads de e-mail são incluídos inline (últimos 50 por direção); a atividade de WhatsApp e voz aparece como contagens — use get_lead_conversation para a linha do tempo completa e mesclada entre canais.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |

#### `list_lead_emails` (leitura)

Lista os e-mails trocados com um lead específico (enviados e recebidos), mais antigos primeiro. Paginado — outbound_total/inbound_total informam o tamanho total da thread. Defina include_bodies=false para uma visualização leve, somente com metadados (datas, assuntos, nomes de anexos).

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | E-mails por direção por página (padrão 20, máximo 100) |
| `include_bodies` | boolean, opcional, padrão `true` | Incluir o corpo completo dos e-mails (padrão true); false retorna apenas metadados |

#### `list_paused_prospecting_leads` (leitura)

Lista leads com a prospecção pausada, incluindo o horário e o motivo da pausa. Paginado por cursor, 50 por página. Use resume_lead_prospecting para continuar ou stop_lead para encerrar o trabalho pendente.

| Parâmetros | | |
|---|---|---|
| `after_lead_id` | integer, opcional, padrão `0` | ID do último lead da página anterior, ou 0 |

#### `list_pending_review` (leitura)

Lista os leads que foram sinalizados para revisão humana pelo agente de prospecção.

Parâmetros: —

#### `pause_lead_prospecting` (escrita)

Pausa temporariamente a prospecção de um lead enquanto aguarda aprovação do proprietário ou uma decisão posterior. Preserva o status e as instruções pendentes. Leads em espera permanecem visíveis no console até serem retomados ou interrompidos. Não é possível retratar uma mensagem já enviada ou uma chamada ativa.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `reason` | string, obrigatório | Motivo da pausa temporária |

#### `register_lead` (escrita)

Registra manualmente um novo lead para que o Blue Button possa prospectá-lo. É necessário um e-mail válido para que o lead seja efetivamente contatado (apenas o telefone só habilita WhatsApp/voz). Faz deduplicação: se já existir um lead com o mesmo e-mail ou telefone, retorna o id desse lead em vez de criar um duplicado. Para trazer muitos leads de uma vez, use import_leads; para um lead indicado por outro lead, use register_referral_lead.

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome do contato |
| `email` | string, opcional | Endereço de email |
| `phone` | string, opcional | Número de telefone |
| `company` | string, opcional | Nome da empresa |
| `status` | string, opcional | Status inicial: Cold (padrão) ou Confirmed |
| `campaign` | string, opcional | Nome da campanha ou campaign_id numérico para atribuir ao lead |

#### `resume_lead_prospecting` (escrita)

Remove a pausa temporária de prospecção de um lead após autorização do proprietário. Preserva as instruções pendentes e o status; outros bloqueios permanecem e são retornados. Sucesso significa que a pausa foi removida, não que uma mensagem foi enviada.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |

#### `return_lead_to_pipeline` (escrita)

Retorna um lead ao pipeline autônomo de prospecção com instruções opcionais para o próximo contato.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `instructions` | string, opcional | Instruções para o próximo contato do agente |
| `next_touch_date` | string, opcional | Quando fazer o próximo contato (data ISO, padrão: agora) |

#### `search_leads` (leitura)

Busca leads por consulta, status, campanha, intervalo de datas, ou data da última mensagem de prospecção. Oferece suporte a ordenação por date_created (padrão), last_prospecting_message, ou status. Retorna resultados paginados. Cada resultado inclui last_outbound_at (data da última mensagem enviada para este lead) e last_inbound_at (data da última resposta deste lead) para que você possa triar a atividade sem abrir a conversa.

| Parâmetros | | |
|---|---|---|
| `query` | string, opcional | Consulta de busca (corresponde a nome, nome da empresa, email) |
| `status` | string, opcional | Filtrar por status: Pending, Cold, Confirmed, Aware, NotInterested, Interested, Closed, Unqualified, Rejected, Gatekeeper |
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico |
| `created_after` | string, opcional | Somente leads criados nesta data ou depois (formato ISO, ex.: 2026-01-01) |
| `created_before` | string, opcional | Somente leads criados nesta data ou antes (formato ISO, ex.: 2026-03-31) |
| `last_prospecting_message_after` | string, opcional | Somente leads que receberam uma mensagem de prospecção nesta data ou depois (formato ISO) |
| `sort_by` | string, opcional | Ordem de classificação: date_created (padrão, mais recentes primeiro), last_prospecting_message (atividade mais recente primeiro), status (por status e depois por data). Valores não reconhecidos usam date_created como padrão. |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Tamanho da página (padrão 20, máximo 100) |
| `has_linkedin` | boolean, opcional | Filtrar pela presença no LinkedIn: true retorna apenas leads que têm uma URL de perfil do LinkedIn, false apenas leads sem uma. Omita para todos os leads. |

#### `send_message_to_lead` (escrita)

Envia um e-mail direto para um lead a partir do endereço Blue Button do cliente. EFEITO COLATERAL: isso assume o controle do lead (remove-o do pipeline autônomo, o mesmo que take_over_lead) — o cliente passa a ser o dono da conversa a partir daí. O e-mail é colocado na fila para envio, não é enviado instantaneamente. Se o cliente só quiser direcionar a abordagem sem assumir o controle, use return_lead_to_pipeline com instruções em vez disso. Para WhatsApp, use send_whatsapp_message_to_lead.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `subject` | string, obrigatório | Assunto do email |
| `body` | string, obrigatório | Corpo do email |

#### `stop_lead` (destrutiva)

Interrompe a prospecção de um lead — o Blue Button finaliza o lead e não envia mais nada. Reversível: recover_lead_to_pipeline o coloca de volta no pipeline com uma abordagem de reengajamento. Contraste: take_over_lead significa que o cliente cuidará pessoalmente do lead; stop_lead significa que ninguém cuidará. Para registrar um resultado final (won/lost/gave_up), use register_lead_outcome — esses resultados interrompem a prospecção e preservam o contexto voluntariamente informado. Seus relatos negotiating/unresponsive apenas atualizam a situação em aberto e não interrompem a abordagem.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `reason` | string, opcional | Motivo da interrupção |

#### `take_over_lead` (escrita)

Assume o controle de um lead — marca como controlado pelo usuário, removendo-o do pipeline de prospecção autônoma (o Blue Button para de entrar em contato; o cliente passa a lidar com ele pelos próprios canais). Para devolver o lead ao Blue Button depois, use recover_lead_to_pipeline (reengajamento suave). Contraste: stop_lead encerra a prospecção sem implicar que o cliente vai cuidar do lead; send_message_to_lead também assume o controle como efeito colateral; return_lead_to_pipeline é a retomada pós-revisão-humana.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |

#### `update_lead` (escrita)

Atualiza o status, goal ou background de um lead. Passe apenas os campos que deseja alterar. Observação: definir um status aqui NÃO interrompe nem pausa a prospecção — para remover o lead do pipeline, use stop_lead (finalizar permanentemente), pause_lead_prospecting (retenção temporária) ou take_over_lead (o cliente cuida pessoalmente). Frozen é reservado para automação e não pode ser atribuído.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `status` | string, opcional | Novo status: Pending, Cold, Confirmed, Aware, NotInterested, Interested, Closed, Unqualified, Rejected, Gatekeeper |
| `goal` | string, opcional | Objetivo de prospecção específico do lead |
| `background` | string, opcional | Contexto de background sobre este lead |

### Operações de lead

Age sobre um lead: envia mensagem de WhatsApp, importa uma lista, reagenda o próximo contato, registra uma indicação ou gera uma apresentação para um lead específico.

#### `create_lead_presentation` (escrita)

Gera uma apresentação estratégica personalizada (PDF) para um lead específico, com base no negócio do cliente e no contexto do lead. É executado de forma síncrona e pode levar um minuto. Retorna a URL do PDF. Se o lead já tiver uma apresentação, retorna a existente. Respeita a opção 'generate custom presentations' do cliente/campanha.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |

#### `import_leads` (escrita)

Importe muitos leads de uma vez. Forneça um customer_file_id existente (um arquivo CSV/Excel/TXT enviado) OU linhas inline (rows_json: um array JSON de objetos com name, email, phone, company — email ou phone obrigatório por linha). A importação é enfileirada e processada em segundo plano (deduplicada contra leads existentes); novos leads entram na prospecção automaticamente. Para um único lead, use register_lead.

| Parâmetros | | |
|---|---|---|
| `customer_file_id` | integer, opcional | Id de um arquivo do cliente já enviado (.csv, .xlsx, .xls, .txt) para importar |
| `rows_json` | string, opcional | Leads embutidos como um array JSON, ex.: [{"name":"Ana","email":"ana@acme.com","phone":"+5511999999999","company":"Acme"}]. Máximo de 500 linhas por chamada. |
| `instructions` | string, opcional | Instruções especiais para extração (mapeamento de colunas, filtros) |
| `status` | string, opcional | Status inicial para os leads importados (ex.: Cold, Confirmed) |
| `preferred_channel` | string, opcional | Canal de primeiro contato: Email ou WhatsApp (aplicado por lead somente quando ele tiver essa informação de contato) |
| `first_message_instructions` | string, opcional | Instruções para a primeira mensagem de prospecção aos leads importados |
| `prospecting_background` | string, opcional | Contexto sobre os leads importados (ex.: 'Leads do workshop de IA da TechConf 2026') |
| `prospecting_goal` | string, opcional | Objetivo de prospecção para os leads importados, substituindo o objetivo em nível de cliente |
| `campaign` | string, opcional | Nome da campanha ou campaign_id numérico para atribuir aos leads importados |

#### `register_referral_lead` (escrita)

Registra um NOVO lead indicado por um lead existente ('fale com o X'). Passa pelo pipeline compartilhado de indicações: deduplicação, verificação de e-mail, cópia de dados da empresa quando same_company, enriquecimento e entrada automática na prospecção. Precisa de pelo menos um e-mail ou um telefone para a pessoa indicada. Requer um plano pago ativo.

| Parâmetros | | |
|---|---|---|
| `referring_lead_id` | integer, obrigatório | ID do lead existente que fez a indicação |
| `lead_name` | string, obrigatório | Nome da pessoa indicada |
| `lead_email` | string, opcional | Email da pessoa indicada |
| `lead_phone` | string, opcional | Telefone da pessoa indicada |
| `same_company` | boolean, opcional, padrão `false` | True quando a pessoa indicada trabalha na MESMA empresa que o lead que fez a indicação (os dados da empresa são copiados) |
| `status` | string, opcional | Status inicial (ex.: Cold, Confirmed) |
| `instructions_for_first_touch` | string, opcional | Instruções para o primeiro contato com o lead indicado |

#### `reschedule_lead_touch` (escrita)

Atualiza a data do próximo contato de prospecção e/ou o canal preferido para um ou mais leads em prospecção ativa, selecionados por IDs de lead explícitos e/ou pelo arquivo do qual foram importados. Definir next_touch_date como agora faz com que cada lead seja contatado o quanto antes. Leads que a fila de prospecção não pegaria (nunca iniciados, finalizados, aguardando revisão, assumidos, rejeitados, ou congelados sem uma resposta mais recente) são ignorados e reportados.

| Parâmetros | | |
|---|---|---|
| `lead_ids` | string, opcional | IDs de leads separados por vírgula para atualizar (opcional se imported_from_file_id for fornecido) |
| `imported_from_file_id` | integer, opcional | Atualiza todo lead em prospecção ativa importado deste id de arquivo do cliente |
| `next_touch_date` | string, opcional | Nova data/hora do próximo contato em UTC (formato ISO). Informe a hora UTC atual para contatar o quanto antes. Omita para manter o agendamento de cada lead. |
| `preferred_channel` | string, opcional | Novo canal preferido de primeiro contato: Email ou WhatsApp (aplicado apenas onde o lead for alcançável nesse canal) |

#### `send_whatsapp_message_to_lead` (escrita)

Envia uma mensagem de WhatsApp direta para um lead no número de prospecção do cliente. O comportamento espelha o do agente no aplicativo: se o controle do lead NÃO foi assumido, a mensagem fica reservada como instruções para o próximo contato e é entregue no próximo contato natural de prospecção do lead (o controle do lead NÃO é assumido). Se o controle do lead FOI assumido e sua janela de atendimento de WhatsApp de 24h está aberta (o lead enviou mensagem nas últimas 24h), a mensagem é enviada agora, ao pé da letra; se a janela estiver fechada, o envio é recusado (política do WhatsApp) — use e-mail via send_message_to_lead em vez disso. Requer uma linha de WhatsApp de prospecção ativa (register_whatsapp_line).

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `message` | string, obrigatório | A mensagem a ser entregue, escrita exatamente como deve chegar ao lead |
| `attachment_url` | string, opcional | URL https absoluta opcional de um arquivo para enviar como mensagem de mídia do WhatsApp após o texto |

### Desfechos

Fecha o ciclo: registra o que aconteceu com um lead, responde a uma pergunta que ele fez, recupera ele para o pipeline ou lê o histórico do seu ciclo de vida.

#### `answer_lead_question` (escrita)

Salva a resposta do cliente para uma pergunta que um lead fez anteriormente e que a plataforma não conseguiu responder (preço, área de entrega, especificações, processo...). Enfileira respostas rastreadas para os leads elegíveis que estão aguardando. A reutilização como conhecimento do negócio requer aprovação explícita do proprietário via reusable=true; caso contrário, a resposta é apenas para os leads em espera. Passe open_question_id quando conhecido; caso contrário, passe question_text.

| Parâmetros | | |
|---|---|---|
| `answer_text` | string, obrigatório | A resposta do cliente, em suas próprias palavras |
| `open_question_id` | integer, opcional | ID da pergunta em aberto que está sendo respondida, quando conhecido |
| `question_text` | string, opcional | O texto da pergunta — obrigatório quando nenhum open_question_id for fornecido |
| `reusable` | boolean, opcional, padrão `false` | True somente com aprovação explícita do proprietário para reutilizar este fato para leads futuros |
| `expected_answer_id` | integer, opcional | ID da resposta atual ao corrigir uma resposta |
| `valid_until` | string (ISO 8601), opcional | Expiração em UTC, quando aplicável |
| `request_id` | string, opcional | UUID estável reutilizado em uma nova tentativa |

#### `list_lead_lifecycle_events` (leitura)

Lista o histórico de ciclo de vida/desfecho de um lead específico (desfecho registrado, recuperado, check-ins silenciados, perguntas respondidas, desfechos de reuniões...), mais recentes primeiro. A trilha de auditoria somente-acréscimo por trás de register_lead_outcome e suas irmãs.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `limit` | integer, opcional, padrão `50` | Número máximo de eventos a retornar (padrão 50, máximo 200) |

#### `mute_lead_check_ins` (escrita)

Silencia ou posterga os lembretes de resultado de um lead. Para solicitações de "me lembre depois", defina snooze_days; use 7 se nenhuma duração for informada. Omita snooze_days para interromper os lembretes. Não altera o resultado nem o estado do pipeline.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `reason` | string, opcional | Por que o cliente quer parar de ouvir falar sobre este lead, com as próprias palavras |
| `snooze_days` | integer, opcional | Dias para adiar em vez de silenciar permanentemente (1-365); use 7 para lembrar mais tarde sem uma duração |

#### `recover_lead_to_pipeline` (escrita)

Traz DE VOLTA para o pipeline autônomo de prospecção um lead que o cliente havia assumido pessoalmente (ou desistido), com um enquadramento de reengajamento suave (o lead já conhece o negócio). Use esta ferramenta — e NÃO return_lead_to_pipeline — quando o cliente assumiu PESSOALMENTE o lead ou parou de buscá-lo e agora quer que o Blue Button o retome. Recusa leads descadastrados e leads com um resultado won/lost já registrado. O primeiro contato de reengajamento acontece após um pequeno atraso.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `owner_context` | string, opcional | Contexto que o cliente deu para a recuperação, com as próprias palavras (ex.: 'ele pediu para conversar depois das férias') |

#### `register_lead_outcome` (escrita)

Registra o relato do cliente sobre um lead: won (venda concluída), lost (o LEAD recusou comprar), gave_up (o PROPRIETÁRIO desistiu explicitamente), negotiating (negociações em andamento) ou unresponsive (o lead parou de responder). Apenas won/lost/gave_up são resultados finais e interrompem a prospecção. Negotiating/unresponsive mantêm o resultado final como desconhecido e não iniciam nem interrompem a abordagem. Não infira uma perda ou desistência do proprietário a partir de silêncio ou de uma formulação vaga; esclareça a ambiguidade. Preserve qualquer motivo/contexto voluntariamente informado em cada situação, sem inventar ou exigir um. O valor do negócio é apenas para uma venda ganha quando informado voluntariamente; nunca pergunte por ele.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `outcome` | string, obrigatório | A situação: 'won', 'lost', 'gave_up', 'negotiating', ou 'unresponsive' |
| `reason` | string, opcional | O motivo/contexto voluntário do cliente para qualquer uma das cinco situações; não invente nem exija isso |
| `deal_value_brl` | number, opcional | Valor do negócio em BRL — APENAS quando o cliente mencionou explicitamente um valor |

### Reuniões

Lista as reuniões marcadas com leads, confirma ou cancela, e registra quem realmente compareceu.

#### `cancel_lead_meeting` (destrutiva)

Cancela uma reunião do lado do cliente e envia o lead de volta ao pipeline de prospecção, para que o executor comunique o cancelamento no próximo contato.

| Parâmetros | | |
|---|---|---|
| `meeting_id` | integer, obrigatório | Id da reunião a ser cancelada |
| `next_touch_date` | string, obrigatório | Quando o executor deve reengajar o lead sobre o cancelamento (ISO 8601 UTC, geralmente dentro de algumas horas) |
| `reason` | string, opcional | Motivo de cancelamento opcional — anexado às notas da reunião e incluído nas instruções de próximo contato |
| `additional_instructions` | string, opcional | Instruções extras opcionais de próximo contato para o executor, escritas no idioma do cliente |

#### `confirm_lead_meeting` (escrita)

Confirma uma reunião do lado do cliente (chame quando o cliente aceitar uma reunião proposta pelo lead). Registra a aceitação do cliente.

| Parâmetros | | |
|---|---|---|
| `meeting_id` | integer, obrigatório | Id da reunião que o cliente está confirmando |

#### `list_lead_meetings` (leitura)

Lista as reuniões entre o cliente e seus leads. Opcionalmente, filtre por um lead específico, inclua reuniões canceladas, ou inclua reuniões passadas.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, opcional | ID do lead opcional para filtrar |
| `include_cancelled` | boolean, opcional, padrão `false` | Incluir reuniões canceladas (padrão false) |
| `include_past` | boolean, opcional, padrão `true` | Incluir reuniões passadas dos últimos 30 dias (padrão true). Defina false para somente as futuras. |

#### `update_lead_meeting_attendance` (escrita)

Registra a presença em uma reunião que já aconteceu — se o cliente e/ou o lead compareceram, além de notas de resultado opcionais. Passe pelo menos um campo.

| Parâmetros | | |
|---|---|---|
| `meeting_id` | integer, obrigatório | Id da reunião a ser atualizada |
| `has_customer_attended` | boolean, opcional | Se o cliente compareceu |
| `has_lead_attended` | boolean, opcional | Se o lead compareceu |
| `notes` | string, opcional | Notas opcionais sobre o resultado — anexadas às notas existentes |

### Inteligência de timing

Lê os sinais de timing coletados para um lead — quando esse tipo de contato costuma responder.

#### `get_lead_timing_intelligence` (leitura)

Obtém a inteligência de timing de um lead: os melhores horários para contatá-lo (por dia da semana, no horário local do lead), quando o lead historicamente responde, e o tempo médio de resposta dele. Construído a partir do histórico deste lead, recorrendo ao setor dele, a este cliente, e depois aos dados de toda a plataforma (o campo source indica qual). Use isso para cronometrar os toques de send_message_to_lead / return_lead_to_pipeline.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |

### Conversas

Lê o que foi realmente dito. Linha do tempo completa de um lead em todos os canais, a thread de WhatsApp isolada, ou uma busca por significado em todas as conversas de uma vez.

#### `get_lead_conversation` (leitura)

Obtém a linha do tempo completa da conversa de um lead entre canais — e-mail, WhatsApp e chamadas de voz — mesclada cronologicamente, com cada item marcado com seu canal e direção. Paginado. Esta é a única ferramenta que mostra a conversa INTEIRA como o lead a vivenciou; para um único canal, use list_lead_emails ou list_lead_whatsapp_messages.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `30` | Itens por página (padrão 30, máximo 100) |
| `order` | string, opcional, padrão `newest_first` | Ordenação: newest_first (padrão) ou oldest_first |
| `include_transcripts` | boolean, opcional, padrão `false` | Incluir transcrições completas das chamadas de voz (padrão false — apenas o resumo do resultado) |

#### `list_lead_whatsapp_messages` (leitura)

Lista as mensagens do WhatsApp trocadas com um lead específico (enviadas e recebidas), mais antigas primeiro. Paginado — outbound_total/inbound_total informam o tamanho total da thread. Defina include_bodies=false para uma visualização leve, somente com metadados. Para os e-mails do lead use list_lead_emails; para a linha do tempo combinada de e-mail+WhatsApp+voz use get_lead_conversation.

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Mensagens por direção por página (padrão 20, máximo 100) |
| `include_bodies` | boolean, opcional, padrão `true` | Incluir o corpo completo das mensagens (padrão true); false retorna apenas metadados |

#### `search_lead_conversations` (leitura)

Busca semântica em TODAS as conversas de LEAD do cliente — e-mails de leads e mensagens de WhatsApp de leads — por significado, não por palavras-chave (ex.: 'leads que perguntaram sobre preço', 'objeções sobre duração de contrato'). Retorna trechos com lead_id; busque as conversas completas via get_lead_conversation / list_lead_emails / list_lead_whatsapp_messages. Opcionalmente, restrinja a um lead ou um canal. NÃO é para o próprio chat do cliente com seu agente Blue Button — isso é search_my_agent_conversation.

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | O que buscar, formulado por significado (qualquer idioma) |
| `lead_id` | integer, opcional | Restringir à conversa de um lead (opcional) |
| `channel` | string, opcional | Restringir canal: email, whatsapp, email_inbound, email_outbound, whatsapp_inbound, whatsapp_outbound (opcional; padrão = todos) |
| `top_k` | integer, opcional, padrão `10` | Máximo de resultados (padrão 10, máximo 25) |
| `min_score` | number, opcional | Pontuação mínima de similaridade 0..1 (opcional) |

#### `search_my_agent_conversation` (leitura)

Busca semântica na PRÓPRIA conversa passada do cliente com seu agente Blue Button (o assistente de WhatsApp com quem ele conversa) — use para lembrar o que o cliente discutiu, decidiu, ou pediu anteriormente. NÃO é para conversas de leads — isso é search_lead_conversations.

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | O que buscar, formulado por significado (qualquer idioma) |
| `top_k` | integer, opcional, padrão `5` | Número máximo de resultados (padrão 5, máximo 10) |

### Caixa de entrada

O e-mail da própria conta, como um cliente de e-mail completo: pastas e conversas, busca híbrida por significado e por texto exato, ler / favoritar / arquivar / excluir em lote, respostas na mesma conversa com o encadeamento correto e novas mensagens para qualquer destinatário.

#### `delete_mailbox_messages` (destrutiva)

Move uma ou mais mensagens para a lixeira (uma exclusão reversível — restore_mailbox_messages as traz de volta, e list_mailbox_messages com folder=trash as lista). SEGURANÇA: uma mensagem enviada que ainda está na fila e não saiu é RECUSADA, porque excluí-la cancelaria o envio silenciosamente; a linha retorna com blocked_reason="pending_send" (ou "pending_processing" para uma mensagem recebida ainda em classificação). Passe force_cancel_pending_send=true apenas quando o cliente realmente quiser cancelar esse envio. Aceita uma lista de handles de mensagens separados por vírgula (máximo 100 por chamada).

| Parâmetros | | |
|---|---|---|
| `message_ids` | string, obrigatório | Identificadores de mensagem separados por vírgula, ex.: "in-42,out-9" (máximo 100) |
| `force_cancel_pending_send` | boolean, opcional, padrão `false` | Excluir mesmo quando isso cancela um envio na fila ou uma classificação pendente (padrão false) |

#### `get_mailbox_message` (leitura)

Lê uma mensagem por completo pelo seu handle ("in-42" / "out-42") — assunto, corpo, contraparte, datas, estado na caixa de entrada e seus anexos (nome do arquivo + URL pública). Para a conversa inteira ao redor dela, use get_mailbox_thread.

| Parâmetros | | |
|---|---|---|
| `message_id` | string, obrigatório | Identificador de mensagem de um resultado de lista ou busca, ex.: "in-42" |
| `include_attachments` | boolean, opcional, padrão `true` | Incluir a lista de anexos (padrão true) |

#### `get_mailbox_overview` (leitura)

A caixa de entrada em um relance: o endereço de email Blue Button do cliente, se está configurado, e as contagens de unread / inbox / starred / archived / sent / trash mais os timestamps das mensagens mais recentes. As contagens vêm em duas unidades e AMBAS são reportadas: *_conversations conta threads e sempre é igual ao total que list_mailbox_messages retorna para a mesma pasta e filtro, enquanto *_messages conta os emails individuais dentro delas — uma caixa de entrada com 3 conversations pode conter 40 messages, então nunca compare as duas. Chame isso primeiro — responde "há algo me esperando?" sem paginar nenhuma lista. Para as próprias mensagens use list_mailbox_messages.

Parâmetros: —

#### `get_mailbox_thread` (leitura)

Abre toda a conversa à qual uma mensagem pertence — todas as mensagens recebidas e enviadas mescladas da mais antiga para a mais recente. Uma mensagem vinculada a um lead abre todo o histórico de emails do lead; uma mensagem sem lead abre a conversa reconstruída a partir do endereço da contraparte e do assunto normalizado. Paginado (total_messages informa o tamanho total da conversa) para que uma conversa longa nunca sobrecarregue o contexto. Defina mark_read=true para limpar o estado de não lida das mensagens recebidas na página, exatamente como abrir a conversa no console faz.

| Parâmetros | | |
|---|---|---|
| `message_id` | string, obrigatório | Identificador de mensagem de um resultado de lista ou busca, ex.: "in-42" |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `50` | Mensagens por página (padrão 50, máximo 200) |
| `mark_read` | boolean, opcional, padrão `false` | Marcar como lidas as mensagens recebidas nesta página (padrão false) |

#### `list_mailbox_contacts` (leitura)

Lista as pessoas para quem o cliente pode enviar email — todo lead com um endereço confirmado ou mais avançado e que ainda pode receber email, em ordem alfabética e paginado. Use para encontrar o destinatário certo antes de send_mailbox_message. Este é o seletor de composição, não a lista completa de leads — para isso, use search_leads.

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `50` | Contatos por página (padrão 50, máximo 200) |

#### `list_mailbox_messages` (leitura)

Lista a caixa de entrada uma linha por conversa, da mais recente para a mais antiga — inbox, sent ou trash. filter restringe a inbox a não lidas, com estrela ou arquivadas no console ("all" retorna tudo que não foi excluído, incluindo arquivadas). Paginado: total informa a contagem total de correspondências. Cada linha carrega um handle message_id como "in-42" / "out-42" — passe esse handle para todas as outras ferramentas de caixa de entrada. Defina include_bodies=true para corpos completos em vez do trecho de prévia. Esta é a caixa de entrada inteira, incluindo emails que não pertencem a nenhum lead; para a conversa de email de um único lead, use list_lead_emails.

| Parâmetros | | |
|---|---|---|
| `folder` | string, opcional, padrão `inbox` | Pasta: inbox, sent ou trash (padrão inbox) |
| `filter` | string, opcional, padrão `all` | Filtro: all, unread, starred ou archived (padrão all). unread se aplica somente à caixa de entrada |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Linhas por página (padrão 20, máximo 100) |
| `include_bodies` | boolean, opcional, padrão `false` | Incluir o corpo completo das mensagens (padrão false); false retorna apenas o trecho de prévia |

#### `reply_to_mailbox_message` (escrita)

Responde dentro da conversa à qual uma mensagem pertence — funciona em QUALQUER thread, seja a outra parte um lead ou não. Diferente de send_message_to_lead, isso encadeia corretamente: carrega os headers In-Reply-To e References da mensagem mais recente da thread mais o subject "Re:", então a resposta cai na thread existente do destinatário em vez de iniciar uma nova. EFEITO COLATERAL: em uma thread vinculada a um lead, isso assume o controle do lead (o agente autônomo para de enviar mensagens a ele), adia o próximo contato agendado em uma semana, e o corpo é traduzido para o idioma do lead quando eles diferem — uma resposta a não-lead não faz nada disso e é enviada exatamente como escrita. Recusado quando o destinatário está na blacklist ou cancelou a inscrição. O email é enfileirado para entrega, não enviado instantaneamente. Anexos já devem ser URLs públicas — gere-as com as ferramentas de mídia ou com register_business_file primeiro.

| Parâmetros | | |
|---|---|---|
| `message_id` | string, obrigatório | Identificador de mensagem de qualquer mensagem na conversa a ser respondida, ex.: "in-42" |
| `body` | string, obrigatório | O corpo da resposta, no próprio idioma do cliente |
| `attachment_urls` | string, opcional | URLs públicas separadas por vírgula para anexar (opcional, máximo 5 arquivos, 20MB no total) |

#### `restore_mailbox_messages` (escrita)

Restaura uma ou mais mensagens da lixeira. AVISO: restaurar uma mensagem enviada que foi excluída antes de sair coloca-a de volta na fila de envio e ela SERÁ entregue — a fila só ignora linhas excluídas. Aceita uma lista de handles de mensagens separados por vírgula (máximo 100 por chamada).

| Parâmetros | | |
|---|---|---|
| `message_ids` | string, obrigatório | Identificadores de mensagem separados por vírgula, ex.: "in-42,out-9" (máximo 100) |

#### `search_mailbox` (leitura)

Pesquisa a caixa de entrada por significado E por texto exato — correspondências semânticas sobre os corpos de mensagens indexados combinadas com correspondências exatas no endereço da contraparte, nome de exibição e o nome / email / empresa do lead. Retorna uma linha por conversa correspondente, mais relevante primeiro, paginado. Requer no mínimo 3 caracteres. Isto pesquisa a própria caixa de entrada do cliente, incluindo emails sem lead; para pesquisar dentro das conversas de um único lead, use search_lead_conversations, e para a conversa do próprio cliente com seu agente Blue Button, use search_my_agent_conversation.

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | O que buscar, em qualquer idioma — expresso pelo significado ou como um nome / endereço exato |
| `folder` | string, opcional, padrão `inbox` | Pasta: inbox ou sent (padrão inbox) |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `10` | Linhas por página (padrão 10, máximo 50) |
| `include_bodies` | boolean, opcional, padrão `false` | Incluir o corpo completo das mensagens (padrão false) |

#### `send_mailbox_message` (escrita)

Envia um novo email do endereço Blue Button do cliente para qualquer endereço — não precisa ser um lead existente. Defina register_as_lead=true para também registrar um destinatário desconhecido como lead, de modo que a conversa seja rastreada. EFEITO COLATERAL: quando o destinatário É um lead existente, isso assume o controle desse lead (o agente autônomo para de enviar mensagens a ele). Recusado quando o destinatário está na blacklist ou cancelou a inscrição, seja lead ou não. O email é enfileirado para entrega, não enviado instantaneamente. Para responder dentro de uma conversa existente, use reply_to_mailbox_message, que encadeia a resposta corretamente.

| Parâmetros | | |
|---|---|---|
| `to_address` | string, obrigatório | Endereço de email do destinatário |
| `subject` | string, obrigatório | Assunto do email; quando em branco, um padrão é gerado |
| `body` | string, opcional | O corpo da mensagem, no idioma do próprio cliente |
| `register_as_lead` | boolean, opcional, padrão `false` | Registra um destinatário desconhecido como novo lead (padrão false) |
| `attachment_urls` | string, opcional | URLs públicas separadas por vírgula para anexar (opcional, máximo 5 arquivos, 20MB no total) |

#### `set_mailbox_messages_archived` (escrita)

Arquiva ou desarquiva uma ou mais mensagens, em qualquer pasta. Arquivar oculta uma mensagem da lista padrão da caixa de entrada, mas a mantém totalmente pesquisável e legível — não é uma exclusão. Aceita uma lista de handles de mensagens separados por vírgula (máximo 100 por chamada).

| Parâmetros | | |
|---|---|---|
| `message_ids` | string, obrigatório | Handles de mensagens separados por vírgula, ex.: "in-42,out-9" (máximo 100) |
| `archived` | boolean, opcional, padrão `true` | true arquiva, false desarquiva (padrão true) |

#### `set_mailbox_messages_read` (escrita)

Marca uma ou mais mensagens recebidas como lidas ou não lidas. Aceita uma lista de handles de mensagens separados por vírgula (máximo 100 por chamada), de modo que uma triagem inteira seja uma única chamada. Emails enviados não têm estado de leitura e são rejeitados.

| Parâmetros | | |
|---|---|---|
| `message_ids` | string, obrigatório | Handles de mensagens separados por vírgula, ex.: "in-42,in-43" (máximo 100) |
| `read` | boolean, opcional, padrão `true` | true marca como lida, false marca como não lida (padrão true) |

#### `set_mailbox_messages_starred` (escrita)

Marca ou desmarca com estrela uma ou mais mensagens, em qualquer pasta. Aceita uma lista de handles de mensagens separados por vírgula (máximo 100 por chamada). Marcar com estrela é uma definição sem alternância: passar starred=true duas vezes deixa a mensagem com estrela.

| Parâmetros | | |
|---|---|---|
| `message_ids` | string, obrigatório | Handles de mensagens separados por vírgula, ex.: "in-42,out-9" (máximo 100) |
| `starred` | boolean, opcional, padrão `true` | true marca com estrela, false remove a estrela (padrão true) |

### Campanhas

Roda trilhas de prospecção separadas para produtos ou mercados diferentes: cria, pausa, retoma, renomeia, arquiva, compara resultados e move leads entre elas.

#### `archive_campaign` (destrutiva)

Arquiva uma campanha permanentemente. Todo lead nela tem seu vínculo com a campanha removido e volta para a prospecção padrão, e a campanha deixa de aparecer nas listas de campanhas. Use pause_campaign para uma interrupção temporária.

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |

#### `compare_campaigns` (leitura)

Compara duas campanhas lado a lado: configuração e estatísticas de leads.

| Parâmetros | | |
|---|---|---|
| `name_a` | string, obrigatório | Nome da primeira campanha |
| `name_b` | string, obrigatório | Nome da segunda campanha |

#### `create_campaign` (escrita)

Cria uma nova campanha de prospecção. Name e business_name são obrigatórios. Cada campanha é ISOLADA — ela NÃO herda nenhum campo dos padrões em nível de cliente, portanto preencha todos os campos relevantes no momento da criação.

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha (único por cliente) |
| `business_name` | string, obrigatório | Nome do negócio para esta campanha |
| `business_description` | string, opcional | Descrição do negócio para esta campanha — o produto/serviço que ela representa. OBRIGATÓRIO quando a campanha representa um produto diferente do negócio principal do cliente, caso contrário o texto de prospecção não terá contexto sobre o produto. |
| `business_website` | string, opcional | URL do site do negócio para esta campanha |
| `icp` | string, opcional | Perfil de cliente ideal |
| `cnae_filter` | string, opcional | Códigos CNAE a incluir, separados por vírgula |
| `cnae_exclusion_filter` | string, opcional | Códigos CNAE a excluir, separados por vírgula |
| `instructions` | string, opcional | Instruções de prospecção |
| `email_instructions` | string, opcional | Sobreposição de instruções do canal de e-mail — orientação extra aplicada APENAS ao contatar um lead por e-mail para ESTA campanha, aplicada por cima das instruções gerais da campanha (substituição direta da sobreposição de e-mail). |
| `whatsapp_instructions` | string, opcional | Camada de instruções do canal do WhatsApp — orientações extras aplicadas SOMENTE ao contatar um lead pelo WhatsApp nesta campanha, sobrepostas às instruções gerais da campanha (substituição bruta da camada do WhatsApp). |
| `voice_instructions` | string, opcional | Camada de instruções do canal de voz — orientações extras aplicadas SOMENTE em ligações ativas desta campanha, sobrepostas às instruções gerais da campanha (substituição bruta da camada de voz). |
| `goal` | string, opcional | Objetivo de prospecção |
| `lead_qualification_instructions` | string, opcional | Instruções de qualificação de leads — regras sobre COMO avaliar leads em relação ao ICP (requisitos obrigatórios vs. preferências flexíveis, condições de override, regras de tolerância, limites de desqualificação) |
| `human_review_criteria` | string, opcional | Critérios de revisão humana — quando sinalizar um lead para revisão manual em vez de avançar automaticamente |
| `email_display_name` | string, opcional | Substituição do nome de exibição do e-mail para esta campanha (ex: 'Carlos from PrimeAssist'). Deixe em branco para usar o nome de exibição em nível de cliente. |
| `uf_filter` | string, opcional | Códigos de estados brasileiros separados por vírgula (ex.: 'SP,RJ,MG') |
| `city_filter` | string, opcional | Nomes de cidades separados por vírgula |
| `country_filter` | string, opcional | Códigos de país ISO |
| `min_employee_count` | integer, opcional | Número mínimo de funcionários |
| `max_employee_count` | integer, opcional | Número máximo de funcionários |
| `min_annual_revenue` | number, opcional | Receita anual mínima |
| `max_annual_revenue` | number, opcional | Receita anual máxima |
| `company_size_filter` | string, opcional | Portes de empresa separados por vírgula: Micro,Small,Medium,Large |
| `company_type_filter` | string, opcional | Tipos de empresa separados por vírgula para incluir nas buscas de leads: Private, Individual, Government, StateOwned, NonProfit. Vazio = herda o filtro de tipo de empresa do cliente (padrão do cliente = apenas Private — MEI / empresários individuais, governo, estatais e entidades sem fins lucrativos excluídos). |
| `company_audience_filter` | string, opcional | Públicos separados por vírgula para os quais a empresa-alvo vende: B2B, B2C, B2BAndB2C, Government, NonCommercial. Derivado da atividade registrada, então uma campanha voltada a 'empresas B2B' não precisa de lista de CNAE. Pedir B2B também retorna empresas que vendem para ambos, e empresas cuja atividade não dá nenhum sinal nunca são excluídas. Vazio = herda o filtro de público do customer. |
| `lead_generation_active` | boolean, opcional | Se deve gerar automaticamente NOVOS leads para esta trilha. O padrão é true. Defina como false APENAS quando a campanha deve trabalhar SOMENTE com uma lista que o próprio usuário importa e nunca receber leads gerados automaticamente. Os leads existentes continuam sendo prospectados — apenas a aquisição de novos leads é pausada quando false. |

#### `get_campaign` (leitura)

Retorna a configuração completa e as estatísticas de leads de uma campanha específica. Aceita o nome da campanha ou seu campaign_id numérico (conforme retornado por list_campaigns, search_leads, get_lead).

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |

#### `list_campaigns` (leitura)

Lista todas as campanhas de prospecção do cliente com suas estatísticas de leads (total, interested, confirmed, cold, aware, frozen, not interested, taken over, pending review) e métricas de e-mail (e-mails enviados, respostas recebidas, taxa de resposta).

Parâmetros: —

#### `move_leads_to_campaign` (escrita)

Move leads de uma campanha para outra, ou os remove de sua campanha e os retorna à prospecção padrão (sem campanha). Informe o nome da campanha de destino, ou 'default' para remover os leads de qualquer campanha. Opcionalmente, filtre por status do lead.

| Parâmetros | | |
|---|---|---|
| `target_campaign` | string, obrigatório | Nome da campanha de destino ou campaign_id numérico, ou 'default' (ou 'none') para remover os leads de sua campanha e devolvê-los à prospecção padrão |
| `lead_ids` | string, obrigatório | IDs de leads separados por vírgula para mover |
| `status_filter` | string, opcional | Mover apenas leads com este status (opcional) |

#### `pause_campaign` (escrita)

Pausa uma campanha. Os leads dessa campanha não serão processados até que ela seja retomada.

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |

#### `rename_campaign` (escrita)

Renomeia uma campanha.

| Parâmetros | | |
|---|---|---|
| `old_name` | string, obrigatório | Nome atual da campanha |
| `new_name` | string, obrigatório | Novo nome da campanha |

#### `resume_campaign` (escrita)

Retoma uma campanha pausada.

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |

#### `set_campaign_lead_generation_active` (escrita)

Alterna se o sistema GERA AUTOMATICAMENTE novos leads para uma campanha. true = gerar novos leads (padrão). false = parar de gerar novos leads — trabalhar apenas a lista existente. INDEPENDENTE de pausar/retomar: uma campanha com lead_generation_active=false mas is_active=true continua prospectando seus leads existentes, apenas sem aquisição de novos leads. Use isso quando o usuário quiser que uma campanha trabalhe APENAS em uma lista que ele mesmo importou.

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |
| `active` | boolean, obrigatório | true para continuar gerando novos leads, false para parar de gerar novos leads (leads existentes continuam sendo prospectados) |

#### `update_campaign` (escrita)

Atualiza a configuração de uma campanha existente. Passe apenas os campos que deseja alterar. Para filtros numéricos (número de funcionários, receita), defina como -1 para limpar.

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome atual da campanha |
| `business_name` | string, opcional | Novo nome do negócio |
| `business_description` | string, opcional | Descrição do negócio |
| `business_website` | string, opcional | Site do negócio |
| `icp` | string, opcional | Perfil de cliente ideal |
| `cnae_filter` | string, opcional | Filtro de inclusão de CNAE |
| `cnae_exclusion_filter` | string, opcional | Filtro de exclusão de CNAE |
| `uf_filter` | string, opcional | Códigos de estado brasileiros separados por vírgula (ex.: 'SP,RJ,MG') |
| `city_filter` | string, opcional | Nomes de cidades separados por vírgula |
| `country_filter` | string, opcional | Filtro de país |
| `instructions` | string, opcional | Instruções de prospecção |
| `email_instructions` | string, opcional | Camada de instruções do canal de e-mail — orientação extra aplicada APENAS ao contatar um lead por e-mail para ESTA campanha, sobreposta às instruções gerais da campanha (substituição bruta da camada de e-mail). |
| `whatsapp_instructions` | string, opcional | Overlay de instruções do canal WhatsApp — orientação extra aplicada APENAS ao contatar um lead pelo WhatsApp para ESTA campanha, sobreposta às instruções gerais da campanha (substituição bruta do overlay do WhatsApp). |
| `voice_instructions` | string, opcional | Overlay de instruções do canal de voz — orientação extra aplicada APENAS em chamadas outbound para ESTA campanha, sobreposta às instruções gerais da campanha (substituição bruta do overlay de voz). |
| `goal` | string, opcional | Objetivo de prospecção |
| `strategy` | string, opcional | Estratégia |
| `human_review_criteria` | string, opcional | Critérios de revisão humana |
| `lead_qualification_instructions` | string, opcional | Instruções de qualificação de leads — regras sobre COMO avaliar leads em relação ao ICP (requisitos obrigatórios vs. preferências flexíveis, condições de override, regras de flexibilidade, limiares de desqualificação) |
| `email_display_name` | string, opcional | Nome de exibição do e-mail |
| `min_employee_count` | integer, opcional | Número mínimo de funcionários (-1 para limpar) |
| `max_employee_count` | integer, opcional | Número máximo de funcionários (-1 para limpar) |
| `min_annual_revenue` | number, opcional | Receita anual mínima (-1 para limpar) |
| `max_annual_revenue` | number, opcional | Receita anual máxima (-1 para limpar) |
| `company_size_filter` | string, opcional | Portes de empresa separados por vírgula: Micro,Small,Medium,Large (vazio para limpar) |
| `company_type_filter` | string, opcional | Tipos de empresa separados por vírgula para incluir nas buscas de leads: Private, Individual, Government, StateOwned, NonProfit. Uma string vazia limpa a substituição da campanha e herda o filtro de tipo de empresa do cliente (padrão do cliente = apenas Private — MEI / empresários individuais, governo, estatais e entidades sem fins lucrativos excluídos). |
| `company_audience_filter` | string, opcional | Públicos separados por vírgula para os quais a empresa-alvo vende: B2B, B2C, B2BAndB2C, Government, NonCommercial. Derivado da atividade registrada, então uma campanha voltada a 'empresas B2B' não precisa de lista de CNAE. Pedir B2B também retorna empresas que vendem para ambos. String vazia limpa o override da campanha e herda o filtro de público do customer. |
| `lead_generation_active` | boolean, opcional | Se deve gerar automaticamente NOVOS leads para esta trilha. true = gerar novos leads (padrão para novas campanhas). false = parar de gerar novos leads, trabalhar apenas a lista existente. Independente de pause/resume — quando false a campanha continua prospectando seus leads existentes, apenas não adquire novos. |
| `is_active` | boolean, opcional | Se esta campanha está ou não em execução. false pausa toda a trilha (o mesmo que pause_campaign), true a retoma. |
| `voice_calling_active` | boolean, opcional | Chamada de voz outbound por trilha. true liga para os leads desta trilha, false nunca liga para eles, omitir para manter a configuração atual. Limpe para herdar a configuração de nível de cliente via clear_voice_calling_active. |
| `generate_custom_presentations` | boolean, opcional | Se deve gerar uma apresentação personalizada por lead para esta trilha (true/false) |
| `notify_on_interested` | boolean, opcional | Alertar quando um lead desta trilha demonstrar interesse (true/false) |
| `notify_on_confirmed` | boolean, opcional | Alertar quando um lead desta trilha for confirmado (true/false) |
| `min_founding_date` | string, opcional | Data de fundação da empresa mais antiga a incluir, no formato 'yyyy-MM-dd' (vazio para limpar) |
| `max_founding_date` | string, opcional | Data de fundação da empresa mais recente a incluir, no formato 'yyyy-MM-dd' (vazio para limpar) |

### Configurações de prospecção

A chave geral mais tudo que define quem é contatado e como: segmentação, regras e preferências.

#### `get_prospecting_config` (leitura)

Retorna toda a configuração de prospecção: filtros (CNAE, localização), instruções, objetivo, estratégia, critérios de revisão humana, instruções de qualificação de leads, configurações de notificação, modo e status de ativação.

Parâmetros: —

#### `set_allow_template_whatsapp_messages` (escrita)

Permite ou bloqueia mensagens de template de WhatsApp iniciadas pelo agente para leads. Quando bloqueado, o agente só pode responder a leads que escreveram primeiro, dentro da janela de 24 horas do WhatsApp, e nunca abre uma conversa por template. Respostas de texto livre não são afetadas.

| Parâmetros | | |
|---|---|---|
| `allowed` | boolean, obrigatório | true para permitir mensagens de template iniciadas pelo agente, false para apenas responder |

#### `set_prospecting_active` (escrita)

Ativa ou desativa a prospecção autônoma. Retorna o novo status e as informações de elegibilidade.

| Parâmetros | | |
|---|---|---|
| `active` | boolean, obrigatório | true para ativar, false para desativar |

#### `set_prospecting_preferences` (escrita)

Atualiza as preferências de prospecção: modo (Active/Passive), apresentações personalizadas e configurações de notificação. Passe apenas os campos que deseja alterar.

| Parâmetros | | |
|---|---|---|
| `mode` | string, opcional | Modo de prospecção: 'Active' (buscando leads) ou 'Passive' (pausado até revisão) |
| `generate_presentations` | boolean, opcional | Se deve gerar apresentações personalizadas por lead (true/false) |
| `notification_email` | string, opcional | Endereço de e-mail para receber notificações de prospecção |
| `notify_on_interested` | boolean, opcional | Notificar (in-app/WhatsApp) quando leads demonstrarem interesse (true/false) |
| `notify_on_confirmed` | boolean, opcional | Notificar (in-app/WhatsApp) quando leads forem confirmados (true/false) |
| `notify_on_interested_via_email` | boolean, opcional | Enviar o E-MAIL com a marca da empresa quando leads demonstrarem interesse (true/false) — independente do alerta in-app/WhatsApp |
| `notify_on_confirmed_via_email` | boolean, opcional | Enviar o E-MAIL com a marca da empresa quando leads forem confirmados (true/false) — independente do alerta in-app/WhatsApp |
| `notify_on_first_whatsapp_message` | boolean, opcional | Notificar (aviso único) quando um lead enviar a primeira mensagem no WhatsApp (true/false) |
| `cc_on_interested_lead_emails` | boolean, opcional | Copiar o cliente nos e-mails de lead interessado enviados aos endereços de notificação (true/false) |

#### `set_prospecting_rules` (escrita)

Atualiza as regras de prospecção: instruções para o agente, objetivo de abordagem, estratégia, critérios de revisão humana e instruções de qualificação de leads. Passe apenas os campos que deseja alterar.

| Parâmetros | | |
|---|---|---|
| `instructions` | string, opcional | Instruções sobre como o agente deve prospectar (substituição direta) |
| `goal` | string, opcional | Objetivo desejado da prospecção (ex.: 'agendar uma demonstração', 'marcar uma reunião') |
| `strategy` | string, opcional | Documento de estratégia de prospecção |
| `human_review_criteria` | string, opcional | Critérios para quando escalar leads para revisão humana |
| `lead_qualification_instructions` | string, opcional | Regras sobre COMO avaliar leads em relação ao ICP — quais características são requisitos obrigatórios versus preferências flexíveis, condições de exceção, regras de tolerância, limites de desqualificação. Distinto do ICP em si (quem visar). |
| `email_instructions` | string, opcional | Sobreposição de instruções do canal de e-mail — orientação extra aplicada APENAS ao contatar um lead por e-mail, sobreposta às instruções gerais (substituição direta da sobreposição de e-mail). |
| `whatsapp_instructions` | string, opcional | Sobreposição de instruções do canal de WhatsApp — orientação extra aplicada APENAS ao contatar um lead pelo WhatsApp, sobreposta às instruções gerais (substituição direta da sobreposição de WhatsApp). |
| `voice_instructions` | string, opcional | Sobreposição de instruções do canal de voz — orientação extra aplicada APENAS em ligações ativas, sobreposta às instruções gerais (substituição direta da sobreposição de voz). |
| `email_signature` | string, opcional | Bloco de assinatura exato anexado literalmente a cada e-mail de prospecção. Quando definido, o copywriter não escreve assinatura própria. Envie uma string vazia para limpá-lo e voltar à assinatura padrão somente com o nome. |

#### `set_targeting` (escrita)

Atualiza os filtros de segmentação da prospecção. Passe apenas os campos que deseja alterar. Valores separados por vírgula para campos multivalorados. Para filtros numéricos (número de funcionários, receita), defina como -1 para limpar.

| Parâmetros | | |
|---|---|---|
| `cnae_filter` | string, opcional | Códigos CNAE separados por vírgula a incluir (ex.: '6201,6202,6311') |
| `cnae_exclusion_filter` | string, opcional | Códigos CNAE separados por vírgula a excluir |
| `uf_filter` | string, opcional | Códigos de estado brasileiro separados por vírgula (ex.: 'SP,RJ,MG') |
| `city_filter` | string, opcional | Nomes de cidades separados por vírgula |
| `country_filter` | string, opcional | Códigos de país ISO separados por vírgula (ex.: 'BR,US') |
| `min_employee_count` | integer, opcional | Número mínimo de funcionários (-1 para limpar) |
| `max_employee_count` | integer, opcional | Número máximo de funcionários (-1 para limpar) |
| `min_annual_revenue` | number, opcional | Receita anual mínima (-1 para limpar) |
| `max_annual_revenue` | number, opcional | Receita anual máxima (-1 para limpar) |
| `company_size_filter` | string, opcional | Tamanhos de empresa separados por vírgula: Micro,Small,Medium,Large (vazio para limpar) |
| `company_type_filter` | string, opcional | Tipos de empresa separados por vírgula para incluir nas buscas de leads: Private, Individual, Government, StateOwned, NonProfit. Padrão (vazio) = apenas Private — MEI / empreendedores individuais, governo, estatais e entidades sem fins lucrativos são excluídos. |
| `company_audience_filter` | string, opcional | Públicos separados por vírgula para os quais a empresa-alvo vende: B2B, B2C, B2BAndB2C, Government, NonCommercial. Derivado da atividade registrada da empresa, então um ICP de simplesmente 'empresas B2B' não precisa de lista de CNAE. Pedir B2B também retorna empresas que vendem para ambos, e empresas cuja atividade não dá nenhum sinal nunca são excluídas. Padrão (vazio) = sem filtro de público. |
| `min_founding_date` | string, opcional | Data de fundação mais antiga da empresa a incluir, no formato 'yyyy-MM-dd' (vazio para limpar) |
| `max_founding_date` | string, opcional | Data de fundação mais recente da empresa a incluir, no formato 'yyyy-MM-dd' (vazio para limpar) |

### Simulação de prospecção

Testa o comportamento real da prospecção antes da ativação: conversas isoladas por e-mail e WhatsApp, além de ligações de voz confirmadas explicitamente para um número de teste.

#### `get_voice_simulation_status` (leitura)

Lê o status, a transcrição e o resumo do desfecho de uma simulação de voz do cliente. Faça polling com o simulationLeadId e o callId retornados por start_voice_simulation até finished=true.

| Parâmetros | | |
|---|---|---|
| `simulation_lead_id` | integer, obrigatório | simulationLeadId retornado por start_voice_simulation. |
| `call_id` | integer, obrigatório | callId retornado por start_voice_simulation. |

#### `run_prospecting_simulation` (escrita)

Inicia, continua, inspeciona ou finaliza uma simulação de prospecção isolada usando os MESMOS agentes de prospecção de email/WhatsApp e a configuração atual do customer/campaign usada em produção. Nenhum lead real é contatado. Ciclo de vida: simulation_lead_id=0 inicia um novo lead fictício; passe lead_message para também simular a próxima mensagem do lead; reutilize o simulation_lead_id retornado com outro lead_message para turnos posteriores; omita lead_message com um ID existente para inspecionar a transcrição mesclada e o estado do lead; defina finish=true para encerrá-la. Use uma simulação nova após edições de configuração ao validar a partir de uma base limpa.

| Parâmetros | | |
|---|---|---|
| `channel` | string, obrigatório | Canal de teste de entrada: 'email' ou 'whatsapp'. Em uma nova simulação iniciada pelo agente, este também é o canal de abertura. O agente real pode responder em outro canal. |
| `simulation_lead_id` | integer, opcional, padrão `0` | ID de lead de simulação existente para continuar/inspecionar/encerrar. Omita ou use 0 para iniciar uma nova simulação. |
| `lead_message` | string, opcional | Mensagem a enviar ao interpretar o papel do lead falso. Em uma nova simulação, isso é executado imediatamente após a criação/o texto de abertura. Omita com um ID existente apenas para inspecionar. |
| `last_email_subject` | string, opcional | Assunto do email para esta resposta do lead falso. Usado apenas quando channel='email'. |
| `campaign` | string, opcional | Nome da campanha ou campaign_id numérico. Omita para prospecção padrão em nível de cliente. Usado apenas ao iniciar uma nova simulação. |
| `lead_starts` | boolean, opcional, padrão `false` | Se true em uma nova simulação, o lead falso inicia a conversa e nenhuma abertura do agente é gerada antes de lead_message. |
| `finish` | boolean, opcional, padrão `false` | Encerra a simulação existente. Requer simulation_lead_id; nenhum turno é executado. |
| `lead_name` | string, opcional | Nome do lead falso. Opcional; um teste iniciado pelo agente recebe um valor padrão realista. Deixe em branco com lead_starts=true para testar um lead de entrada desconhecido. |
| `company_name` | string, opcional | Nome da empresa do lead falso. Opcional; um teste iniciado pelo agente recebe um valor padrão realista. |
| `company_description` | string, opcional | Descrição da empresa do lead falso. Inclua fatos de adequação/desqualificação exigidos pelo cenário. |
| `website` | string, opcional | Site da empresa do lead falso. |
| `phone` | string, opcional | Número de telefone do lead falso. |
| `city` | string, opcional | Cidade do lead falso. |
| `state` | string, opcional | Estado/região do lead falso. |
| `cnae` | string, opcional | Classificação CNAE/setor do lead falso. |
| `cnpj` | string, opcional | Número de CNPJ/registro de empresa do lead falso. |
| `country` | string, opcional | País do lead falso. |
| `background` | string, opcional | Histórico de prospecção específico do cenário, conhecido sobre o lead falso. |
| `goal` | string, opcional | Substituição de meta específica do lead para esta simulação. |
| `notes` | string, opcional | Notas específicas do lead visíveis para o agente de prospecção. |
| `first_touch_instructions` | string, opcional | Instruções de primeiro contato específicas do lead para esta simulação. |

#### `start_voice_simulation` (destrutiva)

Inicia uma simulação de prospecção por VOZ isolada que faz uma chamada telefônica REAL para o número de perfil salvo do proprietário da conta autenticada. Nunca liga para um lead ou para um número arbitrário fornecido. Obtenha a confirmação explícita do usuário imediatamente antes de chamar esta ferramenta, pois o telefone vai tocar e há custo de telefonia/uso de LLM. Usa as instruções de voz atuais do cliente ou da campanha e retorna simulationLeadId + callId para o polling de get_voice_simulation_status.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, opcional | Nome da campanha ou campaign_id numérico. Omita para prospecção por voz em nível de cliente/padrão. |
| `lead_name` | string, opcional | Nome do lead falso. Um valor padrão realista é usado quando omitido. |
| `company_name` | string, opcional | Nome da empresa do lead falso. Um valor padrão realista é usado quando omitido. |
| `company_description` | string, opcional | Descrição da empresa do lead falso. Inclua fatos de adequação/desqualificação necessários para o cenário de voz. |
| `website` | string, opcional | Website da empresa do lead falso. |
| `background` | string, opcional | Histórico de prospecção específico do cenário, conhecido sobre o lead falso. |
| `goal` | string, opcional | Substituição do objetivo específico do lead para esta simulação. |
| `notes` | string, opcional | Notas específicas do lead visíveis para o agente de prospecção. |
| `first_touch_instructions` | string, opcional | Instruções de primeiro contato específicas do lead para esta simulação. |

### Arquivos de prospecção

O catálogo de arquivos que o agente pode enviar para um lead — apresentações, tabelas de preço, guias — no escopo de uma campanha ou da conta inteira.

#### `list_prospecting_files` (leitura)

Lista o catálogo de arquivos de prospecção — os materiais que o agente de prospecção pode oferecer e enviar aos leads, com o title, description, url e escopo de campanha de cada arquivo.

Parâmetros: —

#### `register_prospecting_file` (escrita)

Registra um arquivo no catálogo de arquivos de prospecção — os materiais que o agente de prospecção pode oferecer e ENVIAR AOS LEADS durante o contato (tabela de preços, apresentação institucional, guia de integração), via anexos de e-mail e documentos do WhatsApp. Forneça customer_file_id (um arquivo do cliente já enviado — preferido) ou uma url direta. Se nenhuma description for informada, uma é gerada automaticamente a partir do conteúdo do arquivo, para que o agente saiba quando enviá-lo. NÃO serve para o conhecimento do negócio a partir do qual o agente responde perguntas (register_business_file) nem para o guia personalizado gerado por IA por lead.

| Parâmetros | | |
|---|---|---|
| `title` | string, obrigatório | Título curto voltado para o lead, ex.: 'Tabela de preços' |
| `description` | string, opcional | O que o arquivo contém e quando enviá-lo a um lead (1 a 3 frases). Deixe em branco para gerar automaticamente a partir do conteúdo do arquivo. |
| `customer_file_id` | integer, opcional | Id de um arquivo de cliente existente para registrar (preferível a uma url direta) |
| `url` | string, opcional | URL pública direta do arquivo (alternativa a customer_file_id) |
| `campaign` | string, opcional | Nome de campanha opcional para tornar o arquivo enviável APENAS para os leads dessa campanha. Deixe em branco para um arquivo válido para todo o cliente, enviável a qualquer lead. |
| `sort_order` | integer, opcional, padrão `0` | Ordem de exibição/prompt no catálogo (menor primeiro, padrão 0) |

#### `remove_prospecting_file` (destrutiva)

Remove um arquivo do catálogo de arquivos de prospecção para que o agente de prospecção pare de oferecê-lo e enviá-lo aos leads. Encontre o id com list_prospecting_files.

| Parâmetros | | |
|---|---|---|
| `prospecting_file_id` | integer, obrigatório | Id do arquivo de prospecção a ser removido |

#### `update_prospecting_file` (escrita)

Atualiza o título, a descrição, o escopo de campanha ou a ordem de exibição de um arquivo de prospecção. Encontre o id com list_prospecting_files. Para alterar o arquivo em si, remova a entrada e registre uma nova.

| Parâmetros | | |
|---|---|---|
| `prospecting_file_id` | integer, obrigatório | Id do arquivo de prospecção a ser atualizado |
| `title` | string, opcional | Novo título voltado ao lead |
| `description` | string, opcional | Nova descrição do que o arquivo contém e de quando enviá-lo |
| `campaign` | string, opcional | Nome da campanha à qual o arquivo deve ser vinculado, ou 'all' para torná-lo válido para todo o cliente |
| `sort_order` | integer, opcional | Nova ordem de exibição/prompt no catálogo (menor primeiro) |

### Links de prospecção

O catálogo de páginas da web que o agente pode enviar para um lead como links — páginas de documentação, apresentações online, páginas de preços — no escopo de uma campanha ou da conta inteira.

#### `list_prospecting_links` (leitura)

Lista o catálogo de prospecting links — as páginas web que o prospecting agent pode enviar aos leads, com o título, a descrição, a url e o escopo de campanha de cada link.

Parâmetros: —

#### `register_prospecting_link` (escrita)

Registra uma página web no catálogo de prospecting links — páginas que o prospecting agent pode ENVIAR AOS LEADS durante o outreach como um link ao final da mensagem (página de documentação, apresentação online, página de preços). Forneça a url da página e um título curto. Se nenhuma descrição for fornecida, uma é gerada automaticamente a partir do conteúdo da página, para que o agent saiba quando enviá-la. Uma página web nunca é um arquivo — use register_prospecting_file para PDFs e documentos.

| Parâmetros | | |
|---|---|---|
| `title` | string, obrigatório | Título curto voltado ao lead, ex.: 'Apresentacao online' |
| `url` | string, obrigatório | URL pública da página web |
| `description` | string, opcional | O que a página contém e quando enviá-la a um lead (1-3 frases). Deixe vazio para gerar automaticamente a partir do conteúdo da página. |
| `campaign` | string, opcional | Nome de campanha opcional para tornar o link enviável APENAS aos leads dessa campanha. Deixe vazio para um link válido para todo o cliente, enviável a qualquer lead. |
| `sort_order` | integer, opcional, padrão `0` | Ordem de exibição/prompt no catálogo (menor primeiro, padrão 0) |

#### `remove_prospecting_link` (destrutiva)

Remove uma página web do catálogo de prospecting links para que o prospecting agent pare de enviá-la aos leads. Encontre o id com list_prospecting_links.

| Parâmetros | | |
|---|---|---|
| `prospecting_link_id` | integer, obrigatório | Id do prospecting link a remover |

#### `update_prospecting_link` (escrita)

Atualiza o título, a descrição, o escopo de campanha ou a ordem de exibição de um prospecting link. Encontre o id com list_prospecting_links. Para alterar a própria URL, remova a entrada e registre uma nova.

| Parâmetros | | |
|---|---|---|
| `prospecting_link_id` | integer, obrigatório | Id do prospecting link a atualizar |
| `title` | string, opcional | Novo título voltado ao lead |
| `description` | string, opcional | Nova descrição do que a página contém e quando enviá-la |
| `campaign` | string, opcional | Nome de campanha para restringir o link, ou 'all' para torná-lo válido para todo o cliente |
| `sort_order` | integer, opcional | Nova ordem de exibição/prompt no catálogo (menor primeiro) |

### Aprendizados da prospecção

Lista, pesquisa e dispensa aprendizados da atividade de prospecção.

#### `dismiss_prospecting_learning` (escrita)

Oculta um aprendizado de prospecção quando o cliente diz que está incorreto ou desatualizado; preserva o motivo dele. Não altera os resultados de origem nem as instruções operacionais.

| Parâmetros | | |
|---|---|---|
| `learning_id` | integer, obrigatório | ID do aprendizado da lista ou busca. |
| `reason` | string, obrigatório | Motivo do cliente, 1–2000 caracteres. |

#### `list_prospecting_learnings` (leitura)

Lista aprendizados baseados em evidências sobre a prospecção deste cliente, separados dos documentos de referência da empresa. Retorna todos os relatórios fixos dos últimos 90 dias: dias/horários de resposta de e-mail, cada motivo de recusa registrado com contagens, regiões dos leads e setores/CNAEs. Content contém o insight prontamente utilizável; Summary contém a visão numérica geral. Preserva escopo, datas e limitações; não altera as regras de prospecção.

Parâmetros: —

#### `search_prospecting_learnings` (leitura)

Pesquisa semanticamente os aprendizados de prospecção deste cliente usando sua própria consulta orientada por raciocínio: motivos de recusa registrados, dias/horários de resposta de e-mail, cidades/estados dos leads ou setores/CNAEs. Observações não são prova causal. Separado dos documentos de referência da empresa.

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | Tópico ou pergunta de prospecção, 1–2000 caracteres. |

### Relatórios

Os números: relatório principal de prospecção, funil por setor e por estado, tendências de performance, performance das mensagens, estimativas de volume e um resumo narrativo do que mudou.

#### `estimate_lead_volume` (leitura)

Retorna um benchmark do que um cliente PAGO típico da Blue Button (e clientes pagos com um ICP semelhante) produz nos últimos 30 dias: novos leads encontrados, respostas confirmadas (conversas reais), leads interessados (quentes), e mensagens enviadas — cada um mostrado como um intervalo da mediana (cliente típico) até o topo (os mais ativos) por semana e por mês. Usuários somente do teste gratuito são excluídos. A ferramenta escolhe o benchmark mais relevante automaticamente — Similar (clientes pagos com sobreposição de CNAE) quando disponível, Global (todos os clientes pagos) caso contrário.

Parâmetros: —

#### `get_funnel_by_industry` (leitura)

Obtém uma divisão do funil por setor. Para clientes brasileiros, agrupa por divisão do CNAE. Para clientes internacionais, agrupa pelo campo CompanyIndustry dos dados da Apollo. Opcionalmente, filtre por campanha.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para o funil global) |

#### `get_funnel_timeline` (leitura)

Contagem de leads ENTRANDO em cada estágio do funil por bucket de tempo (dia ou semana). Estágios rastreados: cold (DateProspectingStarted), confirmed (DateConfirmedProspectingQualification), interested (DateConfirmedInterest), closed (DateStatusChanged enquanto o Status atual = Closed — APROXIMAÇÃO: um lead que esteve Closed e depois mudou para outro status não será contado, porque a plataforma não armazena histórico de status). Aware não é exposto — a plataforma não rastreia de forma confiável a entrada nesse estágio. Buckets ausentes preenchidos com zeros, do mais recente para o mais antigo. Opcionalmente, filtre por campanha.

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias para olhar para trás (padrão 30, máximo 365) |
| `bucket` | string, opcional, padrão `day` | Tamanho do bucket: 'day' (padrão) ou 'week' (alinhado à segunda-feira) |
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para a timeline global) |

#### `get_message_performance` (leitura)

Taxa de resposta detalhada por campanha e/ou tipo de mensagem em uma janela de tempo. Retorna total sent, replied (e-mails de saída distintos com pelo menos uma resposta), reply_rate_pct, além de um detalhamento. O formato do detalhamento depende de group_by: 'campaign' retorna uma linha por campanha (tipos de mensagem agrupados); 'type' retorna uma linha por tipo de mensagem (campanhas agrupadas); 'both' (padrão) retorna uma linha por combinação campanha×tipo (uma matriz — NÃO duas listas separadas — então espere até N_campaigns × N_types linhas). Tipos de mensagem: first_contact (AutonomousFirstTouch), follow_up (AutonomousFollowUp), response (AutonomousResponse a mensagens recebidas), direct (DirectMessage enviada em nome do usuário), user_written (UserWrittenMessage enviada manualmente pelo usuário). Padrão de 30 dias.

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias retroativos (padrão 30, máximo 365) |
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para todas as campanhas) |
| `group_by` | string, opcional, padrão `both` | Como agrupar o detalhamento: 'campaign', 'type', ou 'both' (padrão) |

#### `get_metrics_by_state_and_industry` (leitura)

Detalha cada métrica de prospecção por ESTADO brasileiro e por SETOR (descrição do CNAE) ao longo de uma janela de tempo, para que você possa comparar quais estados/setores estão performando melhor. Para cada dimensão, retorna os grupos principais por volume de leads — cada um com new_leads, emails_sent, responses, whatsapp_sent, whatsapp_responses, conscientizados, interested (tornou-se interested na janela), confirmed_aware_interested_or_takenover, referrals, e contagens de reuniões (convites feitos/recebidos, agendadas, realizadas) — além do grupo com melhor desempenho por categoria de métrica. Leads sem estado/CNAE caem em 'Não informado' e são excluídos das seleções de melhor desempenho. interested é contado por DateConfirmedInterest (o momento em que o lead converteu). Opcionalmente, filtre por campanha.

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias retroativos (padrão 30, máximo 365) |
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para a conta inteira) |

#### `get_performance_trends` (leitura)

Obtenha as tendências de desempenho de prospecção por dia durante a janela especificada. Todas as métricas são contagens diárias de FLOW (eventos que aconteceram naquele dia), não estoques cumulativos. Cada linha tem: leads_generated (leads criados naquele dia), emails_sent (e-mails de prospecção de saída enviados naquele dia), replies_received (respostas de entrada a e-mails de saída recebidas naquele dia), confirmed (leads cujo status se tornou Confirmed pela primeira vez naquele dia, ou seja, DateConfirmedProspectingQualification cai naquele dia), interested (leads cujo status se tornou Interested pela primeira vez naquele dia, ou seja, DateConfirmedInterest cai naquele dia — esta é a contagem de entradas por dia, NÃO o número total de leads atualmente com Status=Interested), whatsapp_sent (mensagens de WhatsApp de prospecção enviadas naquele dia, por DateSent), whatsapp_replies_received (respostas de WhatsApp de leads naquele dia, pelo timestamp de envio do lead). Dias faltantes são preenchidos com zeros. Opcionalmente, filtre por campanha.

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias para olhar para trás (padrão 30, máximo 365) |
| `campaign` | string, opcional | Filtra por nome da campanha ou campaign_id numérico (opcional, omita para tendências globais) |

#### `get_prospecting_report` (leitura)

Obtenha um relatório geral de prospecção: total de leads, leads por status, e-mails enviados, taxa de resposta e resumo do pipeline. Também retorna atividade no WhatsApp: whatsapp_sent (mensagens de WhatsApp de prospecção enviadas), whatsapp_responses (respostas de WhatsApp recebidas, contadas separadamente das respostas por e-mail) e leads_talked_to_on_whatsapp (leads distintos com qualquer mensagem de WhatsApp em qualquer direção). Opcionalmente, filtre por campanha.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, opcional | Filtra por nome da campanha ou campaign_id numérico (opcional, omita para relatório global) |

#### `get_whatsapp_message_performance` (leitura)

Desempenho de respostas de WhatsApp detalhado por campanha e/ou tipo de mensagem em uma janela de tempo. OBSERVAÇÃO: diferente de get_message_performance (e-mail), a taxa de resposta do WhatsApp é reportada no nível do LEAD — o WhatsApp de entrada não tem vínculo por mensagem com uma mensagem de saída específica, então 'replied' não pode ser atribuído por mensagem. Retorna total sent (contagem de mensagens), leads_messaged (leads distintos contatados), leads_replied (leads distintos que enviaram pelo menos uma mensagem de entrada em ou após sua primeira mensagem de saída daquele tipo na janela), lead_reply_rate_pct (leads_replied / leads_messaged), além de uma discriminação. group_by: 'campaign' (uma linha por campanha), 'type' (uma linha por tipo de mensagem), 'both' (padrão, matriz campaign×type). Tipos de mensagem: first_contact (AutonomousFirstTouch), follow_up (AutonomousFollowUp), response (AutonomousResponse), direct (DirectMessage), user_written (UserWrittenMessage). Padrão de 30 dias.

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias para olhar para trás (padrão 30, máximo 365) |
| `campaign` | string, opcional | Filtra por nome da campanha ou campaign_id numérico (opcional, omita para todas as campanhas) |
| `group_by` | string, opcional, padrão `both` | Como agrupar o detalhamento: 'campaign', 'type', ou 'both' (padrão) |

#### `list_prospecting_optimizations` (leitura)

Lista o histórico de otimizações autônomas de prospecção em ordem cronológica reversa (mais recentes primeiro). Paginado. Cada entrada mostra quando o agente revisor de prospecção rodou e quais mudanças de segmentação/configuração ele fez e por quê. Opcionalmente, filtre por campanha.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para todas as otimizações) |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Tamanho da página (padrão 20, máximo 100) |

#### `what_changed_since` (leitura)

Resumo completo do que aconteceu na operação de prospecção desde uma determinada data — criado para o caso 'fiquei ausente por meses, o que aconteceu?'. Blocos: (1) activity_summary — o trabalho bruto do motor na janela: new_leads, emails_sent, email_replies, whatsapp_sent, whatsapp_replies; (2) funnel_progress — leads que atingiram cada estágio na janela: reached_confirmed, became_interested; (3) new_interested_leads — os próprios leads interessados (até 100, mais total_count); (4) outcomes — negócios fechados na janela: won_count, lost_count, gave_up_count, total_deal_value_brl, e won_items; (5) meetings — contagens de agendadas, canceladas, realizadas e no_show na janela, mais items; (6) pending_human_review — o monte ATUAL de leads aguardando o dono da conta (uma captura instantânea ao vivo, NÃO limitada à janela): total_count mais items; (7) support_answered — solicitações de suporte respondidas pela equipe na janela (message + answer); (8) campaign_performance_changes — campanhas cuja taxa de resposta variou pelo menos 3 pontos percentuais (janela de 30 dias terminando em since_date vs since_date→now, ignorando janelas com menos de 50 enviados); (9) optimizer_adjustments — alterações do prospecting-optimizer persistidas desde essa data (limitadas a 500 itens; total_count/returned_count/truncated informam o total real). Todas as contagens com janela cobrem since_date→now; os timestamps estão em UTC.

| Parâmetros | | |
|---|---|---|
| `since_date` | string, obrigatório | Data ISO no formato YYYY-MM-DD (ex.: 2026-01-15) |

### Ligações

Faz uma ligação com objetivo definido para um lead, lê as ligações já realizadas e liga ou desliga as chamadas por conta ou por campanha.

#### `get_campaign_voice_calling_active` (leitura)

Lê o toggle de chamadas de voz de uma campanha. Um valor null significa que a campanha herda o toggle em nível de cliente.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | Nome da campanha |

#### `get_voice_call` (leitura)

Obtenha o status e o resultado de uma chamada telefônica orientada a objetivo feita com place_goal_driven_call: status do ciclo de vida, se uma pessoa atendeu, se o objetivo foi alcançado, o resumo do resultado e a transcrição completa.

| Parâmetros | | |
|---|---|---|
| `voice_call_request_id` | integer, obrigatório | O voice_call_request_id retornado por place_goal_driven_call |

#### `get_voice_calling_active` (leitura)

Leia se as chamadas de voz de saída autônomas para leads estão ativas no nível do cliente.

Parâmetros: —

#### `get_voice_prospecting_voice` (leitura)

Lê com qual voz o agente fala nas ligações de prospecção outbound ('Male' ou 'Female').

Parâmetros: —

#### `list_voice_calls` (leitura)

Lista as ligações telefônicas orientadas a objetivo do cliente (mais recentes primeiro) com status e resumo do desfecho. Use get_voice_call para a transcrição completa de uma ligação.

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Tamanho da página (padrão 20, máximo 100) |

#### `place_goal_driven_call` (escrita)

Faz uma ligação telefônica REAL para um número fornecido pelo cliente, para cumprir um objetivo declarado (por exemplo, 'ligue para este restaurante e pergunte se há mesa disponível hoje à noite'). Um assistente de voz em tempo real faz a ligação em segundo plano; isso apenas enfileira a solicitação — a ligação é feita pouco depois e não pode ser cancelada assim que a discagem começa. Faça polling de get_voice_call com o voice_call_request_id retornado para obter o resultado (status, goal_achieved, summary, transcript); o resultado também chega como uma notificação da plataforma.

| Parâmetros | | |
|---|---|---|
| `phone_number` | string, obrigatório | O número de telefone para ligar, em formato internacional, ex.: +5511999999999 |
| `goal` | string, obrigatório | O objetivo da ligação em linguagem simples e no idioma do cliente — exatamente o que deve ser realizado ou descoberto |
| `context` | string, opcional | Histórico/contexto opcional: quem está sendo chamado e qualquer informação útil |

#### `set_campaign_voice_calling_active` (escrita)

Habilita ou desabilita ligações de voz ativas autônomas para uma campanha específica, sobrepondo a opção em nível de cliente apenas para essa campanha.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | Nome da campanha |
| `active` | boolean, obrigatório | True para ativar, false para desativar, para esta campanha |

#### `set_voice_calling_active` (escrita)

Habilita ou desabilita as chamadas de voz autônomas de saída para leads no nível do cliente. Independente da prospecção por e-mail.

| Parâmetros | | |
|---|---|---|
| `active` | boolean, obrigatório | True para ativar, false para desativar |

#### `set_voice_prospecting_voice` (escrita)

Define com qual voz o agente fala nas ligações de prospecção outbound. 'Male' é o padrão. Isso só muda como o agente soa - não muda o que ele diz, e não afeta o WhatsApp ou o email.

| Parâmetros | | |
|---|---|---|
| `voice` | string, obrigatório | A voz a ser usada nas chamadas de prospecção: 'Male' ou 'Female' |

### Linha de WhatsApp

Cadastra e consulta a linha de WhatsApp de prospecção, define os tetos de custo mensal e diário e atualiza o perfil comercial.

#### `get_whatsapp_line` (leitura)

Obtenha a linha de prospecção de WhatsApp do cliente — a leitura única de status/diagnóstico: se está ativa/pronta para enviar, seu número, classificação de qualidade, perfil comercial completo do WhatsApp, o link pendente de cadastro em um clique da Meta (quando o cliente ainda precisa conectar sua WhatsApp Business Account), qualquer PROBLEMA DE SAÚDE ATIVO com a correção exata que o cliente deve aplicar (forma de pagamento, link de reconexão, restrição da Meta) e o gasto de WhatsApp no dia e no mês até o momento em relação aos limites de custo diário e mensal do cliente. Atualiza o snapshot ao vivo da Meta primeiro.

Parâmetros: —

#### `register_whatsapp_line` (escrita)

Registra uma linha dedicada de WhatsApp para prospecção (um número real de WhatsApp). O provisionamento é automático e leva alguns minutos. Se o cliente já tiver uma linha, retorna essa linha em vez de criar outra (uma linha por cliente). Requer um plano pago ativo que inclua prospecção por WhatsApp. Por padrão, a Eesier fornece um número novo; passe use_own_number=true quando o cliente quiser prospectar a partir do PRÓPRIO número de WhatsApp — nesse caso, ele recebe um link da Meta de um clique, cujo popup oficial conecta a WhatsApp Business Account dele (ou cria uma), permite escolher qual dos seus números usar, ou verifica um novo número na hora.

| Parâmetros | | |
|---|---|---|
| `use_own_number` | boolean, opcional, padrão `false` | True quando o cliente quer usar o PRÓPRIO número de WhatsApp em vez de um novo fornecido pela Eesier. Padrão false. |

#### `set_whatsapp_daily_cost_cap` (escrita)

Define (ou remove) o limite diário de gastos do customer com prospecção via WhatsApp, na moeda em que a Meta cobra o customer. A Meta cobra as taxas de conversa do WhatsApp diretamente na conta do próprio customer, então esse limite permite que o customer decida o máximo que deseja gastar por dia. Quando o limite é atingido, as mensagens de WhatsApp pagas (que abrem conversa) pausam até o dia seguinte — respostas a leads que mandam mensagem primeiro continuam funcionando, e a prospecção por email não é afetada. Passe 0 ou um valor negativo para remover o limite. O gasto atual e o limite ficam visíveis em get_whatsapp_line.

| Parâmetros | | |
|---|---|---|
| `daily_cap` | number, obrigatório | Gasto máximo diário com WhatsApp, na moeda em que a Meta cobra a conta de WhatsApp deste cliente (retornada como cost_cap_currency por get_whatsapp_line — NÃO necessariamente BRL). Nunca converta o valor para outra moeda. 0 ou negativo remove o limite. |

#### `set_whatsapp_line_profile_picture` (escrita)

Define a foto de perfil da linha do WhatsApp a partir de uma URL de imagem pública ou de um arquivo do customer já enviado. Qualquer JPG/PNG/WebP — imagens não quadradas, pequenas ou grandes demais são ajustadas automaticamente para um avatar quadrado. A linha já precisa estar ativa (live).

| Parâmetros | | |
|---|---|---|
| `image_url` | string, opcional | URL pública da imagem (qualquer JPG/PNG/WebP — ajustada automaticamente para um avatar quadrado) |
| `customer_file_id` | integer, opcional | Id de um arquivo do cliente já enviado para usar como a foto. Preferível quando o usuário enviou uma imagem. |

#### `set_whatsapp_monthly_cost_cap` (escrita)

Define (ou remove) o limite mensal de gastos do customer com prospecção via WhatsApp, na moeda em que a Meta cobra o customer. A Meta cobra as taxas de conversa do WhatsApp diretamente na conta do próprio customer, então esse limite permite que o customer decida o máximo que deseja gastar por mês calendário. Quando o limite é atingido, as mensagens de WhatsApp pagas (que abrem conversa) pausam até o dia 1º do mês seguinte — respostas a leads que mandam mensagem primeiro continuam funcionando, e a prospecção por email não é afetada. Passe 0 ou um valor negativo para remover o limite. O gasto atual e o limite ficam visíveis em get_whatsapp_line.

| Parâmetros | | |
|---|---|---|
| `monthly_cap` | number, obrigatório | Gasto máximo mensal com WhatsApp, na moeda em que a Meta cobra a conta de WhatsApp deste cliente (retornada como cost_cap_currency por get_whatsapp_line — NÃO necessariamente BRL). Nunca converta o valor para outra moeda. 0 ou negativo remove o limite. |

#### `update_whatsapp_line_profile` (escrita)

Atualiza o perfil comercial da linha do WhatsApp. Somente os campos informados são alterados. A linha já deve estar ativa. O nome de exibição não é gerenciado aqui.

| Parâmetros | | |
|---|---|---|
| `about` | string, opcional | Texto curto de 'sobre' (máx. 139 caracteres) |
| `description` | string, opcional | Descrição do negócio (máx. 512 caracteres) |
| `address` | string, opcional | Endereço comercial (rua) |
| `email` | string, opcional | E-mail de contato comercial |
| `websites` | string, opcional | URLs do site do negócio, separadas por vírgula (o WhatsApp exibe no máximo 2) |
| `vertical` | string, opcional | Categoria do negócio (vertical do WhatsApp), ex.: PROF_SERVICES, RETAIL, EDU, HEALTH, FINANCE, RESTAURANT, OTHER |

### Perfil do negócio

O que a conta vende e para quem. Lê o perfil, lê a avaliação que o agente faz dele e reescreve.

#### `get_business` (leitura)

Retorna o perfil de negócio do cliente: nome, descrição, site, perfil de cliente ideal e URL de apresentação padrão.

Parâmetros: —

#### `get_business_assessment` (leitura)

Lê a última avaliação de fundamentos de negócio que o consultor interno do Blue Button registrou para este cliente: veredito, probabilidade de resultados, o JSON completo da avaliação, quando foi feita, e os exemplos conhecidos de clientes pagantes do cliente. Dados somente leitura — traga sua própria análise em cima disso; não há ferramenta para reexecutar a avaliação.

Parâmetros: —

#### `set_business` (escrita)

Atualiza o perfil de negócio do cliente. Passe apenas os campos que deseja alterar. Campos: business_name, business_description, business_website, ideal_customer_profile, paying_customer_examples. Para os arquivos que o agente de prospecção envia aos leads (apresentação, tabela de preços, ...), use as ferramentas de arquivo de prospecção (register_prospecting_file / list_prospecting_files).

| Parâmetros | | |
|---|---|---|
| `business_name` | string, opcional | Nome do negócio |
| `business_description` | string, opcional | Descrição do negócio |
| `business_website` | string, opcional | URL do site do negócio |
| `ideal_customer_profile` | string, opcional | Texto do perfil de cliente ideal |
| `paying_customer_examples` | string, opcional | Exemplos reais de clientes pagantes a partir dos quais o ICP e o consultor de negócios raciocinam |

### Arquivos do negócio

O material de referência que o agente lê para entender o negócio — cadastra, lista e remove.

#### `list_business_files` (leitura)

Liste os arquivos de conhecimento do negócio registrados para este cliente, com o estado de indexação e o escopo de campanha de cada arquivo.

Parâmetros: —

#### `register_business_file` (escrita)

Registra um texto (ou um arquivo do cliente já enviado) como conhecimento do negócio, para que os agentes de prospecção possam responder perguntas sobre o negócio (serviços, processos, preços, perguntas frequentes). O conteúdo é fragmentado + vetorizado em segundo plano e torna-se pesquisável em pouco tempo. Forneça text ou customer_file_id.

| Parâmetros | | |
|---|---|---|
| `title` | string, obrigatório | Título curto e descritivo, ex.: 'Tabela de preços 2026' |
| `text` | string, opcional | Texto bruto para registrar como conhecimento do negócio (use quando o conteúdo foi colado diretamente) |
| `customer_file_id` | integer, opcional | Id de um arquivo de cliente existente para registrar (encontre-o com list_business_files ou na lista de arquivos) |
| `campaign` | string, opcional | Nome de campanha opcional para restringir este conhecimento a uma campanha. Deixe em branco para conhecimento em nível de cliente, compartilhado entre todas as campanhas. |

#### `remove_business_file` (destrutiva)

Remove um arquivo de conhecimento do negócio registrado e seus trechos indexados para que os agentes parem de responder com base nele. Encontre o id com list_business_files.

| Parâmetros | | |
|---|---|---|
| `business_file_id` | integer, obrigatório | Id do arquivo de conhecimento da empresa a ser removido |

### Perguntas frequentes

As perguntas que os leads sempre fazem: o FAQ já respondido do negócio e as que continuam em aberto esperando resposta.

#### `list_business_faq` (leitura)

Liste o FAQ do negócio — todo par de pergunta e resposta que a plataforma acumulou sobre este negócio (cada resposta dada via answer_lead_question chega aqui, e os agentes de prospecção o utilizam para responder aos leads). Leia antes de perguntar ao usuário algo que já possa ter sido respondido.

Parâmetros: —

#### `list_open_lead_questions` (leitura)

Lista as perguntas que os LEADS fizeram e que o agente não conseguiu responder e que ainda estão esperando a contribuição do proprietário do negócio. Loop de alto valor: apresente essas perguntas ao usuário, obtenha as respostas e depois registre cada uma via answer_lead_question (passe o open_question_id) — pergunte se a resposta é reutilizável ou apenas para este lead.

Parâmetros: —

### Sugestões

Pede para a plataforma montar a segmentação: um perfil de cliente ideal, ou os CNAEs a incluir e a excluir.

#### `generate_cnae_exclusion_suggestion` (leitura)

Gera códigos de exclusão de CNAE sugeridos com base em um perfil de cliente ideal e na descrição do negócio. Esses códigos identificam concorrentes e setores incompatíveis a excluir da prospecção. Funciona apenas para clientes brasileiros. Retorna os códigos sem salvar — use set_targeting para salvar.

| Parâmetros | | |
|---|---|---|
| `icp_text` | string, opcional | Texto do ICP para analisar. Se omitido, usa o ICP atual do cliente. |

#### `generate_cnae_suggestion` (leitura)

Gera códigos de inclusão de CNAE sugeridos com base em um perfil de cliente ideal. Os códigos CNAE são usados para direcionar setores específicos na prospecção de leads no Brasil. Funciona apenas para clientes brasileiros. Retorna os códigos sem salvar — use set_targeting para salvar.

| Parâmetros | | |
|---|---|---|
| `icp_text` | string, opcional | Texto do ICP para analisar. Se omitido, usa o ICP atual do cliente. |

#### `generate_icp_suggestion` (leitura)

Gera uma sugestão de perfil de cliente ideal (ICP) com base nas informações do negócio do cliente. Usa IA para analisar o negócio e sugerir quem são os clientes ideais. Retorna a sugestão sem salvá-la — use set_business para salvar.

Parâmetros: —

### Consultas de referência

Busca na base de conhecimento da própria plataforma antes de responder qualquer pergunta sobre como ela funciona, e resolve CNAEs e cidades.

#### `lookup_city` (leitura)

Consulta o código de uma cidade brasileira (código IBGE) a partir do nome da cidade. Funciona apenas para clientes brasileiros. Retorna as cidades correspondentes. Usado para filtros de prospecção baseados em cidade.

| Parâmetros | | |
|---|---|---|
| `city_name` | string, obrigatório | Nome da cidade a ser buscada (ex.: 'São Paulo', 'Curitiba') |

#### `lookup_cnae` (leitura)

Consulta o nome e a descrição de um código CNAE. CNAE (Classificação Nacional de Atividades Econômicas) é o sistema brasileiro de classificação de atividades econômicas. Funciona apenas para clientes brasileiros. Forneça um código para obter seu nome no nível de divisão (2 dígitos), grupo (3 dígitos), classe (5 dígitos) ou subclasse (7 dígitos).

| Parâmetros | | |
|---|---|---|
| `code` | string, obrigatório | Código CNAE (ex.: '62' para divisão de TI, '6201' para grupo de desenvolvimento de software, '6201501' para subclasse de desenvolvimento de software) |

#### `search_knowledge` (leitura)

Busca na base de conhecimento do Blue Button respostas oficiais sobre como a plataforma funciona — preços, planos, onboarding, capacidades de segmentação, envio de e-mail, assunção de controle, relatórios, privacidade, cancelamento, e toda outra pergunta específica da plataforma. Usa RAG semântico (similaridade de embeddings) sobre trechos de conhecimento curados, então a consulta pode ser uma pergunta em linguagem natural, uma palavra-chave, ou um tópico. SEMPRE chame esta ferramenta sempre que o usuário perguntar algo específico sobre o Blue Button — nunca improvise a partir de conhecimento geral. Retorna as melhores correspondências com título, conteúdo, e pontuação de similaridade.

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | Consulta em linguagem natural descrevendo o que o usuário quer saber sobre o Blue Button (ex.: 'quanto custa', 'posso segmentar por tamanho da empresa', 'o que acontece quando eu assumo um lead', 'prospecção internacional'). |
| `top_k` | integer, opcional, padrão `3` | Número de melhores resultados a serem retornados. Padrão 3. Use um valor mais alto (até 10) quando a pergunta for ampla ou você quiser múltiplos ângulos. |
| `min_score` | number, opcional, padrão `0.7` | Limite mínimo de pontuação de similaridade (0.0–1.0). Padrão 0.7. Valores mais baixos retornam mais resultados, mas podem ser menos relevantes. |

### Lista de bloqueio

Nunca mais contatar: bloqueia e desbloqueia e-mails, domínios inteiros e telefones.

#### `add_blacklisted_domain` (escrita)

Adiciona um DOMÍNIO inteiro à lista negra. Todo e-mail nesse domínio (ex.: anyone@acme.com) é bloqueado. Não informe um endereço de e-mail completo — use add_blacklisted_email para isso.

| Parâmetros | | |
|---|---|---|
| `domain` | string, obrigatório | O domínio a ser colocado na lista negra, por exemplo, 'acme.com'. Subdomínios não são incluídos automaticamente. |
| `reason` | string, opcional | Motivo: Competitor, Client, ou Other |

#### `add_blacklisted_email` (escrita)

Adiciona um único endereço de e-mail à lista negra. E-mails na lista negra nunca recebem mensagens de prospecção. Para bloquear uma empresa inteira, use add_blacklisted_domain.

| Parâmetros | | |
|---|---|---|
| `email` | string, obrigatório | O endereço de e-mail a ser colocado na lista negra |
| `reason` | string, opcional | Motivo: Competitor, Client, ou Other |

#### `add_blacklisted_phone` (escrita)

Adiciona um NÚMERO DE TELEFONE à lista negra. O número nunca recebe mensagem de WhatsApp nem chamada de voz. Os dígitos são mantidos e todo o restante é removido, então qualquer formatação é aceita.

| Parâmetros | | |
|---|---|---|
| `phone` | string, obrigatório | O número de telefone a ser colocado na lista negra, em qualquer formato (por exemplo, '+55 11 99999-9999') |
| `reason` | string, opcional | Motivo: Competitor, Client, ou Other |

#### `list_blacklisted_emails` (leitura)

Liste as entradas bloqueadas (e-mails individuais, domínios inteiros e números de telefone) com seu motivo e a contagem de quantas vezes foi bloqueado. Paginado — 'total' reporta o tamanho completo da lista.

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `50` | Entradas por página (padrão 50, máximo 200) |

#### `remove_blacklisted_domain` (destrutiva)

Remove um DOMÍNIO inteiro da blacklist, permitindo que os endereços desse domínio voltem a receber mensagens de prospecção.

| Parâmetros | | |
|---|---|---|
| `domain` | string, obrigatório | O domínio a ser removido da blacklist, ex.: 'acme.com' |

#### `remove_blacklisted_email` (destrutiva)

Remove um único endereço de e-mail da blacklist, permitindo que ele volte a receber mensagens de prospecção.

| Parâmetros | | |
|---|---|---|
| `email` | string, obrigatório | O endereço de e-mail a ser removido da blacklist |

#### `remove_blacklisted_phone` (destrutiva)

Remove um NÚMERO DE TELEFONE da blacklist, permitindo que ele volte a receber mensagens de WhatsApp e ligações de voz.

| Parâmetros | | |
|---|---|---|
| `phone` | string, obrigatório | O número de telefone a ser removido da blacklist, em qualquer formato |

### Configurações da conta

Fuso horário, nome do usuário, preferências, permissão de ligação, e-mails de notificação, configurações de envio, domínio remetente e dados fiscais.

#### `get_email_settings` (leitura)

Obtém as configurações de e-mail do Blue Button do cliente: o endereço completo, o handle, o nome de exibição e as instruções de notificação.

Parâmetros: —

#### `get_general_settings` (leitura)

Obtém as configurações gerais da conta do cliente: modo de voz, envio autônomo de mensagens, e-mail da conta e deslocamento de fuso horário.

Parâmetros: —

#### `get_notification_emails` (leitura)

Obtenha os endereços de e-mail atualmente configurados para notificações de prospecção autônoma e relatórios diários.

Parâmetros: —

#### `lookup_municipality_code` (leitura)

Consulta o código IBGE de 7 dígitos do município para uma cidade brasileira. Retorna todas as correspondências quando a cidade existe em mais de um estado. Use antes de update_tax_info.

| Parâmetros | | |
|---|---|---|
| `city_name` | string, obrigatório | Nome da cidade brasileira (não diferencia acentos) |
| `state` | string, opcional | Estado opcional — UF de 2 letras (RS, SP...) ou nome completo em português — para desambiguar |

#### `set_agent_phone_call_permission` (escrita)

Obtém ou define se o agente pode fazer ligações telefônicas ativas para o cliente. Omita 'enabled' para ler o valor atual; passe true/false para alterá-lo.

| Parâmetros | | |
|---|---|---|
| `enabled` | boolean, opcional | True para permitir chamadas, false para bloquear. Omita para apenas ler o valor atual. |

#### `set_email_notification_instructions` (escrita)

Define as regras em texto livre que decidem quais e-mails recebidos merecem uma notificação imediata ao cliente. Passe uma string vazia para limpá-las e voltar ao comportamento padrão.

| Parâmetros | | |
|---|---|---|
| `instructions` | string, obrigatório | Regras que descrevem quais emails recebidos merecem um aviso imediato (vazio para limpar) |

#### `set_personal_email` (escrita)

Define o próprio endereço de e-mail pessoal da conta — o único endereço vinculado à própria conta, distinto da lista de e-mails de notificação de prospecção separada por vírgulas, gerenciada por update_notification_emails.

| Parâmetros | | |
|---|---|---|
| `email` | string, obrigatório | O endereço de e-mail pessoal do proprietário da conta |

#### `set_timezone` (escrita)

Define o fuso horário do cliente informando ao agente a hora local atual (0-23, formato 24h). O deslocamento é calculado a partir de UTC.

| Parâmetros | | |
|---|---|---|
| `current_hour` | integer, obrigatório | Parte da hora do horário local atual do cliente, 0-23 (formato 24h) |

#### `setup_custom_domain` (escrita)

Configura, verifica ou remove um endereço de e-mail com domínio personalizado (ex.: sales@yourcompany.com). Requer um plano pago ativo. action: 'activate' (precisa de email_address), 'verify', ou 'remove'.

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | 'activate' para definir um novo e-mail personalizado, 'verify' para verificar o DNS, 'remove' para removê-lo |
| `email_address` | string, opcional | O endereço de e-mail personalizado completo, ex.: 'sales@yourcompany.com'. Obrigatório para 'activate'. |

#### `setup_email_subdomain` (escrita)

Configura ou verifica um subdomínio de e-mail personalizado (ex.: yourcompany.eesiermail.com). Requer um plano pago ativo. action: 'activate' (precisa de subdomain) ou 'verify'.

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | 'activate' para definir um novo subdomínio, 'verify' para verificar o status de verificação do DNS |
| `subdomain` | string, opcional | O nome do subdomínio, ex.: 'mycompany'. Obrigatório para 'activate'. |

#### `update_email_settings` (escrita)

Atualiza o handle de e-mail do Blue Button (a parte antes do @, no máximo 20 caracteres, único) e/ou o nome de exibição mostrado nos e-mails enviados. Passe pelo menos um campo.

| Parâmetros | | |
|---|---|---|
| `handle` | string, opcional | Novo handle de e-mail (minúsculo, sem espaços, máx. 20 caracteres). Acentos/caracteres inválidos são removidos. |
| `display_name` | string, opcional | Novo nome de exibição para e-mails enviados (o nome 'De' que os destinatários veem) |

#### `update_notification_emails` (escrita)

Define o(s) endereço(s) de e-mail para notificações de prospecção autônoma e relatórios diários (separados por vírgula). O primeiro endereço também se torna o e-mail da conta.

| Parâmetros | | |
|---|---|---|
| `emails` | string, obrigatório | Endereço(s) de email para notificações, separados por vírgula |

#### `update_preferences` (escrita)

Atualiza as preferências do cliente: idioma, se o negócio deve ser exibido no site do Blue Button, e notificações push. Informe pelo menos um campo.

| Parâmetros | | |
|---|---|---|
| `language_key` | string, opcional | Chave de idioma, ex.: pt-BR, en-US, es-AR |
| `show_on_website` | boolean, opcional | Se a empresa deve ser exibida no site do Blue Button |
| `push_notifications` | boolean, opcional | Se as notificações push (console) estão ativadas |

#### `update_tax_info` (escrita)

Atualiza as informações fiscais/de nota fiscal. Passe apenas os campos que precisam ser atualizados. O documento fiscal deve ser CPF (11 dígitos) ou CNPJ (14 dígitos); o CEP deve ter 8 dígitos; o código do município deve ser um código IBGE válido de 7 dígitos (use lookup_municipality_code primeiro). financial_email é o endereço que também recebe os PDFs da Nota Fiscal (NFS-e), além do e-mail da conta (passe uma string vazia para limpá-lo).

| Parâmetros | | |
|---|---|---|
| `tax_name` | string, opcional | Nome registrado para fins fiscais (empresa ou pessoa) |
| `tax_document` | string, opcional | Documento fiscal, somente dígitos: CPF (11) ou CNPJ (14) |
| `street` | string, opcional | Nome da rua |
| `number` | string, opcional | Número do endereço |
| `neighborhood` | string, opcional | Bairro |
| `cep` | string, opcional | Código postal (CEP, 8 dígitos) |
| `municipality_code` | integer, opcional | Código de município do IBGE (7 dígitos) |
| `financial_email` | string, opcional | E-mail financeiro que também recebe os PDFs da Nota Fiscal (NFS-e) (uma string vazia o limpa) |

#### `update_user_name` (escrita)

Atualiza o nome de exibição do cliente.

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | O novo nome do cliente |

### Membros da equipe

Quem mais está na conta — adiciona, lista e remove membros.

#### `add_member` (escrita)

Adiciona outra pessoa (um número de telefone adicional) a esta conta. Coloca na fila uma mensagem de abertura no WhatsApp e um e-mail de acesso com a identidade visual quando um e-mail é informado. A pessoa tem sua própria conversa com o agente, mas acesso compartilhado completo à mesma empresa, configurações e prospecção. Retorna o status real da integração; estar na fila não significa que foi entregue. Falha se o número de telefone já pertencer a qualquer conta.

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | O nome da pessoa |
| `phone_number` | string, obrigatório | O número de telefone da pessoa em formato internacional, por exemplo, +5511999999999 |
| `email` | string, opcional | E-mail opcional — quando definido, a pessoa recebe cópias das notificações por e-mail (e-mails de lead interessado/confirmado) |

#### `list_members` (leitura)

Lista todos nesta conta: o proprietário da conta mais quaisquer pessoas adicionais que tenham sido adicionadas.

Parâmetros: —

#### `remove_member` (destrutiva)

Remove uma pessoa adicional desta conta, identificada por nome ou número de telefone. O proprietário da conta não pode ser removido.

| Parâmetros | | |
|---|---|---|
| `name_or_phone` | string, obrigatório | O nome ou número de telefone da pessoa a ser removida |

#### `resend_member_welcome` (escrita)

Reenvia explicitamente as boas-vindas de um membro por Email, WhatsApp ou Both. Reutiliza tarefas pendentes; estar na fila não significa que foi enviado ou entregue.

| Parâmetros | | |
|---|---|---|
| `member_id` | integer, obrigatório |  |
| `channel` | string, opcional, padrão `Both` |  |

#### `update_member` (escrita)

Atualiza o nome ou e-mail de um membro existente sem recriar o cadastro. A alteração do e-mail coloca o acesso com a identidade visual na fila; omitir um campo preserva seu valor e informar um e-mail vazio o remove.

| Parâmetros | | |
|---|---|---|
| `member_id` | integer, obrigatório |  |
| `name` | string, opcional |  |
| `email` | string, opcional |  |

### Tokens de acesso

Gerencia os tokens que autenticam esta conexão: lista, cria um novo, revoga.

#### `generate_mcp_token` (escrita)

Cria um novo token de acesso MCP para esta conta. O valor do token é retornado UMA VEZ e nunca mais — repasse-o imediatamente para quem chamou e diga para armazená-lo com segurança.

| Parâmetros | | |
|---|---|---|
| `label` | string, opcional | Um rótulo curto nomeando o que vai usar esse token, por exemplo 'n8n workflow' |

#### `list_mcp_tokens` (leitura)

Lista os tokens de acesso MCP da conta. Os valores dos tokens em si nunca são retornados — apenas o id, o label, a data de criação, a data de último uso e se o token foi revogado.

Parâmetros: —

#### `revoke_mcp_token` (destrutiva)

Revoga um token de acesso MCP para que ele não possa mais se conectar. Use list_mcp_tokens para encontrar o token_id. Revogar o token com o qual quem está chamando está atualmente autenticado encerra imediatamente o próprio acesso.

| Parâmetros | | |
|---|---|---|
| `token_id` | integer, obrigatório | O id do token a ser revogado, obtido em list_mcp_tokens |

### Eventos e webhooks

O feed de eventos da conta com cursor, mais as assinaturas de webhook de saída — cria, lista, testa e remove.

#### `create_webhook_subscription` (escrita)

Registra um endpoint de webhook HTTPS que recebe eventos da conta conforme eles acontecem (POSTs assinados) — para sistemas de automação que o cliente executa (apps do Agent SDK, n8n, Zapier, backends personalizados). O segredo de assinatura é retornado UMA VEZ nesta resposta — armazene-o com segurança. Observação: isso NÃO envia para esta sessão MCP; agentes que só conseguem fazer polling devem usar list_account_events.

| Parâmetros | | |
|---|---|---|
| `url` | string, obrigatório | O endpoint HTTPS para o qual os eventos serão enviados via POST |
| `event_types` | string, opcional | Tipos de evento separados por vírgula a serem entregues (opcional; padrão = todos). Mesmos valores de list_account_events. |
| `description` | string, opcional | Um rótulo curto para esta assinatura (ex.: 'meu fluxo n8n') |

#### `delete_webhook_subscription` (destrutiva)

Exclui uma assinatura de webhook — as entregas para seu endpoint param imediatamente. Irreversível (crie uma nova assinatura para retomar; ela receberá um novo segredo).

| Parâmetros | | |
|---|---|---|
| `subscription_id` | integer, obrigatório | ID da assinatura (de list_webhook_subscriptions) |

#### `list_account_events` (leitura)

Consulta o feed de eventos da conta — novas respostas de lead (email/WhatsApp), qualquer email chegando na caixa de entrada do customer (lead ou não), leads sinalizados para revisão, leads se tornando interested/confirmed, meetings marcadas/canceladas, voice calls finalizadas, imports finalizados, support respondido. Paginado por cursor: passe o next_cursor da chamada anterior para obter apenas o que aconteceu desde então. Isso é sobre ATIVIDADE DA CONTA — não eventos de calendário (list_calendar_events / list_calendly_upcoming_events) e não o histórico de um lead específico (list_lead_lifecycle_events).

| Parâmetros | | |
|---|---|---|
| `since_cursor` | integer, opcional, padrão `0` | Retorna somente eventos com id maior que este valor (0 = desde o início do feed). Use o next_cursor da chamada anterior. |
| `event_types` | string, opcional | Tipos de evento separados por vírgula a incluir (opcional; padrão = todos). Válidos: lead_replied_email, lead_replied_whatsapp, lead_sent_for_human_review, lead_became_interested, lead_confirmed, meeting_booked, meeting_cancelled, voice_call_finished, import_finished, support_request_answered, email_received |
| `limit` | integer, opcional, padrão `50` | Máximo de eventos a retornar (padrão 50, máximo 200) |

#### `list_webhook_subscriptions` (leitura)

Lista as assinaturas de webhook da conta com a saúde de entrega (último sucesso/falha, falhas consecutivas, estado desabilitado). Os secrets nunca são exibidos novamente.

Parâmetros: —

#### `test_webhook_subscription` (escrita)

Envia um evento de teste 'ping' assinado para o endpoint de uma assinatura de webhook, para que o cliente possa verificar o receptor e a checagem de assinatura. O resultado da entrega aparece em list_webhook_subscriptions (date_last_success / last_failure_reason) em cerca de 1 minuto.

| Parâmetros | | |
|---|---|---|
| `subscription_id` | integer, obrigatório | ID da assinatura (de list_webhook_subscriptions) |

### Integrações de CRM

Conecta e desconecta um CRM, consulta o status de sincronização, força uma nova sincronização, mapeia campos personalizados e gerencia as integrações Apollo e RD Station.

#### `connect_crm` (escrita)

Conecta uma integração de CRM. Cada CRM precisa de credenciais diferentes: Pipedrive (api_key), RdStation (marketing_api_key e/ou crm_token), HubSpot (access_token), Odoo (url + database + username + api_key), Omie (app_key + app_secret), Agendor/ExactSales/Piperun/Venttra (api_token), SystemeIo (api_key), Twenty (api_key + url opcional quando auto-hospedado). Requer um plano pago ativo. A credencial é VERIFICADA EM TEMPO REAL com o provedor antes de ser armazenada (uma chave inválida retorna um erro e não armazena nada); o campo 'verified' da resposta informa se a verificação foi possível — ExactSales, Piperun, Venttra, e a chave de marketing do RdStation são APIs somente de escrita e são armazenadas sem verificação.

| Parâmetros | | |
|---|---|---|
| `crm_name` | string, obrigatório | Nome do CRM: Pipedrive, RdStation, HubSpot, Odoo, Omie, Agendor, ExactSales, Piperun, SystemeIo, Venttra, Twenty |
| `api_key` | string, opcional | Chave de API (Pipedrive, Odoo, SystemeIo, Twenty) |
| `api_token` | string, opcional | Token de API (Agendor, ExactSales, Piperun, Venttra) |
| `access_token` | string, opcional | Token de acesso (HubSpot) |
| `url` | string, opcional | URL (Odoo; opcional para Twenty quando auto-hospedado) |
| `database` | string, opcional | Nome do banco de dados (Odoo) |
| `username` | string, opcional | Nome de usuário (Odoo) |
| `app_key` | string, opcional | Chave do app (Omie) |
| `app_secret` | string, opcional | Segredo do app (Omie) |
| `marketing_api_key` | string, opcional | Chave de API de marketing (RdStation) |
| `crm_token` | string, opcional | Token do CRM (RdStation) |
| `pipeline_id` | integer, opcional | ID do pipeline em que os negócios são criados (Pipedrive) |
| `funnel_id` | integer, opcional | Id do funil em que os negócios são criados (Agendor) |

#### `disconnect_crm` (destrutiva)

Desconecta uma integração de CRM limpando suas credenciais.

| Parâmetros | | |
|---|---|---|
| `crm_name` | string, obrigatório | Nome do CRM: Pipedrive, RdStation, HubSpot, Odoo, Omie, Agendor, ExactSales, Piperun, SystemeIo, Venttra, Twenty |

#### `get_crm_sync_status` (leitura)

Mostra quantos leads foram sincronizados com cada CRM conectado: contagens de synced, pending e stuck, o horário da última sincronização, e alguns nomes de leads sincronizados recentemente.

Parâmetros: —

#### `list_crm_integrations` (leitura)

Liste todas as integrações de CRM com seu status de conexão, o filtro de status mínimo de lead para sincronização com o CRM e os campos personalizados configurados.

Parâmetros: —

#### `manage_apollo_integration` (escrita)

Conecta ou desconecta a integração da fonte de leads Apollo. Requer um plano pago ativo. action: 'connect' (precisa de api_key) ou 'disconnect'. A api_key é verificada em tempo real junto à Apollo antes de ser armazenada — uma chave inválida retorna um erro e não armazena nada.

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | Ação: connect ou disconnect |
| `api_key` | string, opcional | Chave de API do Apollo (obrigatória para connect) |
| `list_id` | string, opcional | Id da lista do Apollo para sincronizar leads (opcional) |

#### `manage_crm_custom_fields` (escrita)

Gerencia campos personalizados enviados com cada lead para as integrações de CRM. action: 'list', 'add' (precisa de field_name + field_value) ou 'remove' (precisa de field_id).

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | Ação: list, add, ou remove |
| `field_name` | string, opcional | Nome do campo (obrigatório para 'add') |
| `field_value` | string, opcional | Valor do campo (obrigatório para 'add') |
| `field_id` | integer, opcional | Id do campo (obrigatório para 'remove') |

#### `manage_rd_station_crm_lead_source` (escrita)

Ativa ou desativa a importação de contatos do RD Station CRM como leads de prospecção. Requer um plano pago ativo e que o token do RD Station CRM já esteja conectado (use connect_crm). action: 'enable' (opcionalmente delimitado por pipeline_id e deal_stage_id para que apenas contatos vinculados a negócios ali sejam importados) ou 'disable'. Ativar verifica em tempo real o token armazenado junto ao RD Station CRM antes. Não afeta a sincronização de saída de leads para o CRM.

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | Ação: enable ou disable |
| `pipeline_id` | string, opcional | ID do pipeline de negócios do RD Station CRM para limitar a importação (opcional; omita para importar todos os contatos) |
| `deal_stage_id` | string, opcional | ID da etapa do negócio do RD Station CRM dentro do pipeline para limitar a importação (opcional; requer pipeline_id) |

#### `resync_crm_leads` (escrita)

Recoloca manualmente na fila os leads elegíveis que ainda não foram enviados ao CRM para que a sincronização em segundo plano tente novamente. Leads já sincronizados nunca são reenviados (sem duplicatas). O envio acontece em segundo plano em poucos minutos.

Parâmetros: —

#### `update_crm_minimum_status` (escrita)

Define o status mínimo do lead exigido antes de o lead ser sincronizado com o CRM (Pending, Cold, Confirmed, Aware, NotInterested, Interested). Omita 'status' para limpar o filtro e sincronizar todos os leads.

| Parâmetros | | |
|---|---|---|
| `status` | string, opcional | Status mínimo do lead para sincronização com o CRM. Omitir para sincronizar todos os leads. |

### Calendly

Conecta o Calendly, escolhe o tipo de evento em que os leads são agendados e lê os próximos agendamentos.

#### `disconnect_calendly` (destrutiva)

Desconecta a conta do Calendly do cliente: exclui a assinatura de webhook do lado do Calendly, revoga o token de acesso e limpa todos os campos armazenados do Calendly. Passe user_has_confirmed=true somente quando o usuário tiver confirmado explicitamente que deseja desconectar.

| Parâmetros | | |
|---|---|---|
| `user_has_confirmed` | boolean, obrigatório | Deve ser true — o agente precisa ter confirmação explícita do usuário antes de desconectar. |

#### `get_calendly_connection_url` (leitura)

Retorna a URL em que o usuário deve clicar para conectar a conta do Calendly ao Eesier. Compartilhe essa URL com o usuário — ele a abre, faz login no Calendly, clica em Authorize, e a conexão é estabelecida no lado do servidor. Depois que o usuário concluir o fluxo, chame get_calendly_status novamente para confirmar. Idempotente: retorna a mesma URL independentemente de o Calendly já estar conectado ou não (para que o usuário possa reconectar com uma conta diferente).

Parâmetros: —

#### `get_calendly_event` (leitura)

Retorna os detalhes completos de um evento agendado específico do Calendly, incluindo a lista de convidados com seus nomes, e-mails, status, e quaisquer respostas que tenham dado às perguntas de agendamento. Use isso para perguntas de acompanhamento sobre uma reunião específica depois de list_calendly_upcoming_events.

| Parâmetros | | |
|---|---|---|
| `event_uri` | string, obrigatório | URI completa do evento agendado do Calendly (por exemplo 'https://api.calendly.com/scheduled_events/'). Obtenha em list_calendly_upcoming_events. |

#### `get_calendly_status` (leitura)

Retorna o status atual da conexão do Calendly para o cliente: se o OAuth está conectado, o e-mail da conta do Calendly conectada, e qual tipo de evento (se houver) está selecionado como padrão para os links de prospecção.

Parâmetros: —

#### `list_calendly_event_types` (leitura)

Lista todos os tipos de evento ativos na conta Calendly do cliente (ex.: '15-min intro call', '30-min consultation'). Cada entrada inclui uri (use isto ao chamar set_calendly_default_event_type), name, slug, duration_minutes, scheduling_url e is_default. Obrigatório: o Calendly deve estar conectado primeiro.

Parâmetros: —

#### `list_calendly_upcoming_events` (leitura)

Lista os eventos do Calendly agendados no calendário do cliente dentro de um intervalo de datas. Use isto para pedidos no estilo 'o que tenho na minha agenda' / 'tenho alguma reunião amanhã'. Os `start_utc`/`end_utc` retornados vêm em UTC — obtenha `timezone_offset_utc_hours` de `whoami` e converta antes de mostrá-los ao usuário. O Calendly impõe um intervalo máximo de 100 dias.

| Parâmetros | | |
|---|---|---|
| `start_date` | string, opcional | Início da janela no formato YYYY-MM-DD (UTC, inclusive). O padrão é a data UTC de hoje, se omitido. |
| `end_date` | string, opcional | Fim da janela no formato YYYY-MM-DD (UTC, INCLUSIVE — eventos em qualquer horário deste dia são retornados). O padrão é 7 dias após start_date. |
| `status` | string, opcional, padrão `active` | Filtro de status: 'active' (padrão — reservas confirmadas) ou 'canceled'. |

#### `set_calendly_default_event_type` (escrita)

Define o tipo de evento padrão do Calendly. O padrão é o tipo de evento que o Blue Button usa ao gerar links de agendamento dentro das conversas com leads. Passe event_type_uri (preferido — obtenha-o com list_calendly_event_types) ou event_type_name (correspondência aproximada com os tipos de evento ativos). Passe event_type_uri vazio para limpar o padrão.

| Parâmetros | | |
|---|---|---|
| `event_type_uri` | string, opcional | URI completa do tipo de evento do Calendly (preferencial). Passe uma string vazia para limpar o padrão atual. |
| `event_type_name` | string, opcional | Ou o nome de exibição do tipo de evento — comparado por correspondência aproximada com os tipos de evento ativos do cliente. Usado apenas quando event_type_uri não é fornecido. |

### Google Agenda

Conecta o Google Agenda e mexe na agenda: lista, cria, atualiza, exclui e responde a eventos.

#### `create_calendar_event` (escrita)

Cria um evento no Google Calendar. Os horários são em UTC — converta o horário local do cliente usando timezone_offset_utc_hours de whoami ANTES de chamar. Retorna o id do evento e um link do Meet quando um foi gerado.

| Parâmetros | | |
|---|---|---|
| `summary` | string, obrigatório | Título do evento |
| `start_utc` | string, obrigatório | Início do evento em UTC, formato ISO (ex: 2026-07-10T14:00:00Z) |
| `end_utc` | string, obrigatório | Término do evento em UTC, formato ISO |
| `attendees` | string, opcional | E-mails dos participantes separados por vírgula |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

#### `delete_calendar_event` (destrutiva)

Exclui um evento do Google Calendar. Isso cancela o evento para todos os participantes e não pode ser desfeito.

| Parâmetros | | |
|---|---|---|
| `event_id` | string, obrigatório | ID do evento do calendário |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

#### `get_google_connection_url` (leitura)

Obtém a URL do OAuth para o cliente conectar a conta do Google (necessária para as ferramentas do Google Calendar). Compartilhe a URL com o usuário; a conexão é concluída no lado do servidor depois que ele autorizar. Idempotente — também funciona para reconectar.

Parâmetros: —

#### `list_calendar_events` (leitura)

Liste os eventos do Google Calendar do cliente para um dia do calendário (UTC). Retorna start/end no formato ISO UTC.

| Parâmetros | | |
|---|---|---|
| `date` | string, obrigatório | O dia a ser listado, yyyy-MM-dd (interpretado em UTC) |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

#### `respond_calendar_event` (escrita)

Aceita ou recusa um convite de evento do Google Calendar em nome do cliente.

| Parâmetros | | |
|---|---|---|
| `event_id` | string, obrigatório | ID do evento do calendário |
| `accept` | boolean, obrigatório | true para aceitar o convite, false para recusar |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

#### `update_calendar_event` (escrita)

Atualiza um evento do Google Calendar (título, horários, participantes). Passe apenas os campos a alterar. Os horários estão em UTC.

| Parâmetros | | |
|---|---|---|
| `event_id` | string, obrigatório | ID do evento do calendário |
| `summary` | string, opcional | Novo título do evento |
| `start_utc` | string, opcional | Novo horário de início em UTC, formato ISO |
| `end_utc` | string, opcional | Novo horário de término em UTC, formato ISO |
| `attendees` | string, opcional | Novos e-mails dos participantes, separados por vírgula (substitui a lista atual) |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

### Google Ads

O lado pago: campanhas, orçamentos, faturamento, relatórios de performance, diagnóstico, grupos de anúncios, palavras-chave, negativas, anúncios de busca e públicos.

#### `add_google_ads_keywords` (escrita)

Adiciona palavras-chave a um grupo de anúncios em uma campanha do Google Ads. Uma palavra-chave por linha no parâmetro keywords (as palavras-chave podem conter vírgulas). match_type: Broad, Phrase ou Exact (padrão Broad).

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `ad_group_id` | integer, obrigatório | O id do grupo de anúncios (de list_google_ads_ad_groups) |
| `keywords` | string, obrigatório | As palavras-chave a serem adicionadas, UMA POR LINHA |
| `match_type` | string, opcional | Tipo de correspondência: Broad (padrão), Phrase, ou Exact |

#### `add_google_ads_negative_keywords` (escrita)

Adiciona palavras-chave negativas EM NÍVEL DE CAMPANHA a uma campanha do Google Ads (buscas por esses termos nunca acionarão anúncios). Uma palavra-chave por linha. match_type: Broad (padrão), Phrase ou Exact.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `keywords` | string, obrigatório | As palavras-chave negativas a serem adicionadas, UMA POR LINHA |
| `match_type` | string, opcional | Tipo de correspondência: Broad (padrão), Phrase, ou Exact |

#### `create_google_ads_campaign_draft` (escrita)

Cria uma NOVA campanha do Google Ads como RASCUNHO. Ela NÃO veicula até que o cliente recarregue seu saldo através do recharge_url do console retornado — compartilhe esse link e nunca afirme que a campanha está no ar. channel_type: Search (padrão) ou PerformanceMax (recomende o PMax somente depois que uma campanha Search tiver dados reais de conversão).

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | O nome da campanha como aparecerá no Google Ads |
| `daily_budget_brl` | number, obrigatório | Orçamento diário em BRL (positivo, ex.: 20) |
| `channel_type` | string, opcional | Tipo de canal: Search (padrão) ou PerformanceMax |

#### `create_google_ads_search_ad` (escrita)

Cria um Responsive Search Ad em um grupo de anúncios de uma campanha do Google Ads. Títulos com no máximo 30 caracteres cada, descrições com no máximo 90 caracteres cada — UM POR LINHA. Forneça pelo menos 3 títulos e 2 descrições.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `ad_group_id` | integer, obrigatório | O id do grupo de anúncios (de list_google_ads_ad_groups) |
| `final_url` | string, obrigatório | A URL da página de destino para a qual o anúncio direciona |
| `headlines` | string, obrigatório | Os títulos do anúncio, UM POR LINHA, máximo de 30 caracteres cada |
| `descriptions` | string, obrigatório | As descrições do anúncio, UMA POR LINHA, máximo de 90 caracteres cada |

#### `diagnose_google_ads_campaign` (leitura)

Diagnostica por que uma campanha do Google Ads está (ou não está) veiculando: status de veiculação ao vivo, status primário com motivos, e status de aprovação/revisão por anúncio.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |

#### `get_google_ads_audience_status` (leitura)

Obtém o status do público do Customer Match de uma campanha do Google Ads: quantos e-mails estavam no último upload, quando, e se a lista está anexada.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |

#### `get_google_ads_billing` (leitura)

Lê os dados de cobrança/financiamento do Google Ads da conta de uma campanha. section: AccountInfo, AccountBudgets, BillingSetups, Proposals, Invoices (precisa de year+month), ou CampaignBudgets.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `section` | string, obrigatório | Seção: AccountInfo, AccountBudgets, BillingSetups, Proposals, Invoices, CampaignBudgets |
| `year` | integer, opcional | Ano de emissão da fatura (somente Invoices) |
| `month` | integer, opcional | Mês de emissão da fatura 1-12 (somente Invoices) |

#### `get_google_ads_campaign` (leitura)

Obtém o detalhe completo de uma campanha do Google Ads: status do ciclo de vida, motivo da suspensão, saldo de financiamento, o snapshot de desempenho armazenado (spend, impressions, clicks, conversions, CTR, CPC), e o link de gerenciamento/recarga do console. Passe o nome ou o id da campanha.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha (de list_google_ads_campaigns) |

#### `get_google_ads_keyword_ideas` (leitura)

Obtém ideias de palavras-chave com volume de busca do Keyword Planner do Google para uma campanha. Forneça palavras-chave semente (uma por linha) e/ou uma URL de página para extrair ideias.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `seed_keywords` | string, opcional | Palavras-chave iniciais, UMA POR LINHA |
| `page_url` | string, opcional | Uma URL de página para extrair ideias de palavras-chave |
| `max_results` | integer, opcional, padrão `50` | Número máximo de resultados (padrão 50) |

#### `get_google_ads_performance_report` (leitura)

Extrai um relatório de desempenho AO VIVO do Google Ads para uma campanha. report_type: Campaign (totais), AdGroup, Keyword (com pontuação de qualidade), Ad, SearchTerms (o que os usuários realmente pesquisaram), Daily, Device, Conversion, ImpressionShare (parcela de impressões + % perdida por orçamento vs. classificação), AdAssets (rótulos LOW/GOOD/BEST por título/descrição), Hourly, Geographic, Demographics. Custos em BRL.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `report_type` | string, obrigatório | Tipo de relatório: Campaign, AdGroup, Keyword, Ad, SearchTerms, Daily, Device, Conversion, ImpressionShare, AdAssets, Hourly, Geographic, Demographics |
| `date_range` | string, opcional | Intervalo de datas: um predefinido (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, THIS_MONTH, LAST_MONTH) ou uma janela personalizada 'yyyy-MM-dd AND yyyy-MM-dd'. Padrão LAST_30_DAYS. |

#### `list_google_ads_ad_groups` (leitura)

Liste os grupos de anúncios de uma campanha do Google Ads (id, name, status, CPC bid). Os ids de grupo de anúncios são necessários para as ferramentas de palavra-chave e anúncio.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |

#### `list_google_ads_campaigns` (leitura)

Lista as campanhas do Google Ads do cliente com status, tipo de canal, orçamento diário, motivo da retenção, e saldo (recarregado, gasto, restante) — tudo em BRL. O ponto de entrada: chame esta primeiro, depois passe um name ou id retornado para as outras ferramentas google_ads.

Parâmetros: —

#### `list_google_ads_keywords` (leitura)

Lista as palavras-chave de um grupo de anúncios em uma campanha do Google Ads (texto, tipo de correspondência, status, lance de CPC, índice de qualidade).

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `ad_group_id` | integer, obrigatório | O id do grupo de anúncios (de list_google_ads_ad_groups) |

#### `nudge_google_ads_provisioning` (escrita)

Executa novamente o gate de provisionamento de go-live de uma campanha do Google Ads que parece travada após ser financiada (empurra a máquina de estados de provisionamento adiante).

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | Nome ou id da campanha |

#### `refresh_google_ads_audience` (escrita)

Reenvia o público do Customer Match da campanha do Google Ads a partir dos e-mails atuais dos leads do cliente (mantém a lista de remarketing atualizada). Retorna o número de e-mails enviados.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | Nome ou id da campanha |

#### `set_google_ads_campaign_status` (destrutiva)

Pausa, retoma, ou ENCERRA uma campanha do Google Ads. Retomar depende do saldo restante + pelo menos um anúncio habilitado (e uma palavra-chave para Search). ENCERRAR É IRREVERSÍVEL — isso remove a campanha no Google Ads; obtenha a confirmação explícita do cliente antes de encerrar.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `action` | string, obrigatório | Ação: Pause, Resume ou End (End é irreversível) |

#### `sync_google_ads_spend` (escrita)

Atualiza o gasto de uma campanha do Google Ads a partir da API ao vivo do Google (atualiza o snapshot armazenado e os cálculos de financiamento). Chame isso antes de informar números de gasto ou saldo ao cliente.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |

#### `update_google_ads_campaign_budget` (escrita)

Atualiza o orçamento diário de uma campanha do Google Ads (BRL). Retorna o valor efetivo após o ajuste de limites da plataforma.

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `new_daily_budget_brl` | number, obrigatório | O novo orçamento diário em BRL |

### Sites

Cadastra um site e altera por conversa: configurações, subdomínio, código-fonte, snapshots e restaurações, capturas de tela e rastreamento.

#### `archive_website` (destrutiva)

Arquiva (remove) um site.

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site a ser arquivado |

#### `cancel_website_change` (destrutiva)

Cancela a solicitação de alteração em andamento (não concluída) de um site.

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `change_website` (escrita)

Solicita uma alteração em um site. A alteração é enfileirada e renderizada em segundo plano — isso retorna imediatamente com um code id; consulte get_website para verificar a conclusão.

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site a ser alterado |
| `prompt` | string, obrigatório | Prompt descrevendo a alteração desejada |
| `data_storage_required` | boolean, opcional, padrão `false` | True se a alteração exigir armazenamento de dados (um banco de dados) |
| `ignore_existing_code` | boolean, opcional, padrão `false` | True para ignorar o código existente e reconstruir do zero (reformulação completa) |
| `reasoning_mode` | string, opcional | Raciocínio do agente de código: Fast (alterações simples, padrão) ou Thinking (alterações complexas) |
| `generation_type` | string, opcional | Tipo de geração: Fast (padrão) ou Quality |

#### `change_website_subdomain` (escrita)

Altera o subdomínio de um site (a parte antes de .eesier.website).

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |
| `new_subdomain` | string, obrigatório | Nova parte do subdomínio sem o sufixo .eesier.website (apenas letras, números e hífens) |

#### `create_website_snapshot` (escrita)

Cria um snapshot do código atual de um site, marcado com uma descrição, para que possa ser restaurado depois.

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |
| `snapshot_description` | string, obrigatório | Descrição para o snapshot |

#### `export_website_code` (escrita)

Exporta o código atual de um site para um arquivo HTML e o envia por e-mail para o endereço fornecido.

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do website |
| `email_address` | string, obrigatório | Endereço de email de destino |

#### `get_website` (leitura)

Obtenha informações completas sobre um site: título, URL, tipo, idioma, status de geração e link do editor de código.

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `get_website_code` (leitura)

Obtenha o código HTML de uma entrada específica de código do site.

| Parâmetros | | |
|---|---|---|
| `website_code_id` | integer, obrigatório | Id da entrada de código do site |

#### `get_website_settings` (leitura)

Obtenha as configurações configuráveis de um site (título, idioma, restrição, diretrizes do agente).

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `list_website_code` (leitura)

Lista as gerações de código bem-sucedidas para um site (sem o HTML em si), mais recentes primeiro.

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `list_website_snapshots` (leitura)

Lista os snapshots de um site (versões salvas do código), mais recentes primeiro.

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `list_websites` (leitura)

Lista todos os sites do cliente com seu status de geração, URL, e link do editor de código.

Parâmetros: —

#### `register_website` (escrita)

Registra um novo site gerado por IA. A geração roda em segundo plano — isso retorna imediatamente com um id; faça polling de get_website / list_websites para a URL final e o status.

| Parâmetros | | |
|---|---|---|
| `description` | string, obrigatório | Descrição concisa mas completa do site: propósito, principais funcionalidades, público-alvo, estilo e o que vende/promove |
| `language` | string, obrigatório | Código de idioma no formato xx-xx, ex.: pt-br, en-us |
| `application_type` | string, opcional | Tipo de aplicação: Website (padrão) ou LeadCapturePage. Para um site interativo com logins/dashboards, mantenha Website e defina data_storage_required=true. |
| `generation_type` | string, opcional | Tipo de geração: Fast (padrão, sites mais simples) ou Quality (mais lento, melhor para sites complexos) |
| `data_storage_required` | boolean, opcional, padrão `false` | True se o site precisar de armazenamento de dados persistente (contas, pedidos, dashboards); false para sites estáticos. Padrão false. |
| `restricted` | boolean, opcional, padrão `false` | True para restringir o site atrás de uma página de login; false para público. Padrão false. |
| `copy_from_website_id` | integer, opcional | Id opcional de outro site deste cliente para copiar o código |
| `business_or_brand_name` | string, opcional | Nome opcional da empresa/marca existente para a qual o site é destinado (aciona pesquisa online para conteúdo e branding) |

#### `restore_website_snapshot` (destrutiva)

Restaura um snapshot (ou qualquer entrada de código anterior) como o código atual do site.

| Parâmetros | | |
|---|---|---|
| `website_code_id` | integer, obrigatório | Id da entrada de código do site a ser restaurada |

#### `set_website_settings` (escrita)

Atualiza as configurações de um site. Passe apenas os campos que deseja alterar.

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do website |
| `title` | string, opcional | Título do website (máx. 60 caracteres) |
| `language_key` | string, opcional | Chave de idioma, ex.: pt-BR, en-US |
| `restricted` | boolean, opcional | Se o website é restrito por login |
| `guidelines` | string, opcional | Diretrizes persistentes de como o agente deve trabalhar neste website |

### Páginas de captura

O lado inbound: cria páginas de captura, altera, lista e arquiva.

#### `archive_lead_capture_page` (destrutiva)

Arquiva (remove) uma página de captura de leads.

| Parâmetros | | |
|---|---|---|
| `lead_capture_page_id` | integer, obrigatório | Id da página de captura de leads |

#### `change_lead_capture_page` (escrita)

Solicita uma alteração em uma página de captura de leads. A alteração é enfileirada e renderizada em segundo plano — isso retorna imediatamente com um code id.

| Parâmetros | | |
|---|---|---|
| `lead_capture_page_id` | integer, obrigatório | Id da página de captura de leads |
| `prompt` | string, obrigatório | Prompt descrevendo a alteração desejada |

#### `create_lead_capture_page` (escrita)

Cria uma página de captura de leads. A geração é executada em segundo plano — isso retorna imediatamente com um id; consulte list_lead_capture_pages para obter a URL finalizada.

| Parâmetros | | |
|---|---|---|
| `description` | string, obrigatório | Descrição concisa, porém completa: quais informações capturar, público-alvo, a oferta/proposta de valor e quaisquer preferências de design |
| `language` | string, obrigatório | Código de idioma no formato xx-xx, ex.: pt-br, en-us |

#### `list_lead_capture_pages` (leitura)

Lista todas as páginas de captura de leads do cliente com seu status de geração e URL.

Parâmetros: —

### Página do console

A página de dashboard da própria conta dentro da plataforma: lê o HTML, publica uma nova versão escrita por você, reverte na hora e consulta a documentação sempre atual da API de dados e do design.

#### `get_console_page` (leitura)

Obtém a página de dashboard personalizada do console do cliente (/MyConsole): se ela existe, sua URL em produção, se uma build está em execução no momento e o histórico de versões. Toda versão é mantida e pode ser restaurada.

Parâmetros: —

#### `get_console_page_docs` (leitura)

LEITURA OBRIGATÓRIA antes de escrever o HTML da página do console: o contrato da página (sandbox, segurança, autocontenção), a referência completa da Console Data API que a página pode buscar e o design system da Eesier. Sempre renderizada ao vivo a partir da própria fonte de verdade da plataforma — pode chamá-la novamente a qualquer momento, ela nunca fica desatualizada.

Parâmetros: —

#### `get_console_page_html` (leitura)

Obtém o HTML completo da página de dashboard do console do cliente — a versão atual por padrão, ou uma versão específica por id. Use para inspecionar ou modificar a página antes de chamar set_console_page_html.

| Parâmetros | | |
|---|---|---|
| `version_id` | integer, opcional | Id de versão opcional de get_console_page; omita para a versão atual em produção |

#### `restore_console_page_version` (escrita)

Restaura uma versão anterior da página de dashboard do console do cliente — reapontamento instantâneo, sem rebuild. Obtenha os ids de versão em get_console_page.

| Parâmetros | | |
|---|---|---|
| `version_id` | integer, obrigatório | Id da versão a restaurar, de get_console_page |

#### `set_console_page_html` (escrita)

Publica novo HTML para a página de dashboard do console do cliente. VOCÊ é o agente de codificação: escreva você mesmo o HTML completo e autocontido seguindo get_console_page_docs (chame-o primeiro). Armazenado como uma nova versão e colocado em produção instantaneamente; versões anteriores continuam restauráveis.

| Parâmetros | | |
|---|---|---|
| `html` | string, obrigatório | O documento HTML completo e autocontido (doctype até , apenas CSS/JS inline, buscas somente para caminhos relativos /ConsoleDataApi/) |
| `change_summary` | string, obrigatório | Uma frase curta descrevendo o que esta versão é ou altera — exibida no histórico de versões |

### Mídia

Gera imagens, desenhos e vídeos, edita um vídeo e lê tudo que já foi gerado.

#### `create_video` (escrita)

Gera um vídeo curto de IA a partir de um prompt de texto e de uma imagem de referência opcional do primeiro frame. É renderizado em segundo plano — isso retorna imediatamente com um id; consulte list_videos para obter o video_url finalizado.

| Parâmetros | | |
|---|---|---|
| `prompt` | string, obrigatório | O prompt do vídeo |
| `model` | string, opcional | Mecanismo: SeedancePro, SeedanceProFast (padrão), Grok |
| `reference_image_url` | string, opcional | URL opcional da imagem do primeiro frame (https absoluto). O vídeo anima a partir dessa imagem. |
| `duration` | integer, opcional | Duração em segundos (limitada de acordo com o mecanismo) |
| `aspect_ratio` | string, opcional | Proporção da imagem, ex.: 16:9, 9:16, 1:1, 4:3 |
| `resolution` | string, opcional | Resolução: 480p, 720p ou 1080p |

#### `edit_video` (escrita)

Gera um novo vídeo que itera sobre um gerado anteriormente. Quando nenhum reference_image_url é fornecido, a estratégia de frame inicial decide como o frame inicial é produzido.

| Parâmetros | | |
|---|---|---|
| `video_id` | integer, obrigatório | Id do vídeo gerado anteriormente sobre o qual iterar |
| `prompt` | string, obrigatório | O novo prompt do vídeo |
| `model` | string, opcional | Mecanismo: SeedancePro, SeedanceProFast (padrão), Grok |
| `reference_image_url` | string, opcional | URL opcional da nova imagem do primeiro frame (https absoluto). Substitui a estratégia. |
| `first_frame_strategy` | string, opcional | Como lidar com o primeiro frame: KeepPreviousFirstFrame (padrão), EditPreviousFirstFrame, GenerateBrandNewFirstFrame |
| `duration` | integer, opcional | Duração em segundos (limitada de acordo com o mecanismo) |
| `aspect_ratio` | string, opcional | Proporção da imagem, ex.: 16:9, 9:16, 1:1, 4:3 |
| `resolution` | string, opcional | Resolução: 480p, 720p ou 1080p |

#### `generate_drawing` (escrita)

Gera um desenho (formas, wireframes, layouts de página, diagramas, tabelas, gráficos, grids, formas vetoriais, mapas). É executado em segundo plano — isso retorna imediatamente com um id; consulte list_drawings para obter o image_url finalizado.

| Parâmetros | | |
|---|---|---|
| `prompt` | string, obrigatório | Descrição do drawing a ser gerado |
| `caption` | string, opcional | Legenda opcional para acompanhar a imagem entregue |
| `reference_image_url` | string, opcional | URL https absoluta opcional de uma imagem de referência para enviar com o prompt |
| `drawing_id` | integer, opcional | Id opcional de um drawing existente para editar/iterar |

#### `generate_image` (escrita)

Gera uma imagem a partir de um prompt de texto (ou edita imagens existentes passando URLs de referência). A geração é executada em segundo plano — isso retorna imediatamente com um id; consulte list_images para obter o image_url finalizado.

| Parâmetros | | |
|---|---|---|
| `prompt` | string, obrigatório | Prompt descrevendo a imagem a ser gerada |
| `aspect_ratio` | string, opcional | Formato da imagem: Square (1:1), Landscape (mais larga), ou Portrait (mais alta). Padrão Square. |
| `transparent` | boolean, opcional, padrão `false` | Fundo transparente (padrão false) |
| `reference_image_urls` | string, opcional | URLs https absolutas separadas por vírgula de imagens de referência para enviar com o prompt |
| `profile` | string, opcional | Perfil de otimização: None, SocialMediaInstagramPostFeed, SocialMediaInstagramPostStories. Padrão None. |
| `model` | string, opcional | Modelo de geração: OpenAI (padrão), BytePlus. Não altere a menos que o usuário peça. |

#### `get_drawing` (leitura)

Obtém um desenho gerado pelo id — o alvo do polling para generate_drawing. Mostra o status da geração e, quando finalizado, a image_url.

| Parâmetros | | |
|---|---|---|
| `drawing_id` | integer, obrigatório | O drawing_id retornado por generate_drawing |

#### `get_image` (leitura)

Obtém uma imagem gerada pelo id — o alvo do polling para generate_image. Mostra o status da geração e, quando finalizada, a image_url.

| Parâmetros | | |
|---|---|---|
| `image_id` | integer, obrigatório | O image_generation_id retornado por generate_image |

#### `get_video` (leitura)

Obtenha um vídeo gerado pelo id — o alvo de polling para create_video/edit_video (list_videos só mostra vídeos FINISHED, portanto faça polling neste para os que estão em andamento). is_finished=true com um video_url significa concluído; is_finished=true sem uma URL significa que a renderização falhou.

| Parâmetros | | |
|---|---|---|
| `video_id` | integer, obrigatório | O video_id retornado por create_video ou edit_video |

#### `list_drawings` (leitura)

Liste os desenhos gerados (mais recentes primeiro, paginado). Inclui o status de geração de cada desenho e, uma vez finalizado, seu image_url.

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `1` | Número da página (1 = primeira página) |
| `page_size` | integer, opcional, padrão `10` | Tamanho da página (padrão 10, máximo 50) |

#### `list_images` (leitura)

Lista as imagens geradas (mais recentes primeiro, paginado). Inclui o status de geração de cada imagem e, uma vez concluída, o seu image_url.

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `1` | Número da página (1 = primeira página) |
| `page_size` | integer, opcional, padrão `10` | Tamanho da página (padrão 10, máximo 50) |

#### `list_videos` (leitura)

Lista os vídeos gerados anteriormente (mais recentes primeiro, paginado). Somente vídeos concluídos com sucesso e com uma URL são retornados.

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `1` | Número da página (1 = primeira página) |
| `page_size` | integer, opcional, padrão `10` | Tamanho da página (padrão 10, máximo 50) |

### Pesquisa online

Agenda uma pesquisa na web aberta e lê o resultado quando fica pronta.

#### `get_online_search` (leitura)

Obtenha o status e o resultado de uma busca online.

| Parâmetros | | |
|---|---|---|
| `online_search_id` | integer, obrigatório | Id da busca online |

#### `list_online_searches` (leitura)

Lista as buscas online mais recentes do cliente (até 10, mais recentes primeiro) com seu status.

Parâmetros: —

#### `register_online_search` (escrita)

Registra uma tarefa de pesquisa on-line. Ela roda em segundo plano — isso retorna imediatamente com um id; faça polling de get_online_search para obter o resultado. Opcionalmente, envia o resultado por e-mail quando terminar.

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | A consulta a ser pesquisada online |
| `send_to_email` | string, opcional | Endereço(s) de email opcional(is), separados por vírgula, para enviar o resultado quando finalizado |
| `type` | string, opcional | Profundidade da busca: Fast, Standard (padrão) ou Deep |

### Suporte

A linha direta com o time da eesier — abre um chamado e lê os que já estão abertos.

#### `create_support_request` (escrita)

Abre uma linha direta com a equipe de suporte da Blue Button. Este é VOCÊ, o agente conectado, falando diretamente com a equipe de suporte e engenharia — use isso para fazer uma pergunta ou relatar um problema por iniciativa própria em segundo plano (o usuário final NÃO é notificado), ou quando o usuário pedir explicitamente que você entre em contato com o suporte. Especifique o type (technical, sales, human ou question) e a severity (low/medium/high/critical). A resposta da equipe volta para você — leia-a depois com list_support_requests.

| Parâmetros | | |
|---|---|---|
| `message` | string, obrigatório | O que você quer perguntar ou relatar à equipe do Blue Button |
| `type` | string, obrigatório | Tipo de solicitação: 'technical' (problema de produto/técnico), 'sales' (comercial, cobrança, plano — o cliente quer que um representante de vendas entre em contato), 'human' (o cliente pede um contato humano, sem motivo específico), ou 'question' (uma solicitação simples de informação que você não consegue responder sozinho) |
| `severity` | string, obrigatório | Qual o nível de urgência: 'low', 'medium', 'high' ou 'critical' |

#### `list_support_requests` (leitura)

Lista as solicitações de suporte do cliente — sua thread com a equipe do Blue Button — com status, type, severity de cada solicitação, e a resposta da equipe (null até que respondam). Filtre por status: pending, answered, closed, ou all (padrão all).

| Parâmetros | | |
|---|---|---|
| `status` | string, opcional, padrão `all` | Filtro de status: pending, answered, closed, ou all (padrão all) |

### Incidentes

Lê os incidentes da plataforma que afetam esta conta.

#### `list_incidents` (leitura)

Lista os incidentes da plataforma (interrupções / degradações / instabilidades) reportados pela equipe do Blue Button, cada um com sua linha do tempo pública de atualizações. Retorna incidentes em andamento (ativos) e incidentes passados resolvidos recentemente. Chame esta ferramenta quando o usuário perguntar se a plataforma está com problemas, ou quando chamadas de ferramentas estiverem falhando inesperadamente — um incidente ativo geralmente explica as falhas.

| Parâmetros | | |
|---|---|---|
| `scope` | string, opcional | Quais incidentes retornar: 'active' (somente em andamento), 'past' (somente resolvidos) ou 'all' (padrão) |
| `limit` | integer, opcional | Número máximo de incidentes passados a retornar (padrão 10, máximo 50) |

## Perguntas frequentes

**Esta lista está sempre atualizada?**

Sim. Ela é gerada a partir do registro de ferramentas do servidor MCP em execução, e um teste de build falha se a página e o servidor divergirem.

**Preciso ler isto para usar o eesier?**

Não. Seu agente descobre todas as ferramentas sozinho assim que conecta. Esta página serve para decidir se vale integrar e para depurar uma chamada específica.

**Meu agente consegue fazer algo que eu não consigo?**

Não. O token age como a sua conta e nada além disso — os mesmos dados, os mesmos limites, as mesmas permissões.

**O que acontece se eu revogar um token?**

A conexão para de funcionar na hora. Gere um novo no console e reconecte; nada mais é afetado.

**As descrições daqui são as mesmas que o meu agente vê?**

Exatamente as mesmas. Os nomes, as descrições e os textos de parâmetro desta página são as strings literais que o servidor envia ao seu agente — por isso ficam em inglês.