Contagem de ferramentas é custo de contexto: por que meu servidor MCP expõe 6 ferramentas em vez de 26

Cada sessão começa da mesma maneira. Eu peço ao agente para mesclar alguns PDFs e remover os EXIF de algumas capturas de tela, e ele vai em busca de uma biblioteca, a instala, escreve um script, obtém um resultado que está ligeiramente errado, corrige o script e, em seguida, abre a saída apenas para confirmar que funcionou. Na próxima sessão, a mesma coisa do zero.

Então, eu envolvi as operações de arquivo atrás de um servidor MCP. A parte interessante não foi o envolvimento. Foi decidir quantas ferramentas expor.

A versão óbvia está errada

Eu já tinha 26 operações de arquivo construídas para um site: mesclar PDF, dividir PDF, girar, comprimir, proteger, desbloquear, PDF para JPG, redimensionar imagem, remover metadados, HWP para PDF, XLSX para CSV, código QR e assim por diante. O movimento óbvio é 26 operações, 26 ferramentas.

Isso é um erro, e a razão é chata, mas decisiva: as definições de ferramentas vivem no contexto do modelo em cada turno. Não quando a ferramenta é chamada. A cada turno. Vinte e seis esquemas com suas descrições e documentos de argumentos é um imposto fixo que você paga na primeira mensagem e em cada mensagem depois dela, em uma conversa onde o usuário pode precisar apenas de uma delas.

Há um segundo custo que é mais difícil de ver. Mais ferramentas significam mais chances de escolher a errada. pdf_compress versus pdf_optimize versus image_compress é uma distinção que é óbvia em uma página de documentação e genuinamente ambígua em uma lista de ferramentas.

Agrupar por trabalho, não por operação

A versão que eu enviei tem seis ferramentas. Operações relacionadas compartilham uma ferramenta e um argumento escolhe entre elas.

pdf_edit cobre nove operações atrás de um único esquema. O modelo escolhe a ferramenta pelo substantivo que está segurando (um PDF) em vez do verbo que está adivinhando, e o verbo vai em um argumento onde um palpite errado é um erro de validação em vez de uma viagem de ida e volta desperdiçada.

O que foi medido

Eu coloquei os mesmos quatro arquivos em duas sessões e entreguei a mesma frase de tarefa ao mesmo modelo. Uma sessão tinha apenas este servidor. A outra não tinha ferramentas dedicadas e estava livre para usar o shell e o Node.

53% menos custo, 93% menos tempo. Os números de tokens e custo não são estimativas, são os números por mensagem que as sessões registraram, somados.

Uma coisa para ler com atenção: a sessão simples nunca começou duas das quatro tarefas. Ela queimou tempo encontrando e instalando bibliotecas para dois documentos coreanos (HWP, um formato binário fechado que é padrão na documentação do governo e escolar coreano, e basicamente não tem biblioteca de substituição fora da Coreia). Portanto, a diferença é um piso, não um teto. Se tivesse sido forçada a terminar todas as quatro, a distância seria maior, e a maior parte da distância extra viria de um problema de formato em vez do design da ferramenta.

A regra que eu daria a outra pessoa

Conte quantos esquemas de ferramenta um usuário precisa carregar para obter valor do seu servidor na primeira mensagem. Se esse número for maior do que o número de substantivos distintos que seu servidor opera, você está enviando um menu em vez de uma interface.

Os substantivos para mim eram: um documento, um PDF, uma imagem, um código QR. Quatro substantivos, seis ferramentas, porque PDFs precisavam de um companheiro somente leitura e documentos precisavam de um leitor e um conversor. Se eu tivesse construído isso com foco na operação, teria enviado 26 e teria sido pior de uma maneira que é muito difícil de notar, porque nada quebra. Apenas custa mais a cada turno.

Executando

claude mcp add ezpzfile -- npx -y ezpzfile-mcp

Node 22.13+, MIT, tudo roda localmente e nenhum arquivo é enviado. O código-fonte está em github.com/ezpzfile/ezpzfile-mcp, o pacote está em npm, e a lista de ferramentas com todos os argumentos está em ezpzfile.com/mcp.

A remoção de fundo é a única exceção a "nada toca a rede" — ela baixa um modelo na primeira vez que você pede um recorte, depois o armazena em cache. Ainda assim, não envia nada.

Se você construiu um servidor MCP, estou curioso para saber onde você chegou em relação à contagem de ferramentas e se você mediu isso ou apenas estimou.