Conclusão da Unidade 3

Esta unidade começou com um campo que não cabia e terminou com uma Tool que não mora mais dentro do agente.

São duas coisas diferentes, e a ligação entre elas é o assunto desta página.

O que foi feito

Um campo foi medido antes de ser usado. movimentos[] tem mediana 74 e máximo 613 numa amostra de 200 processos. O campeão — 0018683-81.2020.8.19.0066, 613 movimentos, 105.123 bytes — é de 2020, não de 1880. Os dez processos mais antigos da amostra, incluindo um de 1880 e um de 1901, têm em média 4,4 movimentos.

Uma redução foi quantificada. Cinco processos inteiros: 434.717 bytes, ≈108.700 tokens. Os mesmos cinco, com cinco movimentos cada e dois campos por movimento: 1.446 bytes, ≈360 tokens. Cerca de 300 vezes — e a informação que responde à pergunta continua lá.

Uma pergunta foi separada em cinco formas. Contar, Listar, Agrupar, Evoluir, Detalhar. Todas as cinco medidas: 218 B, 805 B, 601 B, 2.490 B, 599 B. Nenhuma passou de 2,5 KB. O total de "Dívida Ativa" — 5.985.465 processos — coube em 1.519 bytes.

Três Tools saíram do script. Viraram um servidor MCP que roda na sua máquina, por stdio, sem porta aberta. E um agente sem um único @tool dentro dele passou a usá-las.

A lição da primeira metade

Escrever Tool é escolher o que não devolver.

Não é uma frase sobre desempenho. É sobre o que o modelo consegue usar.

A Unidade 2 já tinha ensinado que a Tool devolve objeto Python e que o tipo errado não avisa. Esta acrescentou a dimensão que faltava: o tamanho certo também não avisa. Uma Tool que devolve 105 KB não dá erro — ela enche o contexto, e o modelo, sem espaço para o histórico, começa a repetir passos e a perder o que já sabia.

E há uma consequência dessa escolha que só aparece na hora de escrever a segunda Tool: quem escolhe o que devolver está decidindo quais perguntas o agente consegue responder. Devolver cinco movimentos é decidir que "o que houve neste processo" tem resposta e "quantas vezes ele foi concluso" não tem. Isso é desenho, não limitação — mas é desenho seu, e é bom fazê-lo de propósito.

A lição da segunda metade

A fronteira não acrescenta poder nenhum ao agente. Ela acrescenta lugares onde o dado se transforma em silêncio.

Três defeitos, todos silenciosos de um jeito diferente:

1. O posicional deu erro no lugar errado. O código do modelo estava correto para a assinatura que ele leu; quem mentia era o anúncio.
2. A string em vez do dicionário deu um erro que já significou outra coisa duas vezes neste curso, por causas sem relação nenhuma entre si.
3. O .get(0) não deu erro nenhum. Devolveu None, e seguiu.

E o pior de todos não foi defeito de código: o agente entregou uma resposta bem escrita depois de falhar em tudo. Seis passos, seis erros, e no fim três processos com estrutura, vocabulário jurídico e aparência de trabalho feito.

Isso reduz a uma regra operacional, e ela é a única coisa desta unidade que vale para qualquer agente, de qualquer modelo, em qualquer tarefa:

Número de processo é verificável. Prosa não é.

O que você tem agora

Um servidor MCP local, com três Tools, que qualquer cliente MCP consegue usar — o agente deste curso, e também o Claude Desktop, se você quiser.

Um cliente que corrige o adaptador em seis linhas, sem pedir nada ao modelo.

As cinco formas, que são a ferramenta de análise mais útil do curso: antes de escrever qualquer consulta, decidir qual das cinco a pergunta é. Isso já decide o formato da resposta, o tamanho dela e, como a Unidade 4 vai mostrar, qual porta consegue respondê-la.

Um hábito de medir. Nenhum número desta unidade veio de estimativa. Contamos os bytes, cronometramos as chamadas, provocamos os erros. É o que separa "acho que cabe" de "cabe em 1.446 bytes".

Por que o servidor é local

Vale dizer isto de novo, porque é a decisão que organiza o curso inteiro.

O servidor MCP podia estar num servidor do Tribunal, ou numa nuvem. Ele está na sua máquina, e a razão é simples: se focarmos no local, qualquer pessoa consegue criar o seu próprio agente.

Não depende de aprovação de infraestrutura, não depende de orçamento, não depende de ninguém. O modelo é o Ollama no seu computador. As Tools são um arquivo Python seu. O servidor sobe quando o cliente sobe e morre quando ele morre. E a única coisa que sai da sua máquina, até aqui, é uma consulta a uma API pública.

A Tool saiu do script sem que o dado saísse da máquina. É esse o título da unidade.

O que muda na Unidade 4

Tudo o que veio até agora tinha uma propriedade em comum, e ela some na próxima página: qualquer pessoa conseguia a chave. A base sintética estava no seu disco. A chave do DataJud é pública, igual para todos, e sai por e-mail em um dia.

PJe, eproc, EJUD, DCP, SEI — nenhum é assim. Cada um tem uma porta diferente, algumas não têm porta nenhuma, e a chave nem sempre é sua.

E aparece um problema que este curso ainda não teve. Nas Unidades 2 e 3, o sigilo não era problema seu: 100% do índice público do TJRJ é nivelSigilo 0, medido por dois caminhos independentes. Na Unidade 4, é. A pergunta "o que sai daqui para o modelo?" deixa de ser sobre tamanho e passa a ser sobre quem aparece no retorno.

A boa notícia é que a técnica não muda. Escolher o que não devolver é a mesma disciplina — só que o excesso, lá, cabe perfeitamente no contexto. E é por isso que ele passa despercebido.

Até a Unidade 4.