Escreva a sua

Este capítulo não tem código.

Até aqui o curso entregou Tools prontas: listar_assuntos, buscar_processos, contar_processos, ultimos_movimentos. Todas sobre temas que eu escolhi, contra portas que eu escolhi. Serviram para mostrar o formato. Nenhuma responde à pergunta que você faz.

A partir daqui é seu. O que vem abaixo é o método, na ordem em que ele funciona — e a ordem importa mais que qualquer linha de Python.

Passo 0 — A pergunta, não o sistema

O erro de partida mais comum é escolher o sistema primeiro: "quero conectar no eproc". Isso não é um projeto, é uma vontade — e ela produz uma ferramenta que consulta tudo e não responde nada.

Comece pela pergunta que você faz toda semana e que hoje custa cliques. Uma só. Escreva-a numa linha, em português, do jeito que você a faria para um assessor.

"Quantos processos de execução fiscal da minha vara estão parados há mais de 90 dias?"

Se você não consegue escrever a pergunta numa linha, ela ainda não está pronta para virar Tool — está pronta para virar três Tools, e você vai descobrir isso no passo 1.

Passo 1 — Qual das cinco formas?

Releia As cinco formas de pergunta e classifique a sua.

A pergunta do exemplo é da forma 1. Isso já decidiu que a resposta é um número, não uma tabela — e uma Tool que devolve um número não tem problema de tamanho, não tem problema de sigilo por excesso de coluna, e não precisa de nenhuma das técnicas de redução da Unidade 3.

Perguntas da forma 1 são as mais fáceis de fazer com segurança. Comece por uma.

Passo 2 — Qual porta responde essa forma?

Nem toda porta responde toda forma. Esta tabela é o resumo da unidade:

Leia a coluna do MNI. Se a sua pergunta for de contar, o MNI está fora — e descobrir isso agora custa um minuto, enquanto descobrir depois de pedir credencial custa um mês.

E leia a primeira coluna antes de tudo: se o DataJud responde, use o DataJud. É público, não precisa de chamado, não alcança sigiloso e não expõe credencial sua. A Unidade 2 inteira é sobre isso. Só vá para o banco interno quando a pergunta precisar de algo que o CNJ não publica — o seu campo interno, a sua fase, o seu prazo.

Passo 3 — O pedido, antes do código

Se a porta for interna, o próximo passo não é abrir o editor. É abrir o chamado, com o texto do capítulo do banco adaptado.

E, enquanto ele não volta, faça a parte que não depende dele: escreva a Tool contra a base sintética da Unidade 1, com os mesmos nomes de campo que você espera encontrar. Quando a credencial chegar, o que muda é a string de conexão.

Passo 4 — Meça o formato antes de ler o dado

Você já tem as duas ferramentas para isso, uma por porta:

• Banco: SELECT * FROM sua_view WHERE 1=0
• Webservice: cliente.wsdl.dump()

As duas te dão o formato sem te dar o dado. Rode a sua antes da primeira consulta de verdade — inclusive porque o nome de campo que você imaginou raramente é o nome que existe.

Passo 5 — Escreva a consulta, não a Tool

Ainda não é hora do agente. Escreva um script de vinte linhas que faz a consulta e imprime o resultado. Rode. Confira o número contra a tela do sistema.

Se o número não bater, pare aqui. Uma Tool que devolve o número errado com confiança é pior que nenhuma Tool: o agente vai apresentá-lo em prosa fluente, e ninguém vai conferir.

Este é também o momento do teste que ninguém faz: consulte algo que você não deveria ver. Se vier, sua credencial alcança mais que você.

Passo 6 — Envolva na Tool

Agora sim, e são três decisões, todas já vistas:

Assinatura. Argumentos simples — texto, número, data. Nada de dicionário aninhado: o modelo preenche pior quanto mais estrutura você pedir.

E nada de identidade: quem você é, qual a sua vara, qual o seu perfil — isso é constante lida do ambiente, nunca argumento. Ver Só os meus processos.

Docstring. É o que o modelo lê para decidir se chama. Diga o que a Tool responde e o que ela não responde. "Conta processos por assunto. Não lista os processos." economiza a chamada errada.

Retorno. Monte o dicionário campo a campo. Nunca devolva o objeto que veio do banco ou do webservice.

O teste da publicação

Antes de conectar qualquer Tool a qualquer agente, uma pergunta, e ela substitui uma lista inteira:

Se o que esta Tool devolve fosse colado num e-mail para alguém de fora do Tribunal, isso seria um problema?

Se a resposta for sim, a Tool não está pronta — porque é, na prática, o que você está fazendo. Mandar para o modelo é copiar para um destino a mais. Hoje ele é o Ollama na sua máquina, e isso é o melhor caso possível. Mas nada na Tool garante que amanhã ainda seja: trocar o api_base é uma linha, e ela não fica no arquivo da Tool.

O que protege não é onde o modelo roda. É o que a Tool devolve.

A lista final

Para rodar antes de ligar no agente. Nesta ordem, porque as duas primeiras invalidam as outras:

1. O número bate com a tela do sistema?
2. Uma consulta ao que você não pode ver é recusada?
3. O filtro de sigilo está na view ou no WHERE — não no pandas depois?
4. As colunas estão listadas à mão, sem SELECT * e sem devolver o objeto cru?
5. Nenhum SQL é montado com f-string a partir de argumento?
6. Nenhuma senha, chave ou identificação está em arquivo — só em variável de ambiente?
7. A Tool só consulta? Nenhuma operação de escrita, em nenhum caminho?
8. O retorno passa no teste da publicação?
9. A docstring diz o que a Tool não faz?
10. O código roda dentro da VPN e falha fora dela?
11. Nenhuma Tool tem identidade na assinatura — nome, matrícula, perfil, vara?

Onde isso vai morar

A Tool que você escreveu não precisa viver dentro de um script de agente. A Unidade 3 mostrou como transformá-la em servidor MCP rodando na sua máquina — e é aí que ela deve morar.

O motivo é o mesmo desde o começo do curso: local. O servidor roda no seu computador, com a sua credencial, atrás da sua VPN. Nada sobe. E, porque roda local, qualquer pessoa pode escrever o seu — que é a razão de o curso ter sido montado assim.

O que fazer com o que você descobrir

Este material foi escrito por alguém que não tem as credenciais que você tem. O capítulo do banco veio de código que roda; o do MNI e o do SEI vieram de documentação.

Quando você rodar:

• o nome de campo que era diferente,
• o erro que a documentação não previa,
• a operação que a sua TI não habilitou,
• a pergunta que não coube em nenhuma das cinco formas,

anote e mande de volta. É assim que a próxima versão deixa de ter um capítulo escrito sem medição.

E se a sua Tool responder em dois segundos uma pergunta que hoje custa vinte minutos de cliques, ela já pagou o curso — mesmo que ela seja a única que você escreva.