Progressive disclosure: como não afogar seu agente em 50 ferramentas

Você deu 50 ferramentas pro seu agente e ele ficou pior. Mais lento, mais caro, errando qual tool chamar em tarefa que antes acertava. Não é azar. É arquitetura.

Ninguém escolhe bem entre 50 opções jogadas na mesa de uma vez — nem você, nem o modelo. A saída tem nome: progressive disclosure. Em vez de despejar todas as ferramentas no contexto, o agente descobre o que precisa quando precisa. É um dos padrões centrais de quem constrói agente que escala em produção, e não só em demo.

Neste post você vai entender por que empilhar tool degrada a escolha, o que é progressive disclosure de verdade e três jeitos práticos de aplicar no seu agente hoje.

TL;DR

• O que é: carregar definições de ferramentas sob demanda, em vez de injetar todas no contexto de uma vez.
• Por que importa: menos token, menos latência e — o ponto que ninguém fala — escolha mais certeira de qual tool chamar.
• Padrão central: o agente vê um índice enxuto e busca o detalhe da ferramenta só na hora de usar.
• Referência: Code execution with MCP (Anthropic Engineering).

O problema: 50 ferramentas não te dão um agente 50x melhor

Toda tool que você pluga no agente entra no contexto como uma definição: nome, descrição, schema de parâmetros, exemplos. Uma só é barata. Cinquenta, não. E aqui mora o erro de quem está começando: tratar tool como feature que você acumula.

Tem dois custos somando ao mesmo tempo.

O primeiro é óbvio: token. A Anthropic é direta — quando o agente está conectado a milhares de ferramentas, ele precisa "processar centenas de milhares de tokens antes de ler o request" (Anthropic). Você paga esse imposto em toda chamada, mesmo que a tarefa use uma ferramenta só. É o mesmo problema que a gente discute em engenharia de contexto: o recurso mais escasso do agente é a janela, e encher de coisa que não serve degrada a resposta.

O segundo custo é o que dói de verdade: a escolha piora. Isso tem nome na literatura — prompt bloat. O paper RAG-MCP mediu: enchendo o prompt com todas as ferramentas, a acurácia de selecionar a tool certa caiu pra 13,62%. Filtrando antes e mostrando só as relevantes, subiu pra 43,13% — mais que o triplo — com mais de 50% menos tokens de prompt. Mesma tarefa, mesmo modelo. A única diferença foi não afogar o modelo em opção.

Faz sentido se você pensar no modelo como um dev. Dá um menu de 3 comandos e a pessoa acha o certo na hora. Dá um manual de 300 páginas e peça pra ela achar o comando "no meio disso aqui" — ela vai errar, ou vai demorar, ou as duas coisas.

Vale uma ressalva honesta: nem todo modelo degrada igual. Modelos mais agênticos aguentam tool sets maiores melhor que os menores. Mas "aguenta melhor" não é "fica bom". E tem um detalhe que mostra o tamanho do ponto cego: no Berkeley Function Calling Leaderboard, a média é de cerca de 3 funções por teste. Ou seja, o cenário de 50 ferramentas que você montou em produção mal foi testado nos benchmarks em que a gente confia. Você está em terreno que o número bonito não cobre.

O que é progressive disclosure

Progressive disclosure não é truque de IA. É um princípio velho de design de interface: mostre o essencial primeiro, revele o detalhe conforme a pessoa precisa. Menu que abre submenu. Configuração que tem o modo "avançado" escondido.

A Anthropic usa uma analogia boa pra explicar isso no contexto de agente: é como um manual bem organizado. Você começa pelo sumário, vai pro capítulo certo, e só então abre o apêndice com o detalhe técnico. Você não lê o manual inteiro pra trocar uma lâmpada.

No agente, a tradução é direta:

• O agente vê um índice — uma lista enxuta de ferramentas disponíveis, com nome e uma linha de descrição.
• Quando decide usar uma, ele carrega a definição completa daquela tool — o schema cheio, os parâmetros, os exemplos.
• O resto continua fora do contexto. Não pesa, não atrapalha, não confunde.

Conceito técnico, aplicação prática, impacto no produto — os três. O conceito é carregar sob demanda. A aplicação é separar índice de definição. O impacto é um agente que escala pra dezenas ou centenas de ferramentas sem virar uma sopa de tokens que erra a escolha.

Por que isso destrava token e acerto ao mesmo tempo

O ganho de token é o mais fácil de medir, e ele é absurdo quando a coisa é bem feita.

A Anthropic reescreveu um workflow real — pegar um documento no Google Drive e jogar num registro do Salesforce — usando esse padrão, com as ferramentas expostas como código num filesystem em vez de definições despejadas no contexto. O número: de cerca de 150 mil tokens para cerca de 2 mil. Uma redução de 98,7% (Anthropic). A frase que resume a mecânica é essa: "apresentar ferramentas como código num filesystem permite que os modelos leiam as definições sob demanda, em vez de lê-las todas de uma vez".

Mas reduzir token é o benefício chato. O benefício bom é o que o RAG-MCP mostrou lá em cima: a escolha melhora. Quando o agente decide entre 4 ferramentas relevantes em vez de 50, ele acerta mais. Menos ruído, menos distração, menos chance de chamar a tool errada porque a descrição parecia próxima.

E tem um terceiro ganho que passa despercebido. Quando o agente trabalha com ferramentas como código, os resultados intermediários podem ficar no ambiente de execução, e o modelo só vê o que você explicitamente retorna. Um transcript gigante, um JSON de 10 mil linhas — passa pelo seu pipeline sem nunca entrar no contexto do modelo. Isso é token economizado e dado sensível que não vaza pro prompt de graça.

Mão na massa: três jeitos de aplicar

Você não precisa do setup completo da Anthropic pra colher 80% do ganho. Tem três níveis, do mais simples ao mais robusto.

Padrão 1: índice + carregar definição sob demanda

O mais barato de implementar. Em vez de registrar 50 tools no modelo, você registra uma: algo como listar_ferramentas que devolve um índice enxuto. O agente lê o índice, decide, e chama uma segunda tool descrever_ferramenta(nome) que devolve o schema completo só daquela.

TOOLS_INDEX = [
    {"nome": "buscar_cliente", "desc": "Busca cliente por email ou CPF"},
    {"nome": "criar_fatura", "desc": "Emite fatura para um cliente"},
    {"nome": "enviar_email", "desc": "Dispara email transacional"},
    # ...mais 47, mas o modelo só vê esta linha enxuta
]

def descrever_ferramenta(nome: str) -> dict:
    # devolve o schema COMPLETO só da tool pedida
    return TOOL_SCHEMAS[nome]

O modelo vê 50 linhas de uma frase cada, não 50 schemas inteiros. A definição cara entra no contexto só quando ele decide usar aquela ferramenta.

Padrão 2: recuperação semântica do tool certo (RAG de tools)

Esse é o pulo do gato do RAG-MCP. Em vez de mostrar o índice inteiro, você embute a descrição de cada ferramenta num vetor e, dada a tarefa do usuário, recupera só as 3–5 mais relevantes pra injetar no prompt.

A tarefa "manda a fatura do mês pro cliente João" recupera buscar_cliente, criar_fatura, enviar_email — e ignora as outras 47. O agente decide num espaço pequeno e relevante. Foi exatamente isso que triplicou a acurácia no paper.

Padrão 3: ferramentas como código num filesystem

O nível Anthropic. As ferramentas viram arquivos de código (buscar_cliente.ts, criar_fatura.ts) num diretório. O agente navega a pasta, lê só o arquivo da ferramenta que vai usar, e escreve código que orquestra as chamadas — encadeando, filtrando e tratando resultado antes de devolver qualquer coisa pro modelo. É mais trabalho de infra, mas é o que entrega o 98,7%. É primo direto do programmatic tool calling: em vez de chamar tool a tool pelo modelo, o agente escreve o código que faz a orquestração.

Regra prática pra escolher: começando, faça o Padrão 1 — resolve a maioria dos casos com uma tarde de trabalho. Passou de ~20 ferramentas ou tem ferramentas muito parecidas entre si, vá pro Padrão 2. Está construindo plataforma de agente pra valer, com dezenas de integrações e dado pesado trafegando, o Padrão 3 paga o investimento.

Limitações e pontos de atenção

Não é bala de prata, e fingir que é seria hype barato.

Você troca tokens por uma ida e volta. No Padrão 1 e 2, descobrir a ferramenta vira um passo a mais — o agente lista/recupera antes de agir. Em tarefa trivial com 5 tools, isso pode ser latência desnecessária. Progressive disclosure paga quando o tool set é grande; em agente pequeno, registrar tudo direto ainda é o certo.

Índice ruim é pior que sem índice. Se as descrições de uma linha são vagas ou parecidas, o agente recupera a ferramenta errada e nem chega a ver a definição certa. A qualidade da descrição curta vira parte crítica do sistema. Capricha nela como você capricharia num nome de função.

Modelo importa. Modelos mais fortes aguentam tool sets maiores antes de degradar. Mede com o seu modelo e a sua carga de ferramentas antes de assumir que precisa do esquema completo — às vezes 15 tools diretas ainda funcionam bem no modelo que você usa.

Não esconda o que sempre é usado. Se três ferramentas aparecem em 90% das tarefas, mantê-las sempre visíveis no contexto pode ser melhor que forçar uma descoberta toda vez. Progressive disclosure é pra cauda longa de tools, não pra todas elas.

FAQ rápido

Isso é a mesma coisa que RAG? É o mesmo princípio aplicado a ferramentas em vez de documentos: recupera o relevante sob demanda em vez de jogar tudo no contexto. O Padrão 2 é literalmente RAG de tool definitions. A ideia de recuperar só o que importa é a mesma.

A partir de quantas ferramentas eu devo me preocupar? Não existe número mágico, mas a degradação aparece bem antes do que se imagina — os benchmarks em que confiamos testam em média 3 funções, então acima de ~10–15 você já está em terreno pouco validado. Se notou o agente errando escolha de tool, esse é o sinal.

Preciso de MCP pra fazer isso? Não. MCP facilita e é o contexto do material da Anthropic, mas progressive disclosure é um padrão de arquitetura. Dá pra implementar o Padrão 1 com duas funções comuns no seu framework de agente, sem MCP nenhum.

Vale a pena com modelo grande que "aguenta" muitas tools? Vale, por dois motivos: token continua custando dinheiro em escala, e "aguenta" não é "acerta sempre". Mesmo modelo bom melhora a escolha quando você reduz o ruído de opções irrelevantes.

Conclusão

O instinto de dar mais ferramentas pro agente é o mesmo instinto de quem acha que mais stack resolve. Não resolve. Um agente que escala não é o que tem mais tools no contexto — é o que vê a ferramenta certa na hora certa e ignora o resto. Progressive disclosure é como você passa de 5 para 50 ferramentas sem que a escolha desande e a conta de token exploda.

O próximo passo é parar de pensar em "quantas tools meu agente tem" e começar a pensar em "como meu agente descobre a tool certa". É decisão de arquitetura, não de quantidade. Se você quer ver esse tipo de decisão sendo tomada na prática — código rodando, trade-off na mesa, sem slide motivacional — é o que a gente destrincha no Workshop Arquitetando Soluções de IA, um workshop prático de como arquitetar software com agentes de IA de verdade.

Empilhar ferramenta é fácil. Arquitetar o que o agente vê é o trabalho. E é aí que mora a diferença entre uma demo bonita e um agente que aguenta produção.