Referência de ferramentas

Todas as 26 ferramentas MCP da Certivant agrupadas pela tarefa que executam — triagem da fila, envio e acompanhamento de formulários, ações do ciclo de vida, explicação de decisões e risco de rede, sessões de verificação de identidade ao vivo, consultas ao registro de KYB e relatórios — com o que cada uma retorna e o que deliberadamente não retorna.

O catálogo tem 26 ferramentas por padrão, limitado deliberadamente a essa quantidade. Acima disso, a precisão de seleção de ferramentas pelo modelo cai de forma mensurável; por isso, uma nova capacidade substitui ou consolida outras em vez de acrescentar mais — list_expiring_documents recebe um argumento mode em vez de trazer duas ferramentas irmãs, e as ferramentas de verificação de identidade ao vivo unem listagem e detalhe em uma só, e reagendar / cancelar / reconvidar ficam em outra. Três ferramentas de conformidade adicionais existem atrás de flags do operador (veja o final desta página).

Cada ferramenta é anotada com honestidade (readOnlyHint, destructiveHint, idempotentHint), para que o seu host possa controlar as que têm consequências no mundo real. Cinco ferramentas enviam e-mails de fato (ou SMS). Duas são destrutivas. As demais apenas leem.

send_form_to_customer, send_verification_reminder e renew_verification enviam e-mails a clientes reais. Nenhuma delas é idempotente: chamar uma duas vezes envia dois e-mails. Se uma chamada falhar, verifique list_form_deliveries antes de tentar de novo, em vez de reenviar às cegas.

Organizar o dia

Ferramenta	Retorna	Não retorna
`get_todays_queue`	Um snapshot agregado de toda a organização: contagens por status, encaminhadas e aguardando segunda revisão, paradas (sem atividade há N dias, padrão 7), verificações de sanções que falharam, encaminhamentos além do SLA de revisão, recheques de KYC vencidos, além da atividade de 24 h e de 7 dias.	Apenas contagens — sem IDs de requisição, sem nomes, sem dados de solicitantes. Use as ferramentas de listagem para agir sobre um grupo.
`find_verification`	Busca de texto livre por nome da pessoa, e-mail, nome da empresa ou referência externa. Uma lista compacta de desambiguação — id, status, tipo, decisão, pontuação, datas, dias desde a última atualização — além do total de correspondências, para que uma busca ambígua continue visivelmente ambígua.	Por padrão, os e-mails dos solicitantes não são retornados. Os nomes chegam dentro do envelope não confiável.
`list_stalled_verifications`	Casos não finalizados sem atividade há N dias (padrão 7), cada um com `daysWaiting` e os `pendingDocTypes` ainda pendentes. É a lista de "a quem eu cobro?" — estes aguardam o solicitante.	O backlog do lado do revisor. Encaminhamentos e violações de SLA ficam em `get_todays_queue`. Combinar o filtro com um status finalizado não retorna nada.
`whats_changed_since`	Passagem de turno: tudo o que foi alterado desde um carimbo de data e hora, do mais antigo para o mais recente, agrupado pelo status atual, com o tempo decorrido desde cada movimentação.	Horários em linguagem natural. `since` precisa ser uma data e hora ISO-8601 completa, como `2026-07-18T00:00:00.000Z` — uma data simples é recusada.
`get_verification_status`	Uma forma enxuta de status para um ID de requisição — status, datas, decisão, pontuação geral. Leve o bastante para consultar com frequência.	Nenhum dado pessoal, em qualquer configuração.

Comece por get_todays_queue e depois aprofunde. Não reconstrua a fila fazendo um laço com find_verification — o limite por locatário é de 120 requisições por minuto, e um laço o esgota antes de terminar.

Fazer o trabalho avançar

Ferramenta	Retorna	Observações
`start_verification`	Cria uma verificação e retorna, em uma única chamada, o link que o solicitante usa.	Não envia e-mail — o link volta para você entregar. Não é idempotente.
`start_verifications_batch`	Até 50 registros em uma chamada. Cada registro é validado e criado de forma independente; um e-mail inválido falha apenas o próprio registro, e os registros bem-sucedidos não são desfeitos. As falhas informam o `index` na sua lista e o motivo.	Use no lugar de um laço com `start_verification`. Informe as falhas individualmente — nunca como "algumas falharam".
`send_form_to_customer`	Envia um e-mail real. Cria o solicitante, cria a requisição, gera o link pessoal, envia o convite e retorna um identificador de acompanhamento para `get_delivery_status`.	Não é idempotente — duas vezes significa dois solicitantes, duas requisições e dois e-mails. Obtenha antes o ID do formulário com `list_verification_forms`; um palpite resulta em 404.
`send_verification_reminder`	Envia um e-mail real. Lembra o solicitante com um link novo que retoma a mesma requisição — o status e os documentos já enviados são preservados.	Apenas enquanto o caso estiver em `PENDING_UPLOAD` ou `DOCUMENTS_READY`. Há controle de velocidade no servidor — veja Segurança e limites.
`renew_verification`	Envia um e-mail real. Cria uma nova requisição para o mesmo solicitante, vinculada à original, exigindo os mesmos documentos, e envia um aviso de nova verificação.	A original não é alterada. Não é idempotente — cada chamada é mais uma renovação e mais um e-mail. Encontre antes os casos vencidos com `list_expiring_documents` no modo `renewals`.
`resubmit_verification`	Redefine uma requisição REJECTED para `PENDING_UPLOAD`, para que o solicitante possa tentar de novo — a correção usual para uma foto borrada ou um documento de identidade vencido.	Destrutiva. Apaga as verificações existentes e a pontuação de risco, então `explain_verification_decision` não consegue mais explicar a rejeição depois. Leia a explicação antes. Não envia e-mail.
`list_verification_forms`	O catálogo de onde você envia: id, nome, tipo (`kyc` = pessoa física, `kyb` = empresa), status e slug público. Por padrão, somente formulários publicados.	Nenhum dado de solicitante de qualquer tipo. Um formulário não publicado leva o destinatário ao fluxo genérico de envio, em vez do formulário que você pretendia.
`list_form_deliveries`	Todos para quem um determinado formulário foi enviado e em que etapa cada um está — `sent`, `started`, `completed`, `bounced`, `failed`. `status: sent` é a lista de cobrança.	Os e-mails dos destinatários vêm mascarados por padrão.
`get_delivery_status`	O ciclo de vida completo de um envio: enviado, entregue, aberto, iniciado, concluído, quantos lembretes foram enviados e quando foi o último.	Confie em `startedAt` / `completedAt` — são observados no servidor. `openedAt` depende do rastreamento de abertura do cliente de e-mail, que a maioria dos clientes bloqueia; um `openedAt` nulo não é prova de que a pessoa ignorou o e-mail.

Entender uma decisão

Ferramenta	Retorna	Não retorna
`explain_verification_decision`	O raciocínio real do mecanismo de pontuação para uma requisição: quais desqualificadores de nível 1 ou gatilhos de revisão de nível 2 dispararam, quais fatores de pontuação falharam e com base em qual evidência, quais não puderam ser avaliados e por quê, a pontuação em relação ao limite aplicado, quaisquer regras de política disparadas, indicadores de risco de rede com a forma como cada um foi detectado, e um resumo escrito das notas do caso. Também sinaliza quando um revisor humano substituiu o veredito automatizado.	Veja a lacuna abaixo — o raciocínio estruturado não está presente em todas as requisições.
`get_verification_result`	O resultado: status, decisão, pontuação de confiança, cada verificação executada e se passou, a contagem de aprovado / reprovado / não aplicável sobre os fatores de pontuação, quais desqualificadores ou gatilhos de revisão dispararam, `redFlags` e um resumo `network` (VPN / proxy / Tor / data center / relay detectado, como, país do IP e operadora de rede, e se o fuso horário do dispositivo corresponde), quais documentos foram enviados e o que o solicitante ainda deve.	Nenhum dado pessoal por padrão — sem nome, data de nascimento, números de documento, endereços ou texto de OCR. `include_pii: true` amplia a resposta para os campos de identidade, e isso é registrado.

reasoningAvailable: false é comum. O raciocínio estruturado do mecanismo de pontuação (verdictMeta) só é registrado em verificações pontuadas desde que foi introduzido; por isso, muitas requisições — na prática, a maioria das antigas — retornam com reasoningAvailable: false e sem detalhamento dos fatores. Em uma verificação pontual de um locatário ativo, nenhuma das 12 requisições mais antigas tinha esse dado, e apenas 5 das 12 mais recentes tinham. Quando isso acontecer, descreva o que o status e as verificações mostram e informe que o raciocínio não foi registrado. Não deduza por que o mecanismo decidiu desse modo.

Risco de rede

Toda conexão de verificação é checada pela própria detecção da Certivant — sem fornecedor terceiro — quanto a redes Tor, VPN, proxy, hospedagem / data center e relays de privacidade. As duas ferramentas acima informam isso como redFlags, mais um objeto network:

detected — os tipos encontrados; detections — cada um com a sua origem (uma lista de IPs atualizada diariamente, o nome da operadora, um vazamento de WebRTC ou de DNS, um IP compartilhado por muitos solicitantes, ou uma ida e volta no navegador muito mais longa do que a borda mediu).
ipCountry, networkOperator, deviceTimezoneMatchesIp, ipToGpsDistanceKm, likelyRealNetworkCountry.
Nunca o endereço IP, o nome do host ou a cidade — são dados pessoais.
assessed: false significa não verificado (nenhum IP do solicitante, por exemplo, em requisições criadas pela API) — nunca "limpo".

Um indicador de risco descreve a conexão, não a pessoa: usuários preocupados com privacidade e usuários corporativos usam VPNs. Cada organização escolhe, por tipo, se uma detecção rejeita, encaminha para revisão, apenas sinaliza ou é ignorada.

Verificação de identidade ao vivo

Ferramenta	Retorna	Observações
`list_live_verifications`	Sem `conference_id`: sessões filtradas por status (`scheduled`, `in_progress`, `completed`, `cancelled`, ou `expired` = nunca aconteceu), requisição, referência ou intervalo de datas. Com `conference_id`: o detalhe daquela sessão — anfitrião, se o solicitante entrou e consentiu, configurações da sessão (envio de arquivo pelo solicitante, verificação automática dos documentos recebidos), decisão e resultado, gravação e certificado.	Nenhum nome ou e-mail do solicitante, a menos que `include_pii: true` seja usado com um `conference_id` (registrado em auditoria).
`schedule_live_verification`	Agenda uma sessão para uma requisição existente (`scheduled_for` com fuso horário, ou `start_now`), com `applicant_file_upload` e `auto_verify_documents` opcionais.	Envia e-mail ou SMS ao solicitante. Não é idempotente; uma requisição com uma sessão já acessível retorna 409. O link de entrada único é retornado apenas no texto — compartilhe-o somente com o solicitante.
`manage_live_verification`	`action`: `reschedule` (os participantes são notificados), `resend_invitation` (novo link; o antigo deixa de funcionar) ou `cancel`.	Marcada como destrutiva: o cancelamento é irreversível. Confirme antes de cancelar ou reconvidar.

KYB

Ferramenta	Retorna	Observações
`get_business_record`	O que a empresa declarou em uma requisição BUSINESS: nome da empresa, número de registro, país e tipo de constituição, status de KYB, o representante autorizado e como ele foi conciliado, além de diretores e beneficiários finais declarados, com percentuais de participação e qualquer requisição de KYC vinculada que verifique um UBO.	Uma leitura pura do que a Certivant armazena. Não faz nenhuma consulta ao registro e não tem custo. Não informa se algo disso é verdadeiro.
`check_company_registry`	O diff entre o registro societário público e o que a empresa declarou: quais diretores declarados o registro não lista e quais diretores do registro nunca foram declarados. O diff é a resposta; o registro bruto é evidência de apoio.	Não é uma leitura — faz uma consulta externa cobrável ao registro e, em caso de correspondência, marca o registro de KYB como `verified`. Chame uma vez por empresa, nunca em laço.
`submit_business_details`	Registra os dados de KYB de uma empresa em uma requisição BUSINESS existente — razão social, número de registro, país e tipo de constituição, diretores e beneficiários finais.	Efeitos colaterais além do registro: dispara uma consulta em segundo plano ao registro e cria uma requisição de verificação INDIVIDUAL separada para cada beneficiário final com 25% ou mais de participação (o limiar do GAFI / FATF). Nunca chame por precaução ou para "corrigir um erro de digitação".

Limitação conhecida: check_company_registry está falhando em produção. A consulta ao registro upstream retorna 401, porque a chave da API do OpenCorporates não está sendo repassada; por isso, o diff de correspondência de diretores ainda não foi comprovado contra uma correspondência real no registro. Enquanto isso não for corrigido, espere um erro em vez de um diff, e não crie um fluxo de trabalho que dependa do caminho de sucesso desta ferramenta. get_business_record e submit_business_details não são afetados.

Relatórios e documentos

Ferramenta	Retorna	Não retorna
`get_compliance_metrics`	O resumo de todo o locatário: taxa de aprovação e o funil completo (enviadas / pendentes / em processamento / aprovadas / rejeitadas / encaminhadas), volume por tipo de documento, resultados por nacionalidade, uma tendência diária de 30 dias e taxas de falha por verificação, mostrando qual verificação mais falha — OCR, comparação facial, prova de vida, sanções.	Não é uma lista de motivos de rejeição. "Principais motivos de rejeição" não é algo que esta ferramenta produz; o que ela fornece são as taxas de falha por verificação. Também não há dados de registros individuais nem dado pessoal algum.
`list_expiring_documents`	Dois modos. `documents` (padrão) — verificações cujos documentos enviados vencem ou ficam desatualizados em N dias (um documento de identidade vencido, ou um documento de apoio com data mais antiga que a janela de recência do locatário). `renewals` — verificações cuja própria re-verificação periódica está vencida (o `expiresAt` da requisição), atrasada ou prestes a vencer em N dias.	São perguntas diferentes. Um passaporte válido em uma requisição com renovação anual vencida aparece apenas em `renewals`. Execute o modo que você realmente pediu.
`list_verification_documents`	Somente metadados de cada documento de uma requisição: tipo (`passport`, `id_card`, `drivers_license`, `selfie`, `business_reg`, `utility_bill`, `bank_statement`), lado, status de processamento, tipo e tamanho do arquivo, data de envio e as datas extraídas do próprio documento, incluindo se ele aparece como vencido.	Nenhuma imagem, nenhum texto de OCR, nenhum número de documento, nenhum nome, nenhum endereço, nenhuma MRZ — o bloco de OCR é excluído estruturalmente e não pode ser obtido em nenhuma configuração.
`get_document_download_url`	Uma URL assinada de curta duração (15 minutos), para que uma pessoa possa visualizar um documento enviado, além da validade dela.	Não retorna o arquivo, e o agente não deve buscá-lo — um documento de identidade trazido para uma conversa é uma cópia do passaporte nos registros de um provedor de modelo. O link não exige credenciais, então trate-o como um segredo: entregue-o à pessoa que pediu e pare por aí.

Ferramentas de conformidade com acesso controlado

Três ferramentas existem, mas estão desativadas por padrão. O controle é aplicado no momento do registro; por isso, com a flag não definida, a ferramenta não aparece em tools/list. Cada uma precisa de sua própria flag definida exatamente como "true" no servidor MCP, e de uma chave de API com o escopo kyc:manage:

Ferramenta	Flag	O que faz
`decide_verification`	`CERTIVANT_MCP_ALLOW_DECISIONS`	Registra uma aprovação ou rejeição manual. Uma decisão regulada tomada em um contexto que contém texto controlado pelo solicitante — habilite-a de forma deliberada.
`export_applicant_data`	`CERTIVANT_MCP_ALLOW_EXPORT`	Inicia um job de exportação de dados (GDPR).
`erase_applicant`	`CERTIVANT_MCP_ALLOW_ERASURE`	Exclusão de dados (GDPR) — irreversível; exige repetir uma confirmação.

O que não está no catálogo

get_fraud_signals, explain_to_applicant, submit_verification — não disponíveis.
Configurações (limites, ações de risco de rede, política de privacidade, funções) — gerenciadas apenas no painel; a chave de API do conector não consegue lê-las.

Referência de ferramentas

On this page