O que aprendi ao criar 50 ferramentas MCP: chamadas de função eram uma relação anormalmente íntima

Com base na experiência de migrar, ao longo de dois dias de fim de semana, uma ferramenta de gestão de ativos para uma CLI baseada em SQLite e um servidor MCP,
este texto organiza em que ponto o design de ferramentas MCP se separa decisivamente do RPC.
O autor criou cerca de 30 comandos de CLI e cerca de 50 ferramentas MCP e parte da constatação de que, apesar de todo esse volume,
o que mais consumiu tempo não foi o código, mas sim a descrição das funções.

• Ao expor a mesma função simultaneamente na CLI e no MCP, mesmo com assinatura/argumentos/valores de retorno idênticos, as duas interfaces
  funcionaram de forma diferente. A única mudança foi se o chamador era um humano ou um LLM
• A assinatura explica o que a função recebe, mas quase não consegue explicar quando ela deve ser chamada. O nome da função
  é próximo de uma linha de dicionário, então a palavra em si não determina em que frase ela deve aparecer
• Para um chamador LLM, em vez de ferramentas pequenas e divididas pelo princípio da responsabilidade única (SRP), ferramentas mais pesadas, que tocam diretamente a intenção, são mais naturais
• Formalmente, o MCP pertence à linhagem do RPC (JSON-RPC, assinaturas, esquemas), mas a diferença decisiva é que a direção da confiança se inverte. No RPC, o chamador confia no alvo da chamada; no MCP, quem criou a ferramenta precisa confiar no chamador (LLM)
• A assinatura é uma declaração e a descrição é um pedido. Um lado impõe, o outro persuade. É como se a linguagem da persuasão tivesse começado a entrar no design de ferramentas
• Mais do que uma mudança nova, isso está mais perto de uma regressão. Design industrial, arquitetura e UX já estavam nesse mesmo ponto há muito tempo,
  e a programação é que vinha permanecendo numa extremidade excepcionalmente íntima

O que a assinatura não diz

• Em Firma, add_txn (transação), add_balance (snapshot de ativos) e add_flow (receitas/despesas) tinham assinaturas claras e tipos de argumento rigorosamente definidos com esquemas zod, mas o LLM frequentemente se confundia ao decidir qual ferramenta chamar a partir da fala do usuário
• No início, suspeitou-se de um problema do modelo LLM, mas o problema real estava na própria assinatura. O nome add_txn
  não contém o momento de invocação do tipo “se o usuário falou de compra e venda, use esta ferramenta”
• Só depois de explicitar, na descrição, o momento de chamada e os limites em relação a outras ferramentas no formato "Use this when... Do NOT use this for..." as chamadas se estabilizaram
• A intenção da função migrou da assinatura para a descrição da função. Assim como o cabo de um martelo sugere pela forma como deve ser usado,
  a descrição de uma função MCP equivale, na prática, à affordance da ferramenta para o LLM (Donald Norman)

SRP vs affordance, e a direção da confiança

• No começo, a ideia era dividir tudo de acordo com o princípio da responsabilidade única, com coisas como get_holdings, get_prices e get_pnl, mas quando o usuário pergunta “Como está meu portfólio?”, o LLM precisa combinar quatro ou cinco chamadas, a resposta fica lenta e aumenta a chance de desencontro
• No fim, show_portfolio foi projetada como uma ferramenta pesada que retorna de uma vez só ativos em carteira/preço médio de compra/preço atual/valor avaliado/lucro e prejuízo acumulados. get_brief vai além e retorna, de uma vez, indicadores macro e insights
• SRP é uma virtude para quem cria a função; affordance é uma virtude para quem usa a ferramenta. Se o chamador é humano, dá para montar as peças; se é um LLM, ferramentas que tocam diretamente a intenção funcionam melhor
• Nas ferramentas de escrita, a direção da confiança aparece de forma mais clara. Ao colocar em add_txn "Always confirm with the user before recording", o resultado foi um LLM perguntando toda vez e o usuário respondendo toda vez “ok” — a vantagem da interface em linguagem natural desaparece
• No fim, a responsabilidade foi redistribuída na forma de "registre imediatamente, pergunte apenas quando houver ambiguidade, e, se estiver errado, deve ser possível desfazer". Esse tipo de orientação não é uma descrição formal da ferramenta, mas sim um princípio operacional dado ao chamador

Talvez chamadas de função sempre tenham sido o caso especial

• Humanos sempre usaram ferramentas que não foram feitas por eles mesmos. O vaso feito pelo oleiro, a faca feita pelo ferreiro, até o programa feito pelo desenvolvedor: tudo entra nisso
• Chamada de função talvez tenha sido, na verdade, uma relação bem especial, em que chamador e autor compartilham muito contexto e essa intimidade é continuamente reforçada por sistema de tipos/IDE/documentação
• Se o chamador não é humano, há duas opções. (1) colocar mais contexto no LLM para torná-lo um chamador íntimo, (2) a ferramenta reduzir essa distância do seu lado. O MCP está mais perto da segunda opção
• Pode ser que estejamos num período em que a própria forma de projetar interfaces esteja mudando silenciosamente. O centro de gravidade está se deslocando da assinatura para a descrição, da imposição para a persuasão, da suposição de intimidade para o reconhecimento da distância

[silveris23]

Ao criar MCPs para LLMs, acabei concordando com o que você disse.

Mas... ao mesmo tempo, não consigo deixar de pensar que talvez projetar melhor o contexto e manter as ferramentas (APIs) muito limitadas e simples — algo como os princípios tradicionais de design de software, tipo SRP — não torne isso mais flexível?

Acho que a parte difícil nos LLMs é projetar a intenção e o contexto que não foi explicitado. Talvez, nessa parte, a direção tenha mais a ver com educação / filosofia do que com programação. Talvez até seja melhor perguntar de volta algo como: “é disso que você está falando?”. Compartilhar o plano antes da execução e ir acrescentando reflexões para construir o contexto ao longo do processo.

A assinatura da função kkk talvez seja uma informação mais necessária para o compilador? do que para o desenvolvedor rsrs
Os desenvolvedores, na verdade, já sabiam há muito tempo que o importante eram os comentários em volta, antes e depois.

Obrigado pelo ótimo texto