Una herramienta MCP resulta útil cuando el agente entiende cuándo, por qué y cómo debe llamarla. La descripción hace gran parte de ese trabajo.
Si la descripción es vaga, el agente adivina. Si el esquema de entrada no es claro, envía argumentos confusos. Si dos herramientas se solapan demasiado, puede elegir la equivocada.
El código de la herramienta puede funcionar perfectamente y aun así el agente puede usarla mal porque el modelo no entiende su propósito.
La interfaz que no se ve
Cuando pensamos en servidores MCP, solemos centrarnos en la implementación:
- conectar los datos;
- exponer herramientas;
- devolver resultados;
- probar el transporte.
La descripción de la herramienta es la interfaz entre tu servidor y el modelo. Las personas leen documentación; los agentes leen esas descripciones.
Si la descripción es débil, al agente le cuesta más usar tu servidor MCP de forma fiable.
Una descripción insuficiente
Imagina esta herramienta:
get_projects
Con esta descripción:
Gets projects.
«Obtiene proyectos» es cierto, pero no ayuda demasiado.
El agente no sabe:
- qué tipo de proyectos devuelve;
- si incluye los archivados;
- si puede filtrar;
- qué campos recibe;
- cuándo usar esta herramienta en vez de otra.
La descripción no contiene suficiente información para orientar su comportamiento.
Una descripción más útil
Una versión mejor:
Returns projects from Orlando Ascanio's personal hub. Use this when the user asks what Orlando has built, asks for projects by technology or tag, or needs examples of his work. Supports optional tag, status, and locale filters.
Explica que devuelve proyectos de mi sitio personal y que debe usarse cuando alguien pregunta qué he construido, busca proyectos por tecnología o necesita ejemplos de mi trabajo. También indica que admite filtros opcionales por etiqueta, estado e idioma.
El agente sabe de quién son los proyectos, cuándo llamar a la herramienta, con qué intenciones del usuario encaja y qué filtros existen.
Eso le sirve mucho más que «Obtiene proyectos».
Cuatro preguntas que debe responder la descripción
Una buena descripción de una herramienta MCP debería responder:
- ¿Qué devuelve o hace esta herramienta?
- ¿Cuándo debe usarla el agente?
- ¿Qué entradas importan?
- ¿Qué no debería dar por hecho el agente?
Por ejemplo:
Returns a single product from Orlando's personal hub by slug. Use after get_products when the user asks for more detail about a specific product. Requires an exact product slug. Returns not found if the slug does not exist.
La descripción indica que devuelve un producto concreto por su slug, que debe usarse después de get_products y que requiere un slug exacto. También explica qué ocurre si no existe.
Eso ayuda a ordenar las llamadas. Si el agente no conoce el slug, tiene una razón clara para llamar primero a get_products.
Los esquemas de entrada también explican la herramienta
El esquema orienta al modelo además de validar los argumentos.
Esto es vago:
query: string
Esto es más claro:
topic: optional string used to filter notes by title, category, excerpt, or content. Examples: "AI agents", "Chrome extensions", "product thinking".
El campo topic se describe como un texto opcional para filtrar notas por título, categoría, resumen o contenido, con ejemplos de temas.
El modelo necesita saber qué clase de texto corresponde al campo: una consulta de búsqueda, un valor exacto de una enumeración, un slug o un tema escrito en lenguaje natural.
Esos detalles cambian el argumento que enviará.
Usa enumeraciones cuando las opciones sean finitas
Si un campo solo acepta valores conocidos, indícalo de forma explícita.
Por ejemplo:
status: "active" | "archive"
Es más preciso que:
status: string
Las enumeraciones evitan que el modelo invente valores como:
published;done;live;completed.
Son palabras razonables, pero no son entradas válidas para ese campo.
Quitar libertad innecesaria del esquema mejora la fiabilidad del agente.
Separa las herramientas cuando las intenciones sean distintas
Un error habitual es construir una herramienta enorme que haga de todo.
Por ejemplo:
search_everything
Podría buscar proyectos, productos, notas, información del perfil, estados, enlaces y contenido.
Parece cómodo, pero introduce ambigüedad.
A veces una búsqueda general es útil. Si las intenciones habituales del usuario son distintas, suele ser más claro ofrecer herramientas separadas:
get_projects
get_project
get_products
get_product
get_notes
get_note
get_orlando_bio
Cada una tiene un propósito más concreto, el modelo decide con más facilidad y el resultado es más sencillo de interpretar.
Evita nombres que se solapen
Los nombres que se pisan crean incertidumbre.
Por ejemplo:
get_work
get_projects
get_products
get_all_items
Si las cuatro herramientas devuelven cosas parecidas, el agente puede elegir de forma inconsistente.
Una separación más clara:
get_projectspara casos de estudio;get_productspara productos publicados;get_notespara artículos;get_orlando_biopara información del perfil.
Los nombres deberían reflejar el modelo de contenido.
Incluye los límites en la descripción
Las descripciones también deben explicar qué queda fuera.
Para el servidor MCP de un sitio personal, un límite útil sería:
This tool only returns public content from the site. It does not access private drafts, analytics, billing data, or admin records.
Es decir: solo devuelve contenido público del sitio. No accede a borradores privados, analíticas, datos de facturación ni registros de administración.
Así el agente evita dar a entender que tiene acceso a información que no puede consultar. También ayuda al usuario a entender los límites de acceso.
Devuelve resúmenes cuando sea posible
La descripción orienta la llamada. El resultado orienta la respuesta.
Por eso me gusta incluir ai_summary en las respuestas de la API y resúmenes de texto en los resultados MCP.
Los agentes pueden interpretar JSON, pero una explicación breve reduce la ambigüedad.
Por ejemplo:
Found 5 notes about AI engineering. These notes cover prompt engineering, agent architecture, and production reliability.
El resumen indica que se encontraron cinco notas de ingeniería de IA y enumera sus temas: prompts, arquitectura de agentes y fiabilidad en producción.
Eso le da contexto al modelo antes de elaborar la respuesta.
Una buena herramienta MCP debería ser fácil de elegir
Una herramienta MCP bien definida debería resultar evidente para el modelo.
El usuario pregunta:
What has Orlando shipped?
El agente ve:
get_products - Returns Orlando's shipped products...
La pregunta es qué productos he publicado y la descripción de get_products dice que devuelve mis productos publicados. La elección debería ser fácil.
Si el agente necesita razonar demasiado para elegir, probablemente conviene mejorar los nombres, aclarar las descripciones o reducir las responsabilidades.
La regla que sigo
Cada herramienta MCP debería tener:
- un nombre concreto;
- una descripción clara;
- una responsabilidad limitada;
- entradas tipadas;
- enumeraciones finitas cuando sea posible;
- límites explícitos;
- una estructura de resultado previsible.
La descripción permite que el agente descubra para qué sirve la implementación.
Un pequeño voto de confianza
¿Valió la pena leer esta nota?