Ferramentas

O servidor oferece vinte e cinco ferramentas em sete grupos. Risco Baixo indica leitura. Risco Médio altera dados internos. Risco Alto pode ocupar a agenda de uma pessoa ou avisar o cliente final.

Listas devolvem data, has_more e next_cursor. O limite padrão no MCP é 20 itens, e o máximo é 100. Use next_cursor como cursor na chamada seguinte sem alterar os filtros.

Contatos

buscar_contatos

Pode recusar busca curta, limite fora da faixa, status inválido ou cursor reaproveitado com filtros diferentes.

ver_contato

Um identificador inexistente ou pertencente a outra conta é tratado como contato não encontrado.

criar_contato

O telefone precisa resultar em 10 a 15 dígitos com DDI e DDD. Telefone já cadastrado é conflito. E-mail, data ou situação inválidos são recusados. Uma repetição idêntica na mesma faixa de dez minutos devolve o resultado original em vez de criar duplicata.

atualizar_contato

Somente os campos enviados são alterados. O valor anterior é sobrescrito. A ferramenta recusa identificador inexistente, e-mail, data ou situação inválidos.

Catálogo

listar_servicos

Pode recusar busca curta, limite fora da faixa ou cursor reaproveitado com filtros diferentes.

ver_servico

Um identificador inexistente ou pertencente a outra conta é tratado como serviço não encontrado.

Equipe

listar_profissionais

Pode recusar UUID inválido, limite fora da faixa ou cursor reaproveitado com filtros diferentes.

ver_profissional

Um identificador inexistente ou pertencente a outra conta é tratado como profissional não encontrado.

Agenda

ver_horarios_livres

A ferramenta recusa serviço ou profissional inexistente, agenda não conectada, intervalo amplo demais e data distante demais. Uma indisponibilidade temporária da agenda também gera recusa. A consulta não reserva o horário.

listar_agendamentos

de e ate aceitam data ou data e hora ISO. Sem fuso, o fuso da conta é assumido (Brasília é o padrão de conta nova). A ferramenta recusa período invertido, situação inválida e cursor usado com filtros diferentes.

ver_agendamento

Consulte esta ferramenta antes de alterar. Um identificador inexistente ou pertencente a outra conta é tratado como agendamento não encontrado.

criar_agendamento

Use em data_hora o inicio devolvido por ver_horarios_livres, sem modificar. A ferramenta recusa horário ocupado, serviço inativo, serviço com pagamento antecipado em conta com cobrança automática ligada, entidade inexistente e profissional que não pode atender. Se houver conflito, consulte os horários outra vez e escolha outro. Uma repetição idêntica na mesma faixa de dez minutos devolve o resultado original.

alterar_agendamento

Situações aceitas: agendado, confirmado, realizado, no_show, cancelado, aguardando_pagamento, cancelado_por_nao_pagamento, cancelado_estornado e cancelado_lgpd.

A ferramenta aplica estas recusas:

• Ocorrência de série não pode ser alterada.
• motivo_cancelamento só pode acompanhar status: "cancelado".
• Remarcação só pode terminar em agendado ou confirmado.
• cancelado, realizado e no_show são estados finais.
• profissional_id: null e duracao_minutos: null não são aceitos.
• Horário ocupado é conflito e exige uma nova consulta de disponibilidade.

Cancelar não tem volta. Para atender novamente, crie outro agendamento. Se uma repetição receber transição proibida e o estado atual já for o solicitado, considere que a primeira alteração foi concluída.

Base de conhecimento

A base de conhecimento é o que o agente sabe responder. Ela pertence a um agente, não à conta: quem tem mais de um agente escolhe em qual mexer.

Regras que valem nas quatro ferramentas de documento:

• agent_id é opcional. Sem ele, vale o agente padrão da conta. Se a conta não tiver padrão definido, a chamada é recusada pedindo o identificador.
• Documento marcado como protegido não pode ser editado por aqui. Abra um ticket no suporte.
• Não existe apagar. Use atualizar_documento com ativo: false, que tem volta.
• Fatias internas do documento nunca aparecem, e um identificador de fatia é tratado como não encontrado.

listar_agentes

Use antes das demais quando a conta tiver mais de um agente.

listar_documentos

O texto completo vem em ver_documento. Cursor reaproveitado com filtros diferentes é recusado.

ver_documento

Consulte antes de reescrever, para não apagar o que já estava lá.

criar_documento

O texto é fatiado e indexado automaticamente, então o agente passa a responder a partir dele em seguida.

Esta ferramenta consome o limite de documentos do plano. Atingido o limite, a chamada é recusada com a mensagem do próprio serviço de limites.

Título já usado no mesmo agente é conflito: use atualizar_documento. Uma repetição idêntica na mesma faixa de dez minutos devolve o resultado original em vez de criar duplicata.

Sob concorrência, o serviço de indexação pode pedir uma nova tentativa em alguns segundos.

atualizar_documento

Mudar o conteúdo reindexa o documento. ativo: false deixa o documento fora das respostas do agente sem apagar nada.

Relatórios

ver_relatorio

Sem de e ate, vale o mês corrente. As duas datas andam juntas: informar só uma é recusado.

A resposta traz periodo, agenda, perdas, dinheiro, conversas, produtividade, custo_ia, por_canal, por_profissional, por_agente, contatos_novos e nps_medio.

Conta com um agente só recebe por_agente vazio, e isso não significa ausência de dados. Conta sem plano configurado é recusada com explicação.

Automações

Automação criada pelo MCP nasce desligada. Antes de criar ou editar, consulte as opções da conta para usar nomes de etiquetas, fases, serviços, mídias e agentes que existem de verdade.

listar_automacoes

Não pagina porque cada plano tem um teto pequeno de automações. A resposta nunca inclui a URL secreta nem o segredo de webhook.

ver_automacao

Use antes de editar para preservar a configuração atual. Um identificador inexistente ou pertencente a outra conta é tratado como automação não encontrada. A resposta diz se há webhook, mas não revela a URL secreta nem o segredo.

ver_opcoes_de_automacao

Use antes de criar ou editar. Nome inventado de etiqueta, fase ou serviço pode deixar a automação sem efeito. A resposta também avisa quando um gatilho por intenção depende do plano.

criar_automacao

Automação criada pelo MCP nasce desligada, sempre. Não existe argumento para criar ligada, e isso é proposital: se existisse, criar já ligada seria um pedido só e a confirmação em dois passos de atualizar_automacao poderia ser contornada. Para ligar, chame atualizar_automacao com ativa: true.

Sem cooldown_segundos, a automação nasce com 300 segundos de intervalo mínimo entre disparos. Envie 0 se ela precisa disparar toda vez. A ferramenta recusa configuração inválida, agente de outra conta, gatilho por intenção fora do plano e teto de automações atingido. Uma repetição idêntica na mesma faixa de dez minutos devolve o resultado original.

atualizar_automacao

Enviar gatilhos ou acoes substitui a lista inteira, não acrescenta itens. Consulte a automação antes e envie a lista completa. Ligar uma automação desligada exige dois pedidos: o primeiro devolve os gatilhos e as ações para a pessoa conferir, o segundo usa confirmar: true. Desligar vale na hora.

A confirmação em dois passos evita acidente do modelo, não impede um ator malicioso. A proteção real é a ferramenta de escrita começar desligada e só o dono ligá-la na tela de Integrações.

apagar_automacao

Apagar exige dois pedidos. O primeiro nunca apaga e devolve o nome e os disparos da automação. Depois de a pessoa confirmar, envie o segundo pedido com confirmar: true. Um identificador inexistente ou de outra conta é tratado como automação não encontrada. Apagar não tem volta.

Recusas comuns a todas

Uma chamada também pode ser recusada quando:

• O servidor MCP ou a ferramenta está desligado.
• A chave está ausente, inválida, revogada, suspensa ou vencida.
• Uma chave read tenta usar ferramenta de escrita.
• O plano não inclui MCP ou a conta está suspensa.
• Um campo obrigatório está ausente ou um argumento não atende ao formato e ao limite.
• O limite de requisições foi atingido.

A IA recebe a mensagem de negócio em português como erro de ferramenta. Falhas inesperadas devolvem somente uma mensagem genérica, sem detalhes técnicos.