Diseño de herramientas MCP: enfoques prácticos y compensaciones

Cuando las herramientas del Model Context Protocol (MCP) tienen un rendimiento deficiente, la causa rara vez es el protocolo en sí, sino el diseño de la herramienta. Muchos equipos comienzan exponiendo una API existente tal como está y confiando en que el agente descubrirá el resto. Es una forma natural de extender las API a sistemas agentes y herramientas de codificación de IA generativa. Para casos de uso sencillos, puede funcionar. Pero a menudo no es así.

Debe diseñar sus herramientas sobre cómo funcionan los modelos de lenguaje grandes (LLM) y los sistemas agentes. Sin esto, corre el riesgo de realizar llamadas fallidas a herramientas, valores de parámetros incorrectos y reintentos que desperdician contexto y degradan el rendimiento. En esta publicación, mostramos dónde falla el diseño de la herramienta MCP y cómo solucionarlo con enfoques prácticos de ingeniería contextual.

Dos problemas se esconden detrás de la mayoría de estos fracasos. El primero es la hinchazón. Las definiciones de herramientas se cargan en el contexto del LLM en cada llamada, ya sea que se utilice la herramienta o no. Varios servidores MCP conectados pueden consumir un contexto significativo antes de que el usuario haya hecho una sola pregunta. A medida que el contexto se llena, la capacidad de razonamiento de un LLM puede degradarse y hacer que la sesión se vuelva menos productiva.

El segundo es la confusión. A medida que el razonamiento se degrada, el LLM toma peores decisiones, llama a la herramienta incorrecta y elige parámetros incorrectos. Los reintentos posteriores agravan el problema y contribuyen aún más a la inflación. La similitud semántica entre herramientas, demasiadas opciones y denominaciones ambiguas también contribuyen a la confusión. Una solución común es enriquecer las descripciones de las herramientas con definiciones más claras, asignaciones de lenguaje natural y ejemplos de uso. Esto ayuda con la confusión. Pero todo lo añadido corre el riesgo de empeorar la hinchazón y agravar el problema que estás tratando de resolver.

Este patrón es común. Su agente toma decisiones inesperadas, el contexto se llena antes de lo esperado y su sesión rápidamente se vuelve menos útil. Abordar la hinchazón y la confusión es un problema de ingeniería contextual. La ingeniería de contexto da forma a lo que ve el LLM y cuándo lo ve, por lo que el modelo produce mejores resultados. Mejorar uno o ambos es un acto de equilibrio complejo.

Las siguientes secciones exploran enfoques y compensaciones para abordar estos problemas. Para hacerlos concretos, creamos varios ejemplos que exponen una API de búsqueda de contenido K-12 simulada utilizando el protocolo MCP. Los ejecutará localmente e interactuará con ellos usando Kiro CLI para comparar las diferencias usted mismo.

Enfoques y compensaciones

Los enfoques que compartimos abordan estos problemas a nivel de herramienta. Algunos dan forma a lo que ve el LLM o cuando lo ve. Otros cambian la forma en que se estructuran las herramientas. Al aplicarlos, es necesario comprender cómo afectan la hinchazón y la confusión para encontrar el equilibrio adecuado entre ambos.

Descripciones y respuestas

El primer paso natural para corregir el comportamiento de la herramienta MCP es mejorar las descripciones. Una forma confiable de reducir la confusión es aclarar qué significan los valores, cómo se relacionan con ellos el lenguaje natural y para qué sirve la herramienta. Pero si va demasiado lejos, rápidamente aumentará la hinchazón. El contexto y el costo pueden aumentar rápidamente cuando se cargan muchos servidores MCP en un cliente.

Lo que devuelve la herramienta también moldea el comportamiento. Una herramienta que devuelve 50 campos por resultado llena el contexto rápidamente. Si 5 son suficientes para tomar una decisión, de forma predeterminada la respuesta a esos campos y proporciona una opción separada para solicitar una vista detallada. Según la investigación de Anthropic, cambiar a un enfoque bajo demanda para obtener resultados detallados reduce los tokens de respuesta en aproximadamente dos tercios.

Los mensajes de error adecuados son otra forma de mejorar la eficiencia. Cuando falla una llamada a una herramienta, errores útiles pueden orientar el siguiente intento. Una respuesta que dice "la búsqueda requiere 2 o más términos en la consulta" le dice al LLM exactamente qué cambiar. Una respuesta que devuelve sólo “sin resultados” no da nada, lo que hace que el modelo se dé por vencido o siga adivinando.

Restricciones de esquema

Cuando las descripciones y los errores adecuados guían al LLM hacia los valores correctos, las restricciones de esquema como enumeraciones y valores predeterminados pueden eliminar las conjeturas por completo. Considere lo siguiente para abordar problemas comunes de esquema:

Cambie el nombre de los parámetros para que coincidan con la forma en que el LLM podría entender el dominio, no con la forma en que su base de datos etiqueta sus columnas. Un parámetro llamado Resource_class con valores como 'Recurso para estudiantes' o 'Apoyo para profesores' es más claro para el LLM. Una columna content_bucket requiere que el LLM conozca una convención interna. Establezca los valores predeterminados en los valores más comunes para que el LLM solo necesite especificar qué varía. Restrinja los campos de valores finitos con enumeraciones para que el esquema mismo le indique al LLM qué es válido. Elimine los campos que rara vez se usan o que el LLM no puede usar bien.

Herramientas de reestructuración y contexto bajo demanda

Dividir una herramienta multipropósito en varias herramientas específicas proporciona claridad al modelo y proporciona resultados más granulares. Una herramienta de descubrimiento de carga diferida es un ejemplo. Puede eliminar descripciones de herramientas complejas del contexto siempre cargado y proporcionar una herramienta separada para la recuperación bajo demanda. El LLM solo recupera este contexto cuando la tarea lo requiere. Esto mantiene el contexto ágil y enfocado. La herramienta de búsqueda de herramientas de Anthropic y Amazon Bedrock AgentCore Gateway muestran estos conceptos aplicados a escala. Anthropic informa una reducción de tokens de hasta un 85 % al cargar definiciones de herramientas solo cuando es relevante.

Las habilidades son otro ejemplo de carga diferida, pero implementada en el lado del cliente. Estos archivos locales contienen contexto útil para la herramienta, pero solo se leen en contexto cuando es relevante. Esto reduce el esfuerzo para implementarlos y distribuirlos. Pero no hay garantía de que la habilidad se cargue cuando sea necesario o que permanezca sin cambios una vez instalada.

Inferencia del lado del servidor

La ingeniería de contexto es un desafío cuando no se controla qué modelo interpretará sus instrucciones. Y una vez implementado, es posible que no pueda controlar qué LLM llama a sus herramientas MCP. Una descripción adaptada a un modelo podría confundir a otro. Probar completamente todos los modelos potenciales que un cliente podría utilizar no es realista.

Una forma de abordar esto es agregar una herramienta de introspección que llame directamente a un LLM externo. El cliente utiliza lenguaje natural para consultar su herramienta de introspección y recibe instrucciones específicas para usar las otras herramientas. Debido a que usted elige el modelo, puede solicitarle que diseñe correctamente esta herramienta y pruebe con consultas de oro. El LLM del cliente aún realiza la llamada final a la herramienta, pero su LLM interpreta la necesidad y proporciona los valores correctos. Debido a que el caso de uso está enfocado, un modelo más pequeño y más rápido maneja bien esta tarea y mantiene los costos razonables a escala.

Herramientas agentes

Cuando necesite precisión y control total, la siguiente progresión lógica es respaldar todo su servidor MCP con un agente propio. El ejemplo de introspección maneja un solo paso de interpretación, pero una herramienta agente maneja toda la interacción. Las herramientas se convierten en puntos finales de lenguaje natural para el cliente. Indica lo que necesita y su agente hace el resto. Las otras técnicas cubiertas todavía se aplican. Las compensaciones son completamente suyas, pero al igual que con la introspección, puede diseñar completamente el comportamiento con el modelo de su elección.

La siguiente sección analiza el código de trabajo que aplica estos enfoques en las mismas consultas de prueba y backend, para que pueda comparar su comportamiento directamente.

Tutorial

Cada una de las 6 versiones incluye el mismo backend de búsqueda de contenido K-12 simulado con un diseño de herramienta MCP diferente. El backend tiene 14 campos filtrables (materia, calificación, formato, alineación de estándares, idioma, clase de recurso y otros) con vocabularios controlados. El desafío para el LLM es cerrar la brecha entre cómo un maestro expresa una solicitud y los valores exactos que aceptan esos campos. V1 comienza con el paso sin procesar que deja esta brecha abierta. Cada versión posterior lo cierra de manera diferente.

Requisitos previos

Necesita lo siguiente para ejecutar el código de muestra:

Clone el repositorio de código de muestra y siga el archivo README del repositorio para obtener instrucciones detalladas sobre los requisitos previos, la instalación y el inicio del servidor. El tutorial siguiente supone que se están ejecutando las seis versiones.

No se implementa ninguna infraestructura en AWS. Ejecutas todo el código localmente. Las llamadas de inferencia a Amazon Bedrock son el único costo además del cliente de codificación. Consulte los precios de Amazon Bedrock para conocer las tarifas actuales.

Este tutorial supone que está utilizando Kiro y ha ejecutado python scripts/setup_agents.py desde el repositorio.

Consultas de prueba

Estas consultas devuelven resultados reales de la base de datos de muestra. Pruébelos con cada versión:

"Encuéntrame un cuestionario sobre fracciones para mis alumnos de séptimo grado". “¿Tienes alguna lección para enseñar español en la escuela secundaria?” "Necesito contenido alineado con TEKS para niños que trabajan en la división en la escuela secundaria". "¿Qué tipos de contenido puedo buscar?" "¿Puedo obtener detalles sobre n-sc-1096?"

A medida que recorre cada versión:

Observe si el LLM eligió los valores de filtro correctos en la primera llamada. Tenga en cuenta cuántas llamadas a herramientas fueron necesarias. Verifique si la respuesta incluyó información que el LLM no necesitaba. Observe qué tan rápido se llena la ventana contextual. Verifique el porcentaje que se muestra en Kiro o use /context show para obtener un desglose detallado.

Para cambiar entre versiones, utilice /agent swap (por ejemplo, /agent swap v1-passthrough). Borre el contexto con /clear entre versiones para que los resultados anteriores no influyan en el siguiente.

V1: paso sin procesar

v1_passthrough.py

La primera versión es el antipatrón básico. Expone la API de backend directamente. La definición de la herramienta tiene 14 parámetros con nombres internos como disciplina, tipo_medio, cubo_contenido y una cadena de documentación de una línea que dice "Realiza una búsqueda global de recursos educativos". No se enumeran valores válidos, ni asignaciones de lenguaje natural, ni orientación.

La definición de la herramienta es pequeña, pero el LLM no tiene orientación sobre qué valores son válidos. Pruebe la primera consulta. Podría pasar "cuestionario" para tipo_medio cuando el valor válido es "Evaluación" o "matemáticas" cuando el campo espera "Matemáticas". Cada elección incorrecta desencadena un reintento que consume más contexto. La única pista de que algo salió mal es un resultado vacío. El LLM se queda adivinando qué cambiar en el próximo intento. El bajo costo inicial es engañoso cuando la confusión aumenta el costo real a través de la deserción.

V2: descripciones ricas

v2_better_descriptions.py

Misma estructura que V1, refactorización de backend cero. La cadena de documentación ahora enumera valores válidos y asignaciones de sinónimos para cada campo. Por ejemplo, la disciplina muestra "Válido: Matemáticas, Ciencias, Alfabetización/ELA…" y mapas de tipo_medio "'cuestionario'/'prueba' → Evaluación, 'hoja de trabajo' → Actividad". También distingue la búsqueda difusa (palabra clave) de los filtros estrictos (todo lo demás). Se eliminan tres parámetros raramente utilizados y los mensajes de error ahora devuelven orientación sobre qué filtros agregar, en lugar de un resultado vacío.

Pruebe las mismas consultas. La precisión mejora inmediatamente porque el LLM ve valores válidos y asignaciones de sinónimos. La definición de la herramienta es notablemente mayor. Ésa es la compensación de la inflación. Cada llamada vale, ya sea que se utilice la herramienta o no. Después de cinco consultas, compare el contexto total consumido con la V1. La sobrecarga por llamada es mayor, pero un menor número de reintentos a menudo hace que el total sea menor.

V3: Esquema y valores predeterminados

v3_rethinked_schema.py

Esta versión cambia el nombre de los parámetros para que coincidan con la forma en que el LLM piensa y restringe los valores a través del esquema mismo. Se cambia el nombre de los parámetros: la disciplina se convierte en tema, content_bucket se convierte en recurso_clase. Cada campo de valor finito utiliza un tipo Literal que enumera opciones válidas directamente en el esquema. Los valores predeterminados sensatos manejan el caso común: estructura="Activo", recurso_clase="Recurso estudiantil", idioma="en". Una herramienta get_resource_detail separada maneja el desglose. Esto aplica el enfoque de reestructuración, dando a cada herramienta un trabajo claro y manteniendo concisas las respuestas de búsqueda.

Las enumeraciones ayudan a evitar valores incorrectos a nivel de protocolo. Los valores predeterminados significan que el LLM solo especifica lo que varía. La respuesta incluye un campo defaults_applied para que el LLM sepa qué se filtró implícitamente. La definición es más pequeña que V2 porque los nombres y enumeraciones hacen el trabajo que antes hacían las descripciones detalladas. Ejecute las consultas y compare la precisión con la V2. La precisión mejora mientras el contexto disminuye.

V4: Carga diferida (reestructuración)

v4_lazy_loading.py

En lugar de incorporar enumeraciones y descripciones detalladas en la herramienta de búsqueda, este enfoque las coloca detrás de una herramienta separada. La herramienta de búsqueda mantiene sólo descripciones breves como "Área temática, por ejemplo, 'Matemáticas', 'Ciencias', 'Alfabetización'". Una herramienta get_taxonomy toma una lista de nombres de campos y devuelve valores válidos y asignaciones de lenguaje natural solo para los campos relevantes para la consulta actual.

La definición de la herramienta de búsqueda es la más sencilla hasta el momento. Observe las llamadas de la herramienta. Para consultas ambiguas, el LLM llama a get_taxonomy antes de buscar para confirmar valores válidos. Para consultas sencillas en las que las sugerencias son suficientes, puede omitir por completo la llamada de taxonomía y buscar directamente. Los valores comunes en las sugerencias manejan consultas frecuentes sin ida y vuelta, mientras que la taxonomía completa está disponible para casos extremos. Debido a que la taxonomía se carga solo cuando es necesario, cada interacción previa en la sesión se ejecuta sin ese costo de contexto. El ahorro en este ejemplo es modesto, pero en entornos con muchas herramientas conectadas y esquemas de herramientas complejos, se agrava rápidamente.

V5: introspección del LLM

v5_llm_introspect.py

Esta versión agrega una herramienta de introspección respaldada por Amazon Nova 2 Lite en Amazon Bedrock. La herramienta introspect_query toma la pregunta en lenguaje natural del profesor y devuelve valores de filtro recomendados con una justificación que explica cada elección. Interpreta “contenido alineado con TEKS para niños que trabajan en la división en la escuela secundaria” y devuelve filtros recomendados: materia “Matemáticas”, grados 6-8, estándar estatal “TX-TEKS”, tema “división, división”.

Kiro todavía hace la llamada de búsqueda final. Debido a que Introspect se ejecuta en un modelo de su elección, la ingeniería y las pruebas rápidas son confiables. La interpretación se realiza en el lado del servidor, por lo que su contexto se mantiene ágil. La compensación es el costo. Pagas por la llamada al servidor, pero los resultados se mantienen constantes independientemente del modelo que utilice Kiro. Cambie de modelo con /model y compare V4 con V5. Sin introspección, los modelos más débiles producen resultados inconsistentes. Con introspección, los resultados se mantienen estables.

V6: Agente como herramienta

v6/app/v6/main.py

La versión final expone una única herramienta MCP respaldada por un agente de Strands Agents con su propio indicador del sistema y herramientas internas. La interfaz externa es una herramienta con un parámetro: agentic_search_content(pregunta: str). Su agente maneja la búsqueda de taxonomía, la búsqueda, la recuperación de detalles y el formato de respuesta internamente utilizando sus propias herramientas que el LLM del cliente no ve.

Pruebe las 5 consultas y compare el uso del contexto del cliente con las otras versiones. El cliente LLM hace un trabajo mínimo. El comportamiento es consistente independientemente de qué cliente se conecte porque su agente es dueño del razonamiento. El historial de conversaciones persiste en todas las llamadas, por lo que las preguntas de seguimiento funcionan de forma natural. La compensación es el costo y la latencia a cambio de un control directo sobre el comportamiento y la coherencia. Cambie entre modelos con /model en Kiro y observe que los resultados permanecen estables en todos los modelos.

Compensaciones de un vistazo

Cada versión cambia un costo por otro. Esta mesa los coloca uno al lado del otro.

Versión Enfoque Compensación V2 Descripciones ricas Precisión aumentada, definición más grande V3 Esquema + valores predeterminados Precisión aumentada, definición más pequeña V4 Reestructuración + carga diferida Línea de base más simple, ida y vuelta adicional V5 Introspección del lado del servidor Maneja la ambigüedad, usted paga por la inferencia V6 Agente como herramienta Control directo, mayor costo de infraestructura

Después de ejecutar las consultas de prueba en las 6 versiones, observe los patrones. V2 es el camino más rápido hacia mejores resultados sin refactorización. V4 tiene el contexto de referencia más sencillo. V5 maneja consultas ambiguas que otras versiones pasan por alto. V6 le brinda el mayor control al mayor costo de infraestructura. Ninguna versión gana en todas las dimensiones. La elección correcta depende del número de campos, la estabilidad del vocabulario, el presupuesto de latencia y de cuánto necesita un comportamiento consistente entre diferentes clientes.

limpiando

Todos los servidores se ejecutan localmente. Para detenerlos, ejecute scripts/stop_all.sh desde la raíz del repositorio. Consulte el repositorio README adjunto para obtener más detalles.

Conclusión

MCP en sí no es el problema. Es un protocolo clave para soluciones agentes. El problema es el diseño de herramientas. Los enfoques de esta publicación abordan la hinchazón y la confusión a través de la ingeniería de contexto a nivel de herramienta. El tutorial del código demuestra cada enfoque frente al mismo escenario para que pueda observar las compensaciones directamente y decidir qué se adapta a su situación.

El protocolo sigue evolucionando. La hoja de ruta de MCP 2026 aborda la ampliación del transporte, la comunicación de agentes y las funciones para la implementación empresarial.

Para profundizar más, explore los siguientes recursos:

Estrategias de MCP en AWS: cubre la arquitectura más amplia: qué patrones de MCP usar, cuándo conectar varios servidores y cómo estructurar su sistema MCP más allá de una sola herramienta. Servidor AWS MCP: un servidor MCP administrado que brinda a los agentes de codificación de IA acceso a las API de AWS, búsqueda de documentación y habilidades seleccionadas de los agentes a través de una única conexión. Estudie cómo utiliza la carga de habilidades bajo demanda para mantener el contexto optimizado. SDK de Strands Agents: profundice en el enfoque agente de V6. Cree agentes de múltiples turnos con orquestación de herramientas, memoria y comportamiento comprobable. Amazon Bedrock AgentCore: implemente su servidor MCP sin administrar la infraestructura. Incluye alojamiento en tiempo de ejecución, puerta de enlace para el descubrimiento de herramientas multiservidor y memoria persistente entre sesiones.

Para obtener más ejemplos y patrones de código MCP:

Servidores MCP de código abierto para AWS: 56 servidores MCP de código abierto que cubren documentación, infraestructura, IA/ML, datos, herramientas para desarrolladores y más. Elija uno y evalúe las descripciones de sus herramientas en comparación con el marco de confusión y confusión de esta publicación. Muestras de Amazon Bedrock AgentCore: guías de introducción, demostraciones de funciones, ejemplos de casos de uso, planos y talleres para AgentCore. Ejemplos de servidores MCP sin servidor: implementaciones de referencia para alojar servidores MCP en AWS Lambda y Amazon Elastic Container Service (Amazon ECS), incluidos patrones sin estado y con estado, además de agentes de Strands en Lambda. Guía para la codificación de Vibe con servidores AWS MCP: una aplicación de reserva de hotel de muestra que demuestra cómo los asistentes de codificación de IA utilizan los servidores AWS MCP para acelerar el desarrollo con AgentCore.

Sobre los autores

Daniel Wells

Daniel tiene más de 20 años de experiencia en TI en roles de arquitectura y liderazgo, respaldando una amplia variedad de tecnologías. Actualmente trabaja como arquitecto senior de soluciones de AWS, especializado en IA/ML e IA agente, apoyando a las empresas de tecnología educativa que se esfuerzan por marcar la diferencia para los estudiantes y educadores de todo el mundo. Los intereses de Daniel fuera del trabajo incluyen la música, la familia, la salud, la educación y cualquier cosa que le permita expresarse creativamente.