Ferramentas Fantasma

Como reconhecer

Um agente interno de dados tem 12 ferramentas. Ninguém lembrava por que algumas estavam lá, então o time contou as chamadas nos traces dos últimos 90 dias:

ferramenta              chamadas   última chamada
query_warehouse         18.402     hoje
describe_table          6.117      hoje
list_tables             2.954      hoje
export_csv              1.088      ontem
legacy_query_v1         0          há 7 meses
send_report_email       0          nunca
create_dashboard        0          nunca
refresh_cache           0          há 5 meses
get_metadata_old        0          há 7 meses
schedule_job            0          nunca
delete_temp_tables      0          há 4 meses
run_python              0          nunca

Oito das doze ferramentas não foram chamadas em três meses. Quatro nunca foram. Mesmo assim, todas vão em toda chamada ao modelo. Duas delas (delete_temp_tables e run_python) têm efeito: apagam dados ou executam código.

Sinais de Ferramentas Fantasma:

• Ferramentas que não aparecem nos traces há meses continuam na lista.
• Ninguém sabe dizer se alguma ainda é necessária, nem quem pediu.
• Versões antigas convivem com as novas (_v1, _old, legacy_).
• Ferramentas com efeito ficam disponíveis sem que nenhuma tarefa precise delas.
• As definições ocupam uma parte relevante do contexto de cada chamada.

flowchart LR
  T[("1. 12 ferramentas na lista")]:::store --> M(["2. Modelo lê todas em toda chamada"]):::llm
  M --> U["3. Usa sempre as mesmas 4"]:::tool
  T --> X["4. 8 sem uso, 2 com efeito"]:::untrusted

1. A lista cresceu ao longo do tempo, uma ferramenta por pedido.
2. Todas as definições entram no contexto de cada chamada, usadas ou não.
3. O uso real se concentra em poucas.
4. As outras só ocupam espaço e, quando têm efeito, aumentam o risco.

Quanto pesa uma ferramenta que ninguém chama

A definição de uma ferramenta é texto: nome, descrição e o JSON Schema dos parâmetros. O provedor injeta esse texto no prompt em toda requisição. Uma definição com descrição decente e quatro ou cinco parâmetros costuma passar de cem tokens.

Faça a conta com números de exemplo. Suponha 200 tokens por definição e 8 ferramentas sem uso: são 1.600 tokens de entrada a mais por chamada. Com 10 mil chamadas por dia, isso dá 16 milhões de tokens por dia pagando para o modelo ler ferramentas que ele nunca escolhe. Para saber o seu número, conte os tokens do array de ferramentas com o tokenizador do seu provedor.

Checagem +20 XP de primeiraSeu agente tem 15 ferramentas e o trace dos últimos 60 dias mostra que 9 nunca foram chamadas. O agente responde bem. Qual é o custo mais direto de deixar as 9 lá?

Nenhum, já que o modelo não as escolhe

Tokens de entrada pagos em toda chamada e mais opções competindo na escolha

Só o custo de manter o código das ferramentas

Por que acontece

• Ferramentas entram e nunca saem. Acrescentar leva cinco minutos. Remover exige descobrir se alguém usa, e ninguém tem esse dado.
• Planos que não aconteceram. create_dashboard foi criada para um recurso que não foi lançado. O recurso morreu; a ferramenta ficou.
• Migrações pela metade. A versão nova entrou, a antiga ficou “por segurança”. Seis meses depois, ninguém lembra qual é qual.
• Sem dado de uso. Sem um span por chamada de ferramenta, a única fonte de verdade é a memória do time.
• Demos generosas. Para impressionar numa apresentação, o agente ganhou ferramentas “que podem ser úteis”. Em produção, ninguém pediu aquilo.

Quanto custa ignorar

• Tokens desperdiçados em toda chamada, como na conta acima. O custo cresce junto com o volume, sem que nada novo aconteça.
• Escolhas erradas. legacy_query_v1 e query_warehouse têm descrições parecidas. Um dia o modelo escolhe a antiga, que lê uma tabela desatualizada, e a resposta sai errada sem erro nenhum.
• Superfície de ataque. Uma ferramenta de efeito que ninguém usa é uma porta que ninguém vigia. Se um texto malicioso entrar no contexto, run_python está ali, pronta. O OWASP Top 10 for LLM Applications (edição 2025) chama isso de Excessive Agency, e “funcionalidade excessiva” é a primeira causa da lista.
• Manutenção fantasma. Uma API muda e quebra a ferramenta esquecida. Ninguém percebe até o dia em que o modelo resolve usá-la.

Tratamento

Refatoração	Escolha quando
Consolidar Ferramentas	Sempre. Remova as que não são chamadas, junte as que se sobrepõem e mantenha a remoção reversível por um tempo. Destinos: Roteador de Ferramentas e Revelação Progressiva.

Antes de remover, você precisa da contagem. Se ela não existe, comece por Adicionar Trace e deixe rodar algumas semanas. Com spans por ferramenta, a contagem é uma consulta:

select tool_name, count(*) as calls, max(started_at) as last_call
from spans
where kind = 'tool_call' and started_at > now() - interval '90 days'
group by tool_name
order by calls desc

Remova em etapas

Tirar a ferramenta do schema e apagar o código no mesmo dia é o jeito mais rápido de descobrir, em produção, que ela era usada por um fluxo raro. Faça em três etapas:

1. Esconda. Tire a definição da lista enviada ao modelo, mas mantenha o código. Rode o eval do agente antes e depois para conferir que nada piorou.
2. Observe. Por algumas semanas, registre qualquer tentativa de chamar o nome removido. Modelos às vezes “lembram” de ferramentas citadas em exemplos ou no histórico.
3. Apague. Sem tentativas e com o eval estável, remova o código.

A armadilha das ferramentas raras

Zero chamadas em 90 dias não prova que a ferramenta é inútil. Algumas tarefas têm calendário: fechamento de trimestre, declaração anual, recuperação de desastre. Antes de apagar, pergunte ao dono do fluxo. Se a ferramenta é rara mas necessária, a resposta não é removê-la, e sim carregá-la só quando a tarefa pede, com Revelação Progressiva.

Checagem +20 XP de primeiraO time escondeu export_csv_v1 do schema na segunda-feira. Na quinta, o log mostra duas tentativas do modelo de chamar esse nome. O que isso indica?

Que a remoção foi um erro e a ferramenta deve voltar

Que o modelo está alucinando e o log pode ser ignorado

Que algum prompt, exemplo ou histórico ainda cita o nome antigo

O que você ganha

Antes	Depois
12 definições em toda chamada	4 sempre visíveis, as raras sob demanda
Duas versões da mesma consulta	Uma ferramenta por trabalho
run_python disponível sem uso	Nenhuma ferramenta de efeito sem dono
Lista que ninguém revisa	Lista curta, com uso medido

Quando ignorar

• Ferramentas de uso raro, mas crítico. Uma ferramenta de recuperação de desastre pode ser chamada uma vez por ano. Mantenha, mas considere carregá-la só quando necessária.
• Agente recém-lançado. Com duas semanas de uso, a contagem diz pouco. Espere dados que cubram ao menos um ciclo completo do negócio.
• Lista pequena e sem efeito. Três ferramentas de leitura, uma delas pouco usada, não justificam uma refatoração. Anote e revise junto com a próxima mudança.

É esse smell?

Checagem +20 XP de primeiraUma ferramenta foi chamada 3 vezes em 90 dias, sempre em tarefas de fechamento de mês, e nas três vezes resolveu a tarefa. É Ferramenta Fantasma?

Não, mas ela pode ser carregada sob demanda

Sim, porque o uso é muito baixo

Sim, e deve ser removida para economizar tokens

Checagem +20 XP de primeiraO agente tem 6 ferramentas, todas usadas toda semana, mas duas fazem quase a mesma coisa com nomes diferentes. Qual smell?

Ferramentas Fantasma

Ferramentas Demais

Checagem +20 XP de primeiraO time não tem traces por ferramenta e quer saber quais remover. Qual é o primeiro passo?

Remover as que parecem antigas pelo nome

Perguntar ao modelo quais ferramentas ele usa

Registrar o uso de cada ferramenta por algumas semanas

Checagem +20 XP de primeiraEntre as ferramentas sem uso há delete_temp_tables, que apaga tabelas. O agente só responde perguntas de leitura. Por que ela merece prioridade na limpeza?

Porque é a que mais gasta tokens

Porque é uma ação destrutiva ao alcance do modelo sem nenhuma tarefa que precise dela

Porque ferramentas de efeito ficam lentas quando não são usadas