Referência de Tools

A Fase 1 do MCP Alcance expõe 7 tools - 6 de leitura e 1 de escrita. Todas seguem padrões inegociáveis do projeto: descrições em PT-BR (consumidas pelo LLM), identificação por cliente_id (int), PII mascarada por padrão e dry-run obrigatório em qualquer operação de escrita.

Convenções

Annotations MCP sinalizam ao cliente IA o caráter da tool. readOnlyHint: true é exibido como ícone de leitura; destructiveHint: true dispara o escudo amarelo de confirmação no Claude Desktop.
openWorldHint: true em todas - a tool fala com um sistema externo (a WebApi).

`buscar_cliente` read

Resolve um termo em uma lista de clientes da Alcance. Detecta CNPJ automaticamente quando o termo contém 11+ dígitos; busca fuzzy por razão social chega na Fase 1.1.

Input

Campo	Tipo	Obrigatório	Descrição
`termo`	`string` (mín. 2)	Sim	CNPJ (com ou sem máscara) ou trecho da razão social / nome fantasia.

Output

Tabela markdown com até 20 linhas:

Coluna	Conteúdo
`cliente_id`	ID inteiro - use como chave nas demais tools.
`Razão social`	Nome jurídico (ou nome fantasia, em fallback).
`CNPJ`	Mascarado (`XX.XXX.***/0001-XX`).
`Cidade/UF`	Localização concatenada.

Annotations

readOnlyHint: true
openWorldHint: true

Exemplo de prompt

Encontre o cliente com CNPJ 12.345.678/0001-90 na base da Alcance.

`obter_cliente` read

Retorna a ficha completa do cliente. PII sempre mascarada (CNPJ, telefone, celular, e-mail). Credenciais Gov (login_gov, senha_gov) nunca são expostas, mesmo que estejam na resposta da WebApi.

Input

Campo	Tipo	Obrigatório	Descrição
`cliente_id`	`int` positivo	Sim	ID retornado por `buscar_cliente`.

Output

Bloco markdown com 17 campos: razão social, nome fantasia, CPF/CNPJ, inscrições, regime tributário, contatos mascarados, endereço, representante, flags (ativo, certificado, zap_contábil).

Annotations

readOnlyHint: true
openWorldHint: true

Exemplo de prompt

Me mostre a ficha completa do cliente 1234, com regime tributário e endereço.

`listar_clientes` read

Lista clientes da Alcance com filtros opcionais e paginação. Mapeia o endpoint GET /api/v1/customers/ da WebApi, que devolve todos os clientes ativos - filtros (uf, regime_tributario, cidade) e paginação são aplicados client-side no gateway. CNPJ/CPF mascarados via mascararDocumento (auto-detect PF/PJ).

Quando usar

Use listar_clientes para explorar/filtrar a base (ex.: "clientes do Simples em SP"). Para buscar um cliente específico por CNPJ, prefira buscar_cliente.

Input

Campo	Tipo	Obrigatório	Default	Descrição
`uf`	`string` (2 letras)	Não	-	Sigla da UF (ex.: `SP`, `PR`). Aceita minúsculas - normalizado para maiúsculas.
`regime_tributario`	`"simples_nacional" \| "lucro_presumido" \| "lucro_real" \| "mei"`	Não	-	Regime tributário exato.
`ativo`	`boolean`	Não	`true`	Somente `true` é suportado nesta versão - a WebApi só retorna ativos.
`cidade`	`string` (mín. 2)	Não	-	Trecho do nome da cidade - busca case-insensitive e parcial (`casca` encontra `Cascavel`).
`pagina`	`int ≥ 1`	Não	`1`	Página de resultados (1-based).
`por_pagina`	`int 1..50`	Não	`20`	Itens por página.

Output

Tabela markdown com cabeçalho dinâmico (total + filtros aplicados) e footer indicando próxima página ou fim da listagem.

Coluna	Conteúdo
`cliente_id`	ID inteiro - use como chave nas demais tools.
`Razão social`	Nome jurídico (ou nome fantasia em fallback), truncado em 40 chars.
`CNPJ`	Mascarado - `XX.XXX.*/0001-XX` (PJ) ou `.**.123-XX` (PF).
`Cidade/UF`	Localização concatenada.
`Regime`	Label legível: `Simples`, `Lucro Presumido`, `Lucro Real`, `MEI`.
`Status`	`Ativo` (a WebApi não retorna inativos).

Annotations

readOnlyHint: true
openWorldHint: true

Limitações conhecidas

ativo=false retorna erro estruturado not_implemented - depende de evolução na WebApi (Fase 1.2).
Filtros aplicados em memória no gateway - a WebApi não suporta query params neste endpoint hoje.

Exemplo de prompt

Liste os 10 primeiros clientes do regime Simples Nacional em SP.

`listar_certidoes` read

Lista Certidões Negativas de Débito (CND, FGTS, SEFAZ) com filtros e paginação. O campo pdf_base64 é removido antes de chegar ao LLM - para baixar o PDF, use o endpoint binário da WebApi (/api/v1/certidao-negativa/{id}/pdf).

Input

Campo	Tipo	Obrigatório	Default	Descrição
`cliente_id`	`int` positivo	Não	-	Filtra por um cliente.
`status`	`"valida" \| "vencida" \| "em_processamento" \| "erro" \| "todos"`	Não	`"vencida"`	Default reduz ruído; use `"todos"` para listar tudo.
`pagina`	`int ≥ 1`	Não	`1`	Página de resultados (1-based).
`por_pagina`	`int 1..50`	Não	`20`	Tamanho da página.

Output

Coluna	Conteúdo
`id`	ID da certidão.
`Cliente`	`#<cliente_id>` para correlacionar com `obter_cliente`.
`Tipo`	CND, FGTS, SEFAZ, etc.
`Status`	`valida`, `vencida`, `em_processamento`, `erro`.
`Validade`	Data BR (dd/mm/aaaa).
`Negativa`	Sim / Não / -.

Annotations

readOnlyHint: true
openWorldHint: true

Exemplo de prompt

Quais certidões do cliente 1234 estão vencidas? Mostre a data de validade.

`listar_lembretes` read

Lista lembretes WhatsApp por cliente ou por usuário responsável. Pelo menos um dos filtros é obrigatório - sem isso a tool retorna erro estruturado (input_validation) explicando ao LLM como corrigir.

Input

Campo	Tipo	Obrigatório	Default	Descrição
`cliente_id`	`int` positivo	Condicional¹	-	Filtra por cliente.
`usuario_id`	`int` positivo	Condicional¹	-	Filtra por usuário atribuído.
`apenas_pendentes`	`boolean`	Não	`true`	Quando `true`, oculta lembretes concluídos/enviados.

¹ É obrigatório informar cliente_id ou usuario_id (ambos aceitos, mas pelo menos um).

Output

Coluna	Conteúdo
`ID`	ID do lembrete.
`Envio`	Data/hora BR formatada.
`Status`	`pendente`, `agendado`, `enviado`, etc.
`Contato`	Telefone mascarado (`(11) ****-1234`).
`Mensagem`	Truncada em 80 caracteres.

Annotations

readOnlyHint: true
openWorldHint: true

Exemplo de prompt

Quais lembretes pendentes eu (usuário 7) tenho agendados para essa semana?

`criar_lembrete` write

Cria um lembrete WhatsApp. Tool de escrita com custo real (envia mensagem WhatsApp Business quando confirmada). Por padrão executa em dry-run - sem confirmar=true, retorna apenas preview.

Dry-run obrigatório por padrão

Esta tool tem destructiveHint: true. O Claude Desktop exibe o escudo amarelo de confirmação. Em modo dry-run nada é enviado à WebApi; a operação real só ocorre com confirmar=true explícito.

Input

Campo	Tipo	Obrigatório	Default	Descrição
`cliente_id`	`int` positivo	Sim	-	Cliente destinatário.
`contato`	`string` (mín. 8)	Sim	-	Telefone com DDD; aceita formato livre - só os dígitos são extraídos.
`mensagem`	`string` 1..4096	Sim	-	Texto do lembrete.
`observacao`	`string` ≤ 500	Não	-	Observação interna (não enviada ao destinatário).
`data_hora_envio`	`string` ISO 8601	Não	imediato	Com timezone. Sem TZ assume `-03:00` (Brasília).
`confirmar`	`boolean`	Não	`false`	`false` ⇒ apenas preview. `true` ⇒ cria e agenda o envio de verdade.

Output

Dois formatos possíveis:

Modo	Conteúdo
Dry-run (`false`)	Bloco "Preview do lembrete" com cliente_id, contato, data, observação e mensagem citada.
Confirmado (`true`)	Bloco "Lembrete criado" com `id`, `cliente_id`, `status` e `envio` formatado.

Annotations

destructiveHint: true
openWorldHint: true

Exemplo de prompt

Crie um lembrete para o cliente 1234 no celular (11) 91234-5678 dizendo
"DARF do Simples vence amanhã". Pode confirmar e agendar pra hoje 16h.

`consultar_status_task` read

Consulta o estado de uma tarefa Celery na WebApi. Útil quando o usuário disparou uma automação (geração de PDF, conversão de extrato bancário) e quer saber se já terminou - tasks longas nunca bloqueiam o LLM; o task_id é devolvido na hora.

Input

Campo	Tipo	Obrigatório	Descrição
`task_id`	`string` não-vazia	Sim	UUID retornado por outra tool que dispara processamento assíncrono.

Output

Bloco markdown com o estado atual. Os campos extras dependem do estado:

Estado	Campos adicionais
`SUCCESS`	`resultado` (truncado em 500 chars, formatado como JSON quando objeto).
`FAILURE`	`erro` (resumo) e `traceback` parcial.
`RETRY`	Mensagem informativa - task está sendo retentada automaticamente.
`PENDING`/`STARTED`	Sugestão de consultar novamente em alguns segundos.
`REVOKED`	Mensagem de cancelamento.

Annotations

readOnlyHint: true
openWorldHint: true

Exemplo de prompt

A task 7c1e9f2a-... já terminou? Se tiver resultado, me mostra.