Un agente ve dos herramientas con nombres parecidos y elige la equivocada. Otra llamada usa un identificador inexistente porque el parámetro solo decía “ID”. La aplicación rechaza la solicitud, pero el modelo no sabe si debe corregir el argumento, elegir otra herramienta o pedir más información.
Para escribir una descripción útil, explica cuatro decisiones: qué hace la herramienta, cuándo debe elegirla el agente, qué representan los parámetros y qué resultado devuelve. El schema limita la forma de la llamada. La descripción orienta la elección. Una cosa no sustituye a la otra.
Este trabajo ocurre antes del runtime. El servidor MCP en TypeScript para agentes de código muestra cómo exponer una superficie estrecha. Aquí el foco es escribir la interfaz que el modelo lee antes de enviar su primer argumento.
Resumen práctico
- Nombra la intención que el agente necesita cumplir, no la clase o el endpoint interno.
- Di cuándo usar la herramienta y cuándo elegir otra opción.
- Describe los parámetros ambiguos con unidad, formato, origen y ejemplos breves.
- Mantén separadas las herramientas parecidas por alcance y prueba la elección con casos reales.
¿Qué debe responder una descripción de herramienta?
Una descripción útil responde a la pregunta “¿es esta la herramienta correcta para esta solicitud?”. La guía de function calling de Google Cloud separa la declaración de la función, los parámetros y la ejecución que devuelve el resultado al modelo. Esos campos forman la superficie que usa el agente para proponer una llamada.
Empieza por la intención, no por la implementación. El agente no necesita saber que la función llama a un endpoint REST o que el handler consulta una tabla. Necesita saber que la herramienta busca pedidos existentes por número o cliente, por ejemplo. La capa de ejecución puede cambiar sin obligar al modelo a aprender de nuevo una decisión de negocio.
Una descripción debe dejar claras cuatro cosas:
- Acción: qué pregunta o tarea resuelve la herramienta.
- Momento: qué señales indican que debe llamarse.
- Límite: qué solicitudes pertenecen a otra herramienta o requieren confirmación.
- Resultado: qué evidencia vuelve y qué sigue sin estar confirmado.
Esto no significa convertir la descripción en un manual. La autenticación, los reintentos internos y los nombres de tablas pertenecen al código y a los logs. El texto que recibe el modelo debe contener la información necesaria para decidir, no toda la historia de la implementación.
Cápsula citable: La descripción de una herramienta forma parte de la interfaz del agente. Debe explicar la acción, cuándo usarla, sus límites y el resultado esperado. El schema valida la forma de los argumentos, pero no enseña por sí solo cuándo una herramienta es más adecuada que otra.
¿Cómo nombrar herramientas para diferenciarlas?
El nombre debe representar una operación reconocible con un vocabulario estable y específico. get_data no distingue clientes, pedidos ni facturas. get_order_by_number reduce la ambigüedad porque nombra el objeto y el criterio principal de búsqueda.
Evita nombres basados en detalles que solo existen en el código, como executeQueryV2, customerLookupService o runWorkflow. Pueden tener sentido para quien abrió el repositorio, pero no describen la tarea que aparece en la conversación.
Este ejemplo ilustrativo muestra dos herramientas de lectura. No depende de un proveedor concreto:
const tools = [
{
name: "get_order_by_number",
description:
"Finds an existing order by its exact number and returns observed status, items, and dates.",
},
{
name: "find_orders_for_customer",
description:
"Lists orders associated with a customer when the user does not have an order number.",
},
];Las dos herramientas todavía necesitan schemas de entrada y salida. La diferencia es que cada descripción responde a una intención distinta. Si una herramienta sirve tanto para buscar por número como por nombre, el agente debe adivinar qué regla aplica y la superficie se vuelve más grande de lo necesario.
Cuando una herramienta cambia datos, su nombre también debe hacer visible la acción. prepare_refund y confirm_refund no tienen el mismo riesgo ni la misma condición de uso. La descripción debe reforzar esa diferencia, pero la autorización sigue siendo una decisión del runtime, no una promesa escrita.
¿Cómo describir parámetros sin ocultar la ambigüedad?
Un parámetro no está explicado solo porque tenga un nombre. id, date, status y amount pueden representar muchas cosas. La guía de function calling de Google Cloud recomienda nombres claros y descripciones detalladas para funciones y parámetros. Convierte esa recomendación en preguntas concretas para cada campo.
Para cada parámetro, indica qué identifica, qué formato acepta, dónde puede obtenerlo el usuario y qué unidad o zona horaria se aplica. Si el valor debe venir de un resultado anterior, dilo. Si el agente no debe inventarlo, escribe la regla.
const getOrder = {
name: "get_order_by_number",
description:
"Finds an existing order by its exact number. Use it when the user provides the number; do not use it to discover a customer’s orders.",
parameters: {
type: "object",
properties: {
orderNumber: {
type: "string",
description:
"Number shown on the order receipt, such as ORD-1042. Do not use the customer phone number or internal customer ID.",
},
},
required: ["orderNumber"],
},
};El ejemplo también muestra lo que no debe ocurrir: cambiar un identificador por otro porque ambos son strings. Un schema puede exigir string, pero no puede explicar por sí mismo la diferencia entre ORD-1042, un teléfono y un UUID interno.
Incluye ejemplos solo cuando eliminan una duda real. Un ejemplo ayuda con fechas, códigos compuestos y unidades. Los ejemplos decorativos añaden contexto sin mejorar la decisión. Si una regla necesita un párrafo largo de excepciones, quizá la herramienta cubra dos operaciones.
Cápsula citable: Los parámetros bien descritos llevan una semántica que los tipos JSON no expresan. Indica qué identifica el campo, qué formato y unidad usa y de dónde debe salir el valor. Un schema puede rechazar un tipo incorrecto, pero no distingue por sí solo un número de pedido de otro identificador textual.
¿Cómo decir cuándo el agente no debe llamar a la herramienta?
Una buena descripción incluye límites positivos y negativos. “Buscar pedidos” no explica si la herramienta sirve para crear un pedido, encontrar un cliente o consultar una entrega. El agente debe reconocer la frontera con las herramientas vecinas.
Escribe la regla con lenguaje operativo:
- Usa esta herramienta cuando la solicitud contenga un número de pedido completo.
- Usa la búsqueda por cliente cuando el usuario no conozca ese número.
- No uses esta herramienta para cambiar, cancelar ni reembolsar un pedido.
- No deduzcas el número. Pide el valor que falta.
Estas frases no conceden permisos. Reducen la posibilidad de que el modelo trate una herramienta de lectura como una acción o elija una mutación porque el nombre se parece. La validación de argumentos y autorización sigue perteneciendo al código, como explica el artículo sobre validar tool calls en TypeScript.
La guía de estrategia de tools MCP de AWS advierte que muy pocas herramientas pueden dejar al modelo sin contexto suficiente, mientras que demasiadas pueden confundir la elección y la secuencia. También recomienda pensar en la granularidad y el alcance de cada herramienta.
La guía actual de function calling de Google Cloud recomienda proporcionar solo las herramientas relevantes para la tarea y usa un conjunto activo de 10 a 20 como referencia operativa. No es una ley para todos los agentes. Es una señal de que una descripción perfecta no corrige un catálogo indiscriminado. Filtra la superficie antes de pulir el texto.
¿Cómo revisar una descripción sin prometer que funciona?
No trates la descripción como un texto que solo debe sonar claro. Revísala con casos que representen decisiones competidoras. El objetivo no es demostrar que un modelo siempre elegirá bien. Es descubrir si la interfaz deja sin responder una elección importante.
Una matriz pequeña puede contener:
| Caso | Herramienta esperada | Qué debe dejar claro la descripción |
|---|---|---|
| El usuario da ORD-1042 | búsqueda por número | número exacto y alcance de solo lectura |
| El usuario da solo el cliente | búsqueda por cliente | falta el número y cuál es el criterio |
| El usuario pide cancelar | ninguna herramienta de lectura | la mutación pertenece a otra superficie |
| El usuario no da identificador | pregunta de aclaración | no inventar el valor que falta |
Para cada caso, registra la herramienta elegida, los argumentos generados y la razón esperada. Si la salida necesita confirmación, registra también esa condición. La prueba puede usar un modelo real, un mock o una fixture de llamada, pero la elección esperada debe ser explícita antes de ejecutar.
Después compara los cambios de la definición como código. Cambiar description, name, inputSchema u outputSchema puede cambiar cómo el agente entiende la superficie. Las pruebas de contrato para servidores MCP en TypeScript cubren la frontera del protocolo; esta matriz cubre la decisión que ocurre antes de la llamada.
Una descripción falla cuando el revisor puede explicar cómo funciona la herramienta, pero no por qué el agente debe elegirla en lugar de la herramienta vecina. Quita el nombre interno de la función y pregunta qué tarea concreta sigue visible. Es una prueba sencilla de lectura de la interfaz.
¿Qué debe quedar fuera de la descripción?
No uses la descripción para esconder una política que debería poder verificarse. Frases como “siempre segura”, “nunca falla” o “puede hacer cualquier operación” son promesas vagas. El runtime debe aplicar límites, validar argumentos, controlar permisos y verificar efectos externos.
Tampoco pongas secretos, tokens, stack traces, nombres de tablas sensibles ni detalles de infraestructura. La descripción llega a la capa que ayuda al modelo a elegir. Los logs de ejecución y los diagnósticos del operador tienen otra finalidad y otra política de retención.
Evita repetir el schema en prosa. Si status acepta tres valores, decláralos en el enum y explica solo la diferencia que afecta a la decisión. Si un campo es obligatorio, márcalo en el schema y usa el texto para decir por qué importa o de dónde sale.
En MCP, la definición de una herramienta incluye nombre, descripción y schemas de entrada y salida. La especificación de tools de MCP describe esta superficie y señala que las herramientas están controladas por el modelo, mientras la aplicación debe conservar controles de confianza e interacción humana para acciones sensibles.
Cápsula citable: Las descripciones de herramientas deben orientar la elección, no sustituir los controles de seguridad. No pongas secretos ni prometas que una operación siempre es segura. La autorización, la validación, los límites y la confirmación pertenecen al runtime; el texto explica la intención y los límites que el agente debe considerar.
Lista de comprobación antes de publicar una herramienta
Antes de exponer una herramienta nueva a un agente, revisa:
- El nombre describe la intención y distingue las herramientas vecinas.
- La descripción dice cuándo usarla y cuándo no usarla.
- Cada parámetro explica significado, formato, unidad y origen cuando importa.
- La herramienta deja claro si lee, propone o cambia el estado.
- El schema marca campos obligatorios, enumera valores y rechaza formas inválidas.
- El resultado explica qué se observó, no solo que la llamada terminó.
- La autorización y los límites existen en el runtime.
- Hay al menos un caso de prueba para cada elección competidora.
- La superficie activa contiene solo las herramientas necesarias para la tarea.
Una descripción no vuelve determinista el comportamiento. Mejora el contrato que recibe el modelo y hace revisable la decisión. Si los casos siguen siendo ambiguos después de escribir la regla de uso y la regla de no uso, el siguiente ajuste probablemente sea dividir la herramienta o reducir el catálogo, no añadir más adjetivos.
Cómo se produjo este artículo
Samuel Fajreldines escribió este artículo después de auditar los posts relacionados del repositorio, revisar los resultados actuales y leer la documentación de Google Cloud, AWS y Model Context Protocol el 9 de octubre de 2026. Los ejemplos de TypeScript y JSON son ilustrativos. No se presenta ningún benchmark propio ni una prueba de selección ejecutada como evidencia.
