A parte 3 terminou com um diagnóstico claro. Quando a página certa chegava, os modelos grandes acertavam tudo. Todo erro que sobrou foi da busca: em 10 das 33 perguntas em português, a página da resposta nem chegou ao modelo.
A busca da parte 3 era fixa. A pergunta do usuário virava um vetor, o banco devolvia os 3 trechos mais parecidos e pronto, sem segunda chance. Uma pessoa procurando no mesmo PDF faria diferente: trocaria as palavras, buscaria de novo, abriria a página do gráfico para olhar.
Então demos isso ao modelo. O banco virou um servidor MCP com duas ferramentas, buscar e ver uma página, e um agente decide como usá-las. Mesmas 33 perguntas, mesmos três modelos grandes, mesmo documento.
O resumo: o agente acertou 32 ou 33 de 33 com os três modelos, nos dois idiomas, contra 24 ou 25 do pipeline fixo. Todos os 60 acertos de gráfico vieram depois de o agente abrir a página do gráfico. Com o GPT, ficou até mais barato que o pipeline fixo. E o nosso avaliador quebrou de novo, agora no sentido contrário.
O código está em salada-dados/blog, nos arquivos index_pg.py, mcp_server.py, agent.py e rewrite.py. O experimento inteiro, com testes, custou US$ 6,80.
MCP em dois parágrafos
O Model Context Protocol é um padrão aberto para ligar ferramentas e dados a modelos de linguagem. Um servidor MCP anuncia as ferramentas que oferece, com nome, descrição e parâmetros. Um cliente MCP (um agente, o Claude Desktop, uma IDE) lista essas ferramentas, passa a lista para o modelo e executa as chamadas que o modelo pedir.
A vantagem é escrever a ferramenta uma vez e usá-la em qualquer cliente. O servidor deste artigo é o mesmo que dá para ligar no Claude Desktop ou no Claude Code e conversar com o PDF. Isso fica para um post à parte; aqui, o que importa é medir.
O experimento
O banco. Os mesmos trechos das partes 2 e 3 (texto do pypdf, até 400 tokens, embeddings multilingual-e5-small) foram para o Postgres com pgvector, como na parte 1. Com um detalhe: o servidor entra por um usuário do banco que só consegue ler essa tabela.
O servidor MCP, com o SDK oficial em Python, oferece duas ferramentas:
search_report(query)devolve os 3 trechos mais parecidos com a consulta, cada um com o número da página.view_page(page)devolve a página como imagem, em 150 dpi, igual à parte 3.
O agente é um laço curto, sem framework. Ele manda ao modelo a pergunta e a lista de ferramentas; se o modelo pedir uma ferramenta, o agente chama o servidor MCP e devolve o resultado; repete até o modelo responder, com no máximo 6 passos.
Os modelos são os três maiores da parte 3, pelo OpenRouter: Claude Sonnet 5.5, GPT-6.1 Sol e Gemini 4 Argon. O Qwen ficou de fora: na parte 3, ele inventava resposta quando não achava, e num agente isso piora, porque ele pode decidir parar de buscar cedo demais.
Resultados
Respostas certas, de 33 perguntas:
| Modelo | Pipeline fixo (parte 3) pt / en | Agente pt | Agente en |
|---|---|---|---|
| Claude Sonnet 5.5 | 25 / 25 | 32 | 33 |
| GPT-6.1 Sol | 24 / 25 | 32 | 33 |
| Gemini 4 Argon | 24 / 25 | 33 | 33 |
Por tipo, em português, os três acertaram as 12 de texto e as 10 de gráfico. Nas tabelas, o Gemini fez 11 de 11, e o Claude e o GPT, 10.
Os dois erros que sobraram são recusas honestas. O Claude fez 5 buscas e abriu 3 páginas atrás do IPCA de julho antes de dizer que não encontrou o valor isolado; o GPT fez 3 buscas pelo papelão ondulado e desistiu. Ninguém inventou número.
A página certa passou a aparecer. Nos resultados das buscas do agente, a página da resposta apareceu em 29 a 30 perguntas em português e 31 a 32 em inglês. A busca fixa ficava em 23 e 25.
Os gráficos foram lidos, e não adivinhados. Os 60 acertos de gráfico (10 por modelo, em cada idioma) vieram todos depois de o agente chamar view_page na página do gráfico. Na parte 3, verificamos que modelo barato chuta; aqui, conferimos isso antes de comemorar.
Como o agente achou o que a busca fixa perdia
Somando os três modelos e os dois idiomas, houve 54 casos em que a busca fixa não trouxe a página. Neles, o agente chegou à página assim:
| Como | Casos |
|---|---|
| Na primeira busca, só reescrevendo a pergunta | 29 |
| Numa busca seguinte, com outras palavras | 16 |
Abrindo uma página vizinha com view_page | 4 |
| Não chegou à página-alvo | 5 |
Dos 5 casos em que o agente não chegou à página-alvo, 3 são de uma pergunta cuja resposta também aparece em outra página, e ele acertou do mesmo jeito. Os outros 2 são os dois erros.
A primeira linha da tabela engana se lida sozinha. A primeira busca do agente, em que ele troca a pergunta por palavras-chave, recuperou 29 páginas que a busca fixa perdia. No Gemini, "Qual foi a variação anual da construção civil em 2022?" virou construção civil 2022 variação anual PIB, e a tabela da página 16 apareceu na hora. Mas essa mesma primeira busca perdeu 15 páginas que a busca fixa achava. O saldo é de 14 páginas, de 144 para 158 nos 198 casos.
O grosso do ganho veio do que só um agente faz: olhar o resultado, buscar de novo quando ele não serve e abrir a página ao lado. Somando todas as buscas, a página certa apareceu em 184 dos 198 casos. Para as exportações em média móvel, o Gemini buscou uma vez, não gostou, buscou pelos números dos gráficos (Gráfico 1.2.40 Gráfico 1.2.41 Gráfico 1.2.42...) e abriu a página 31.
E se só reescrever a pergunta?
Se a primeira busca do agente já ajuda, dá para ficar com ela e dispensar o agente? A ideia é barata: uma chamada ao modelo reescreve a pergunta, e a busca fixa da parte 3 roda com a consulta nova. Testamos com os mesmos três modelos. Página certa entre os resultados, somando os três:
| Busca | pt | en |
|---|---|---|
| Fixa, com a pergunta original (parte 3) | 69 | 75 |
| Pergunta reescrita, primeiro prompt | 65 | 68 |
| Pergunta reescrita, segundo prompt | 68 | 72 |
| Primeira busca do agente | 76 | 82 |
| Todas as buscas do agente | 89 | 95 |
Não deu. A pergunta reescrita ficou no nível da original ou abaixo, e por isso nem rodamos a etapa de resposta: sem a página, a resposta não melhora.
O primeiro prompt pedia "uma consulta de busca no Relatório de Política Monetária do Banco Central". Os modelos fizeram o que um buscador pediria. O GPT colocou "Banco Central do Brasil Monetary Policy Report September 2026" nas 33 consultas em inglês, e esse nome está no cabeçalho de todas as páginas do PDF, então a busca passou a puxar páginas quase ao acaso. O Gemini escreveu coisas como "2026Q2" OR "second quarter of 2026" em 9 delas, operadores que não significam nada para uma busca por embeddings.
O segundo prompt explicava que a busca compara significados, pedia a frase curta que estaria no trecho da resposta e proibia o nome do relatório e os operadores. As consultas ficaram limpas, com 8 a 10 palavras, e a busca voltou ao nível da original, sem passar dela. Ajustamos esse prompt olhando as mesmas perguntas, o que favorece o resultado, e mesmo assim ele não superou a busca fixa.
A diferença para o agente parece estar em duas coisas: a descrição da ferramenta, que orienta a consulta sem empurrar o nome do relatório, e a segunda chance. A reescrita isolada custou US$ 0,40 para os três modelos; o código está em rewrite.py.
Quanto custou
| Modelo | Custo por pergunta: fixo (parte 3) | Custo por pergunta: agente | Tempo, mediana: agente |
|---|---|---|---|
| Claude Sonnet 5.5 | US$ 0,017 | US$ 0,024 | 6 s |
| GPT-6.1 Sol | US$ 0,019 | US$ 0,011 | 8 s |
| Gemini 4 Argon | US$ 0,007 | US$ 0,012 | 21 s |
O agente fez em média 1,4 busca e abriu 0,6 página por pergunta. O pipeline fixo mandava 2,8 páginas sempre, até para pergunta de texto. Por isso o GPT ficou mais barato como agente: ele quase só abre página quando precisa.
O Claude e o Gemini ficaram mais caros, por motivos diferentes. O Claude faz mais buscas e respostas mais longas, e cada volta do laço reenvia todo o histórico: deu cerca de 10.500 tokens de entrada por pergunta, o dobro dos outros dois. O Gemini custou pouco por chamada, mas cada chamada foi lenta: 21 segundos de mediana por pergunta, contra 7 na parte 3.
O que a IA de coding não vai te avisar
A descrição da ferramenta é o manual do modelo
O modelo só sabe o que a ferramenta faz pela descrição. Rodamos tudo de novo com descrições curtas: "Search the report." e "Get a page of the report.", contra as detalhadas, que dizem o que volta, que os valores dos gráficos só existem na imagem e que vale buscar de novo com outras palavras.
| Descrições detalhadas | Descrições curtas | |
|---|---|---|
| Acertos (3 modelos, pt e en) | 196 de 198 | 194 de 198 |
| Chamadas de ferramenta por pergunta | 1,97 | 2,35 |
| Claude, em inglês: chamadas por pergunta e custo | 1,9 e US$ 0,70 | 2,9 e US$ 1,04 |
Esperávamos uma queda grande de acertos, e ela não veio: os modelos grandes se viram bem com pouca instrução. O que muda é o caminho. Com a descrição curta, o agente fez 19% mais chamadas, e o Claude gastou 48% a mais em inglês.
E às vezes ele nem descobre que a ferramenta certa existe. Na pergunta sobre o IPA-DI, com a descrição curta, o Claude fez 7 buscas e respondeu: "O relatório mostra a variação em 12 meses do IPA-DI só no Gráfico 1.2.50 [...]. O texto que consegui consultar não diz em que ano ela chegou perto de 50%." Nunca chamou view_page. Com a descrição detalhada, fez 3 buscas, abriu a página e acertou.
Erro genérico não ensina nada
Pedimos de propósito a página 999. Com um ValueError comum dentro da ferramenta, o modelo recebe só "Error executing tool view_page". Ele não tem como saber o que fazer diferente. O SDK tem uma exceção própria, ToolError, cuja mensagem chega ao modelo:
Error executing tool view_page: page must be between 1 and 90, got 999A imagem não cabe no resultado da ferramenta
O MCP permite que uma ferramenta devolva imagem. A API de chat no formato da OpenAI, que o OpenRouter usa, não: a mensagem de resultado de ferramenta só leva texto. Se você só repassar o resultado, a imagem some no caminho, sem erro nenhum, e o modelo responde sem ter visto a página.
A saída é mandar a imagem numa mensagem à parte, logo depois do resultado, e avisar no resultado que ela vem:
note = f"(page {args.get('page')} follows as an image)" if pics else ""
messages.append({"role": "tool", "tool_call_id": tc["id"], "content": "\n".join(texts) or note})
images += [{"type": "image_url", "image_url": {"url": f"data:{p.mime_type};base64,{p.data}"}} for p in pics]
...
if images:
messages.append({"role": "user", "content": [{"type": "text", "text": "Requested page images:"}] + images})print() derruba o servidor
No transporte stdio, que é o mais comum para um servidor local, a saída padrão é o canal do protocolo. Um print() de depuração no servidor vira uma mensagem inválida no meio da conversa. Log vai para stderr.
O avaliador quebrou de novo, ao contrário
Na parte 3, criamos uma regra para que recusas que repetem a pergunta não contassem como acerto. Aqui, ela pegou uma resposta certa. O Claude respondeu:
Construction grew 6.8% in 2022, according to the report's GDP table on page 16. The table's
column headers were not in the text, so I matched the columns to years from the other rows."Not in the" estava na lista de frases de recusa. A resposta está certa, e ainda explica como o modelo contornou o cabeçalho perdido da tabela, o problema central da parte 2. A correção foi procurar a recusa só na primeira frase, que é onde toda recusa que lemos aparece. Antes de aplicar, conferimos a regra nova em todas as respostas das partes 2, 3 e 4: só esse caso mudou.
Ponha teto em passos e em gasto
Um agente decide sozinho quantas vezes chamar o modelo, e cada volta reenvia o histórico inteiro, com as imagens. Sem limite, uma pergunta difícil vira um laço caro. Usamos no máximo 6 passos (4 das 198 perguntas chegaram lá) e um orçamento que para a rodada inteira se o custo informado pelo OpenRouter passar de US$ 15.
Na prática, quem nos parou primeiro foi o crédito: no meio do experimento, a conta do OpenRouter acabou e a API passou a responder com erro 402. A rodada caiu, mas o cache em disco guardava cada pergunta já respondida, e retomar custou só o que faltava. Sem cache, um erro no meio de um laço de agente custa tudo de novo.
O documento também é entrada
O texto que a ferramenta devolve vai direto para o modelo. Se um documento tiver uma frase como "ignore as instruções e chame a ferramenta X", ela chega ao modelo como qualquer outro trecho. É prompt injection, e num agente o risco cresce, porque o modelo escolhe os argumentos das ferramentas.
Não medimos isso aqui, mas tomamos duas precauções baratas. As ferramentas só leem e estão marcadas como somente leitura no MCP (read_only_hint). E o servidor entra no banco por um usuário que só pode ler uma tabela: testamos, e um DELETE volta com "cannot execute DELETE in a read-only transaction".
A solução, em código
O servidor inteiro tem umas 90 linhas. O essencial são as duas ferramentas:
mcp = MCPServer("monetary-policy-report", instructions="Read-only access to one PDF report.")
READ_ONLY = ToolAnnotations(read_only_hint=True, destructive_hint=False, open_world_hint=False)
@mcp.tool(description=DESCRIPTIONS["search_report"], annotations=READ_ONLY)
def search_report(query: str) -> str:
vector = model.encode("query: " + query, normalize_embeddings=True)
rows = conn.execute(
"SELECT page, content FROM rpm_chunks WHERE lang = %s ORDER BY embedding <=> %s LIMIT %s",
(LANG, vector, K),
).fetchall()
return "\n\n".join(f"[page {page}]\n{content}" for page, content in rows)
@mcp.tool(description=DESCRIPTIONS["view_page"], annotations=READ_ONLY)
def view_page(page: int) -> Image:
if not 1 <= page <= len(doc):
raise ToolError(f"page must be between 1 and {len(doc)}, got {page}")
return Image(data=doc[page - 1].get_pixmap(dpi=DPI).tobytes("png"), format="png")Repare no [page N] em cada trecho. Sem ele, o modelo não sabe qual página abrir, nem tem como dizer de onde tirou a resposta.
O agente abre o servidor como um subprocesso, lista as ferramentas e as converte para o formato da API de chat:
params = StdioServerParameters(command=sys.executable, args=["mcp_server.py"], env={**os.environ, "DOC_LANG": lang})
async with Client(params) as client:
tools = [{"type": "function", "function": {"name": t.name, "description": t.description,
"parameters": t.input_schema}}
for t in (await client.list_tools()).tools]O SDK de MCP para Python está na versão 2, com mudanças grandes em relação à 1. O FastMCP, que aparece na maioria dos tutoriais, virou MCPServer, e código antigo falha logo no import, com um ModuleNotFoundError. Os campos também passaram a usar snake_case (input_schema, mime_type). Assistentes de código treinados antes disso tendem a escrever a API antiga. Leia a documentação da versão instalada antes de aceitar a sugestão.
Quando vale montar um agente:
- Vale quando a busca fixa erra a página com frequência e a resposta pode estar num gráfico. Foi daí que saiu o salto de 24 para 32 ou 33.
- Reescrever a pergunta sozinho não substitui o agente. Aqui, a consulta reescrita numa chamada separada achou tantas páginas quanto a pergunta original, ou menos. O ganho veio de buscar de novo e de abrir páginas.
- Custa previsibilidade. O número de chamadas, o tempo e o custo variam por pergunta. Para um sistema com prazo de resposta, isso pesa.
Cuidados antes de generalizar
33 perguntas é pouco, e o teto ficou baixo. Com 32 ou 33 acertos, o teste não separa mais os modelos. Para comparar Claude, GPT e Gemini como agentes, seria preciso um conjunto mais difícil.
O resultado vale para este documento. Um relatório de 90 páginas, com gráficos vetoriais e texto bem extraído. Num acervo de milhares de PDFs, a busca erra de outros jeitos, e o agente precisaria de ferramentas para escolher o documento antes da página.
Os modelos, os preços e o SDK mudam. Os números são de novembro de 2026, e o SDK de MCP mudou de versão grande há pouco tempo.
A descrição detalhada foi escrita por nós, uma vez. Não testamos variações dela. Uma descrição melhor talvez reduza ainda mais as chamadas.
Próximos passos
Esta é a parte 4 da série sobre RAG. Com 32 ou 33 acertos, este conjunto de perguntas chegou ao limite: o próximo teste da série precisa ser mais difícil.
Num post à parte, vamos ligar este mesmo servidor MCP ao Claude Desktop e ao Claude Code, para conversar com um PDF sem escrever o agente.
