Lo que aprendí al crear 50 herramientas MCP: las llamadas a funciones eran una relación anormalmente íntima

Un texto que, a partir de la experiencia de mover durante dos días del fin de semana una herramienta de gestión de activos a un CLI basado en SQLite y a un servidor MCP,
ordena en qué punto el diseño de herramientas MCP se separa de forma decisiva del RPC.
El autor creó unas 30 órdenes de CLI y unas 50 herramientas MCP, pero descubrió que, pese al volumen de código,
lo que más tiempo le tomó no fue el código sino la descripción de las funciones.

• Al exponer la misma función a la vez en CLI y MCP, aunque la firma/los argumentos/los valores de retorno eran exactamente los mismos, las dos interfaces funcionaban de manera distinta. Lo único que cambió fue si quien invocaba era un humano o un LLM
• La firma explica qué recibe una función, pero casi no puede explicar cuándo debe llamarse. El nombre de una función se parece más a una línea de diccionario, así que la palabra por sí sola no puede decidir sobre qué oración debe colocarse
• Para un invocador LLM, en vez de herramientas divididas en partes pequeñas siguiendo el principio de responsabilidad única (SRP), resultan más naturales las herramientas pesadas que llegan directo a la intención
• MCP, si se mira solo la forma, pertenece al linaje RPC (JSON-RPC, firmas, esquemas), pero la diferencia decisiva es que la dirección de la confianza se invierte. En RPC, quien llama confía en aquello que llama; en MCP, quien creó la herramienta debe confiar en quien llama (el LLM)
• La firma es una declaración y la descripción es una petición. Una impone y la otra persuade. Es como si en el diseño de herramientas hubiera empezado a entrar el lenguaje de la persuasión
• Más que un cambio completamente nuevo, esto se parece más a una regresión. El diseño industrial, la arquitectura y UX ya estaban en ese lugar desde hace mucho; la programación simplemente había permanecido en un extremo inusualmente íntimo todo este tiempo

Lo que la firma no dice

• En Firma, add_txn (transacción), add_balance (snapshot de activos) y add_flow (ingreso/gasto) tenían firmas claras y los tipos de argumentos estaban definidos estrictamente con esquemas de zod, pero el LLM se confundía con frecuencia sobre qué herramienta llamar a partir de la frase del usuario
• Al principio se sospechó que era un problema del modelo LLM, pero el problema real estaba en la firma misma. El nombre add_txn no contiene el momento de invocación de “si el usuario habló de una compra o venta, usa esta herramienta”
• Solo después de definir la description en forma de "Use this when... Do NOT use this for...", dejando explícitos el momento de invocación y el límite con otras herramientas, la invocación se estabilizó
• La intención de la función se desplazó desde la firma hacia la descripción de la función. Igual que el mango de un martillo sugiere por su forma cómo se usa, la descripción de una función MCP equivale en la práctica a la affordance de la herramienta para el LLM (Donald Norman)

SRP vs affordance, y la dirección de la confianza

• Al principio se intentó dividir todo finamente según el principio de responsabilidad única, con cosas como get_holdings, get_prices, get_pnl, pero cuando el usuario preguntaba “¿cómo va mi portafolio?”, el LLM tenía que combinar cuatro o cinco llamadas, la respuesta se volvía lenta y aumentaban las posibilidades de desajuste
• Al final, show_portfolio se diseñó como una herramienta pesada que devuelve de una sola vez posiciones, precio promedio de compra, precio actual, valor de mercado y ganancia/pérdida acumulada. get_brief va todavía más allá y devuelve también indicadores macro e insights de una vez
• El SRP es una virtud de quien crea funciones; la affordance es una virtud de quien usa herramientas. Si quien llama es humano, se puede ensamblar; si es un LLM, convienen más las herramientas que llegan directo a la intención
• En las herramientas de escritura es donde la dirección de la confianza se ve con más claridad. Al escribir en add_txn "Always confirm with the user before recording", el LLM preguntaba cada vez y el usuario respondía cada vez “ok”, con lo que desaparecía la ventaja de una interfaz en lenguaje natural
• Al final, se volvió a repartir la responsabilidad en la forma de “registra de inmediato, pregunta solo cuando haya ambigüedad, y si está mal se puede deshacer”. Este tipo de guía no es una descripción formal de la herramienta, sino un principio operativo que se le da a quien llama

Quizá las llamadas a funciones eran, en realidad, el caso especial

• Los humanos siempre han usado herramientas que no fabricaron ellos mismos. Lo mismo vale para una vasija hecha por un alfarero, un cuchillo hecho por un herrero o un programa hecho por un desarrollador
• Las llamadas a funciones eran, en ese sentido, una relación bastante especial, donde quien llama y quien escribe comparten mucho contexto, y el sistema de tipos/IDE/documentación siguen reforzando esa intimidad
• Si quien llama no es humano, hay dos opciones. (1) meter más contexto en el LLM para convertirlo en un invocador íntimo, (2) cerrar la distancia desde el lado de la herramienta. MCP se acerca más a lo segundo
• Puede que estemos en un momento en que la propia forma de diseñar interfaces está cambiando silenciosamente. El centro de gravedad se está moviendo de la firma a la descripción, de la imposición a la persuasión, y de asumir intimidad a reconocer la distancia