Lista os grupos coletados (slug, nome, nº de mensagens, data da última). Use o slug nas outras ferramentas.

Lê as mensagens de um grupo (texto + transcrições já feitas). Filtra por data inicial e limita a quantidade. Default: as 50 mais recentes (passe 'limite' maior, ou 'desde', pra ir além) — evita despejar o grupo inteiro quando você só quer o contexto recente. Cada msg traz timestamp (UTC) e hora_brt (hora de Brasília já convertida) — use a hora_brt pra falar de horário com o operador, NÃO leia o UTC como se fosse local. Mídia com texto junto traz esse texto em legenda (descreve a mídia), não em texto (que é msg de texto solta) — assim você sabe que a legenda se refere ÀQUELE vídeo/imagem, e não confunde com um texto enviado depois. Mensagens coladas do mesmo remetente (rajada: vídeo+texto+áudio numa tacada) compartilham um rajada (id) — trate-as como um bloco do mesmo assunto, não itens soltos.

Busca um texto nas mensagens e transcrições. Sem 'grupo', procura em todos. Retorna os trechos que casam (mais recentes primeiro), limitado a 'limite' (default 50) pra não estourar — se truncar, o retorno avisa em 'truncado'.

Transcreve áudio/vídeo (MLX local, large-v3) e devolve o texto; reusa cache. UMA mídia específica: passe mediaPath (campo 'midia' de ler_mensagens) OU id (campo 'id' da mensagem) — os dois funcionam; qualquer outro nome de parâmetro é ignorado. SEM os dois: transcreve um lote dos pendentes do grupo (até 8 NOVOS por chamada; o que já tem transcrição não ocupa vaga e vem em em_cache; os que só estão na nuvem baixam em paralelo). Se sobrar além do teto, o retorno traz restantes — chame de novo e o lote AVANÇA. Em modo remoto a transcrição é publicada na nuvem, então ler_mensagens passa a trazer transcricao.

Retorna todo o conteúdo de um grupo num dia (texto + transcrições) para a IA resumir. Default: hoje (UTC).

Mostra de fato uma imagem (print/screenshot/sticker) de um grupo para a IA enxergar. Use quando precisar entender o conteúdo visual — ex.: print de um bug que o cliente mandou. Sem mediaPath, mostra a ÚLTIMA imagem/figurinha do grupo (atalho pra 'vê a imagem que acabou de chegar', sem precisar de ler_mensagens antes).

Mostra um vídeo ou GIF pra IA enxergar, amostrando alguns frames (via ffmpeg). Use pra entender o conteúdo visual de um GIF (reação/meme) ou de um vídeo mudo. Para o áudio do vídeo, use 'transcrever'; pra entender imagem e fala juntos (ex.: cliente mostrando um erro), use 'assistir_video'. Sem mediaPath, mostra o ÚLTIMO vídeo/GIF do grupo.

Assiste um vídeo com o Gemini (imagem e áudio juntos) e devolve o que aparece e o que é falado, com tempos MM:SS. Use quando o conteúdo do vídeo importa: cliente mostrando erro na tela, explicando algo em vídeo, ou mandando LINK de vídeo (YouTube, Instagram, TikTok). Custa ~US$ 0,03–0,05 por minuto de vídeo (OpenRouter): chame sob demanda, nunca em lote. GIF/meme ou só uma olhada rápida: prefira 'ver_video' (grátis). Vídeo do chat: grupo + id (campo 'id' de ler_mensagens) ou mediaPath; sem os dois, o ÚLTIMO vídeo do grupo. Link: url (grupo opcional). pergunta foca a resposta. Teto: 20 min de vídeo.

Lê o conteúdo de texto de um documento que o cliente mandou (PDF, .docx, .txt, .csv...). Use quando precisar entender o que diz um arquivo recebido — ex.: contrato, orçamento, planilha exportada. Se vier 'note' avisando que não há texto extraível (PDF escaneado), tente 'ver_imagem' no mesmo arquivo. Sem mediaPath, lê o ÚLTIMO documento do grupo.

Acha QUEM é quem: nome, papel (me = você, team = seu time, client = cliente), jid de DM e o slug da DM pronto pra ler_mensagens. Telefone e LID da mesma pessoa vêm numa linha só. PASSE busca (pedaço do nome ou o número, com ou sem formatação/nono dígito) — a conta pode ter milhares de contatos e sem filtro só vêm os 100 primeiros. Se você JÁ TEM o número, nem precisa: a DM é o slug dm-<55DDDnúmero> direto em ler_mensagens/responder.

Chame ANTES de redigir qualquer mensagem pra um chat. Devolve o que a conta já usou nas últimas 5 mensagens ali (aberturas, verbos, pontuação, tamanhos), o estado da conversa (ativa/fria, o que o cliente deixou em aberto, se o operador já respondeu na mão) e instrucoes numéricas pra variar. Escreva seguindo as instruções; o responder revisa e recusa o que estourar.

Revisa um rascunho SEM enviar: repetição contra as últimas mensagens do chat, dois-pontos e outros tells, auto-incriminação, desculpa, tratamento. Devolve ok/score/hits/sugestoes. No modo 'confirmar', revise, corrija e só então mostre o texto ao operador.

Envia uma mensagem de texto no WhatsApp — para um GRUPO (slug/nome/jid) ou um CONTATO em DM (dm-<55DDDnúmero>). PRIMEIRO CONTATO funciona: o número NÃO precisa estar em listar_contatos nem ter conversa anterior — passe dm-<55DDDnúmero> do jeito que o número veio (com ou sem o nono dígito) e o coletor confirma no WhatsApp qual é a conta antes de enviar. Se o retorno trouxer jid_corrigido_de, use o slug_correto dali em diante; número fora do WhatsApp é recusado com motivo, nada sai. Primeiro contato SEMPRE passa pelo OK do operador no texto, mesmo se outros chats rodam em modo autônomo (conduta na skill comunicacao-cliente). VOZ: carregue a skill de voz do operador (voz-do-operador ou a preenchida desta máquina) ANTES de redigir — ela define grafia, registro e a camada de venda do operador, medidos no texto real dele. Depois comunicacao-cliente (conduta: o que responder, três modos, erro sem se rebaixar, urgencia). CONFIRMAÇÃO: cada chat tem um modo (definir_modo). No modo 'confirmar' (DEFAULT), você DEVE ter mostrado o texto e recebido OK do operador antes de chamar. No modo 'autonomo', pode enviar direto. O retorno traz o modo do chat. (Isto é convenção que você respeita, não trava de código — não burle o 'confirmar'.) BALÕES: por default o texto é fatiado em até 3 balões (parágrafos em branco = quebras explícitas suas). Use um_balao: true quando a mensagem deve chegar INTEIRA num balão só — texto coeso/técnico (changelog, lista, instruções passo a passo), ou quando o operador pedir 'manda numa mensagem só'. Quando VOCÊ já decidiu a quebra (4, 5 balões…), passe baloes (lista, um item = um balão, até 8) em UMA chamada — NUNCA chame responder várias vezes pra simular balões: cada chamada é uma entrega separada com visto/digitando. Conversa curta e informal fica melhor em balões. REVISÃO: antes de enviar, o texto passa por revisão (repetição contra as últimas mensagens do chat, dois-pontos e tells, auto-incriminação, desculpa). Recusa devolve hits e sugestões; reescreva e chame de novo. Chame preparar_resposta ANTES de redigir. ENTREGA: devolve um TICKET na hora; a mensagem sai depois com latência humana (segundos numa conversa ativa, minutos a horas numa fria), visto antes do digitando, digitação na velocidade do operador. Novo responder no mesmo chat SUBSTITUI o ticket anterior. Acompanhe com status_envio; cancelar_envio cancela. Se o plantão avisar 'Entrega interrompida', releia o chat e responda de novo.

Envia um arquivo para um grupo no WhatsApp: imagem com legenda, documento/PDF, áudio (nota de voz) ou vídeo. REGRA: só chame DEPOIS de confirmar com o usuário o destinatário e o arquivo. Se houver legenda (caption), o texto deve passar pela skill de voz do operador e ser confirmado, igual ao 'responder'. O 'path' pode ser absoluto (arquivo novo no disco) OU o mediaPath de uma mensagem já recebida (campo 'midia') para reenviar.

Cancela uma entrega humanizada AGENDADA ou EM ANDAMENTO: o balão que ainda não saiu não sai; o que já saiu fica. Use na hora, SEM confirmar, quando o operador disser 'cancela'/'para'/'não manda'. Por chat (grupo) ou por ticket. Depois chame ler_mensagens no chat pra ver o que chegou a sair antes de reenviar.

Estado de uma entrega humanizada: por chat (grupo) ou por ticket. Devolve estado (agendado/entregando/entregue/cancelado/interrompido), motivo, balões enviados/total e previsão.

Edita uma mensagem JÁ ENVIADA por você/pela IA (o WhatsApp marca 'editada'). Use pra corrigir erro ou atualizar info numa msg recente. Só funciona em mensagem PRÓPRIA (fromMe) — ATENÇÃO: mensagens que o OPERADOR mandou do celular também são fromMe (mesma conta) e são editáveis por esta tool. Por isso NUNCA escolha o msgId por posição ('a última'): pegue via ler_mensagens e CONFIRA que o texto da msg alvo é exatamente o que você quer substituir antes de chamar. CONFIRMAÇÃO: mesma convenção do responder — no modo 'confirmar', mostre o texto novo e espere OK antes de chamar.

Reage com um emoji a uma mensagem (👍, ❤️, 😂...). Às vezes a resposta humana é SÓ uma reação — prefira isso a um balão de 'ok!' quando couber. Emoji vazio ('') REMOVE a reação. O msgId vem do ler_mensagens. A tool resolve sozinha a key completa (autor/fromMe) pelo histórico — participant/fromMe manuais só como override raro.

Edita o PERFIL do WhatsApp do operador: nome, recado/'sobre' (status) e/ou foto. Passe só os campos que quer mudar. 'foto' é caminho absoluto de imagem OU o mediaPath de uma mensagem recebida. CONFIRMAÇÃO: o perfil é PÚBLICO (todo contato vê). Você DEVE mostrar ao operador o que vai mudar e ter o OK ANTES de chamar — mesma convenção do 'responder'. Não é trava de código; não burle. LIMITE: catálogo, localização, link e horário-oficial do business são read-only no WhatsApp (não editáveis por aqui).

Marca o grupo como resolvido (tira da fila de pendências) até o momento dado. Sem 'ate', usa agora.

Silencia/dessilencia um grupo (coleta mas não alerta).

Salva/atualiza a nota livre (mini-CRM) de um grupo. Nota vazia remove a nota.

Lê as notas dos grupos. Com 'grupo', traz só a dele; sem, traz todas.

Liga/desliga a NOTIFICAÇÃO NO MAC (pro humano) quando chega mensagem de cliente num chat — grupo OU DM — por slug. NÃO acorda o agente nem faz o Claude reagir sozinho: é só um aviso de tela pro operador. (Pra o AGENTE ser acordado por mensagem nova — modo monitor/autônomo — arme um Monitor no data/<slug>/messages.jsonl, ver CLAUDE.md.) Opt-in por conversa. Depois de notificado, use novidades pra puxar o que chegou.

Define se um chat está em modo AUTÔNOMO (a IA envia sem confirmar) ou CONFIRMAR (default: a IA mostra o texto e espera OK do operador antes de enviar). Persiste por chat — você liga uma vez e vale até desligar, sem depender de re-combinar a cada msg. O responder lê esse modo. É convenção respeitada pela IA, não trava de código. Também liga o agente de triagem do chat (agente: off/issue/pr) e escolhe o executor (claude/copilot).

Puxa as mensagens novas dos chats marcados com alerta desde a última vez que você viu. FILTRA só mensagens de CLIENTE (descarta as suas e as do time) — em grupo interno isso pode voltar vazio mesmo tendo msg nova; nesse caso o retorno traz ignoradas_por_papel e uma nota sugerindo ler_mensagens. Use ao ser notificado de mensagem nova. Avança o checkpoint (não repete na próxima) a menos que marcar=false. Com 'grupo', restringe a um chat.

Define as ETIQUETAS de um chat (empresa/contrato/pessoal — ex.: 'Empresa A', 'Freelance'). É o rótulo que diz de qual contexto de trabalho aquele grupo/contato é — use pra saber COM QUEM está falando antes de redigir. Lista vazia remove todas. Pra LER as etiquetas de todos os chats, use estado_triagem (campo etiquetas).

Define o estado comercial de um chat: estado (ativo/encerrado/pausado/sem), início e fim (YYYY-MM-DD), valor mensal e nota. Só os campos passados mudam. O dashboard cruza isso com a atividade pra apontar cliente ativo demais pro contrato, renovação próxima e custo por entrega. Pra ler, use a tool dashboard. limite_mensagens = mensagens do cliente em 30 dias que o plano comporta (null tira o limite); acima dele o dashboard aponta acima-do-contrato.

Registra uma funcionalidade ENTREGUE pra um cliente (chame ao concluir uma entrega). Alimenta o contador de entregas por cliente do dashboard. Se passar ref (URL do PR/issue) e ela já estiver registrada NESTE chat, não duplica (a mesma ref em outro cliente é outra entrega). PRs mergeados que fecham issues da triagem entram sozinhos; use esta tool pro que não passou por PR.

Visão de negócio por cliente: atividade 30 d, contrato, entregas 30 d/total, mensagens e valor por entrega, e SINAIS (encerrado-ativo, sem-contrato-ativo, pausado-ativo, renovacao-30d, sem-entrega-30d) com uma frase explicando cada um. Use pra responder 'quem está ativo demais pro contrato', 'quem renova este mês', 'quantas entregas o cliente X recebeu'. so_sinais: true devolve só as linhas com sinal. Contratos e entregas refletem na hora; atividade de mensagens pode ter até 60 s de atraso.

Quem está esperando resposta e de qual projeto, em todos os chats coletados (o operador não precisa abrir o WhatsApp). Use pra 'quem me mandou mensagem?', 'tem cliente esperando?', 'o que rolou hoje?'. Cada item traz o chat, o projeto (cliente, pasta do repo e GitHub, quando o chat está linkado) e, se alguém espera, esperando (quem, prévia, desde quando, há quanto tempo); pendentes vêm primeiro, quem espera há mais tempo no topo. Esperando = a última fala é de cliente (ou te mencionaram) e ninguém da conta respondeu depois; chat silenciado ou marcado resolvido não entra. Só lê: não marca nada como visto (ao contrário de novidades). todos: true inclui os chats em que cliente escreveu desde desde mesmo já respondidos, com do_cliente_desde. Conversa que o cliente fechou ("ok", "combinado", "valeu", figurinha) não entra: vem só a contagem em encerrados. Espera cuja última fala do cliente passou de dias (default 7) vem resumida em antigos (nome e tempo). Ao responder o operador, agrupe por projeto, diga em uma linha o que cada um quer e ainda descarte o que for só social; cite os antigos numa linha. Num repositório ligado a um chat (.claude/whatsapp.json, bloco wa-link no CLAUDE.md), passe grupos com o(s) slug(s) dele em vez de ler a caixa inteira; pra 'teve mensagem nova?' esta tool basta, e ler_mensagens (bem mais caro) só entra se precisar do conteúdo. Se vier avisos (serviço de IA falhando), mostre ANTES de tudo, numa linha cada. Mostre a data e hora de Brasília da última mensagem (ultima_brt) com quanto tempo faz em relação a agora_brt (ex: "28/10 09:34, há 2h"). Pra ler a conversa, ler_mensagens(grupo).

Retorna o estado de triagem inteiro (resolved/muted/notes/lastSeen/copilot/alertar/autonomo/etiquetas/agente/executor) pra IA saber o que já foi tratado, quais chats acompanha (copilot), quais alertam, e o modo de envio de cada um (autonomo: true = envia direto; ausente = confirmar antes). Contrato de cliente não vem aqui: ele fica nas tools dashboard e definir_contrato.

Lê o Google Agenda do operador (todas as agendas da conta) numa janela de datas; padrão hoje até daqui a 7 dias. Cada evento traz agenda e id (use em agenda_editar/agenda_apagar) e hora_brt em horário de Brasília; organizador = reunião de outra pessoa, que só ela altera. Desconectado = erro pedindo para reconectar em /agenda no painel.

Cria um evento no Google Agenda do operador. Marque só o que foi combinado de fato (data e hora claras) ou o que o operador pediu. CONVIDADOS: o Google manda e-mail de convite na hora. Só inclua convidados quando o operador pedir, e antes mostre a ele o evento (título, quando, quem) e espere o OK. Sem convidados, ninguém recebe nada. Devolve o evento criado com id, agenda, hora_brt, link e o link do Meet.

Altera um evento (só os campos passados). Início sem fim mantém a duração. convidados SUBSTITUI a lista. CONVIDADOS: o Google manda e-mail de convite na hora. Só inclua convidados quando o operador pedir, e antes mostre a ele o evento (título, quando, quem) e espere o OK. Sem convidados, ninguém recebe nada. Em evento recorrente, muda só esta ocorrência.

Apaga um evento do Google Agenda. Só apague o que o operador pediu explicitamente. Se o evento tiver convidados, o Google avisa o cancelamento por e-mail.