Descripciones de herramientas MCP que evitan errores en producción

Una descripción de herramienta MCP puede detener una llamada insegura a producción antes de que empiece o esconder el peligro detrás de un verbo amable. La mayoría de las acciones accidentales en producción no empiezan cuando un agente decide causar daños. Empiezan cuando una descripción vaga hace que una herramienta destructiva parezca intercambiable con una herramienta de inspección.

Escribe la descripción de cada herramienta que cambia el estado como un pequeño contrato operativo: indica el sistema objetivo, el efecto secundario y el requisito de confirmación. Si falta uno de esos datos, la descripción obliga al modelo a deducir un límite de seguridad que tu código debería haber dejado explícito.

He revisado suficientes interfaces de acción como para desconfiar de etiquetas como «gestionar», «sincronizar», «desplegar» y «limpiar». Son cómodas para quien las escribe y costosas para la persona que tiene que explicar por qué una solicitud de prueba terminó en una cuenta activa. Una buena descripción hace que los detalles incómodos sean imposibles de pasar por alto.

Una descripción de herramienta es una advertencia de ejecución, no texto de producto

Las descripciones de herramientas MCP deben decirle al agente y a su operador humano qué ocurrirá si la llamada tiene éxito. No deben vender la capacidad, resumir un subsistema interno ni repetir el nombre de la herramienta en una frase más larga.

El esquema de herramientas del Model Context Protocol incluye una description legible para las personas junto al nombre de la herramienta y inputSchema. La especificación MCP también permite anotaciones como readOnlyHint y destructiveHint. Esas anotaciones ayudan al cliente a presentar las herramientas, pero la especificación indica que los clientes deben tratarlas como sugerencias. No son comprobaciones de permisos. Por eso, la descripción sigue siendo el lugar donde el operador puede leer la consecuencia real antes de que la llamada llegue a tu servicio.

Compara estas dos definiciones:

{
  "name": "delete_backup",
  "description": "Deletes a backup.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "backup_id": { "type": "string" }
    },
    "required": ["backup_id"]
  }
}

{
  "name": "delete_production_backup",
  "description": "Permanently deletes one backup from the Production PostgreSQL backup store. This removes a recovery point and cannot be undone. Ask the user to confirm the backup ID and its timestamp before calling this tool.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "backup_id": {
        "type": "string",
        "description": "Immutable backup ID returned by list_production_backups."
      }
    },
    "required": ["backup_id"],
    "additionalProperties": false
  },
  "annotations": {
    "destructiveHint": true,
    "readOnlyHint": false
  }
}

La segunda definición hace algo más que sonar prudente. Proporciona al agente un objetivo, un resultado irreversible, una forma segura de identificar el objeto y una pausa conversacional obligatoria. También ofrece a quien revisa la llamada información suficiente para rechazarla antes de investigar los detalles de implementación.

No supongas que un verbo contundente resuelve el problema. «Destruir» advierte mejor que «eliminar», pero sigue sin decir qué cuenta se verá afectada, qué clase de datos están en juego ni cómo gestiona la herramienta la confirmación. La descripción debe aportar ese contexto.

Pon el sistema objetivo en la primera frase

La primera frase debe identificar el sistema exacto afectado, incluido el entorno o el límite de la cuenta. Una acción contra «la base de datos» puede dirigirse a un contenedor local desechable, un servicio de pruebas compartido, un tenant de staging o el libro mayor de clientes de producción. Son acciones diferentes, aunque el endpoint de la API coincida.

Usa nombres que el operador reconozca de su trabajo. Di «cuenta de pagos de producción», «clúster de Kubernetes de staging», «tenant de cliente northwind» o «rama de publicación del repositorio mobile-api». Evita los apodos internos, salvo que todos los operadores previstos los conozcan y el nombre también aparezca en los argumentos.

Este orden funciona porque coloca el riesgo antes que la mecánica:

[Target system]. [Action and result]. [Confirmation rule].

Por ejemplo:

Production identity directory. Disables the selected user account and ends active sessions. Ask the user to confirm the username before calling.

El objetivo debe coincidir con el manejador, no con la intención de quien escribió la herramienta. Si la herramienta acepta un argumento environment, una descripción que afirme «Actualiza staging» deja de ser cierta en cuanto alguien pasa production. Divide la operación en herramientas específicas para cada entorno o explica claramente qué permite el argumento.

Normalmente es más fácil operar con una división:

list_staging_feature_flags
set_staging_feature_flag
list_production_feature_flags
request_production_feature_flag_change

El diseño puede parecer repetitivo. La repetición cuesta menos que un selector de herramientas que decida que set_feature_flag parece adecuado y descubra demasiado tarde que un argumento opcional apuntaba a producción.

Los nombres merecen la misma disciplina, pero no pueden contener toda la advertencia. Las listas de herramientas recortan los nombres. A veces los agentes se centran en una descripción al elegir entre nombres parecidos. Las personas consultan ambas cosas cuando están bajo presión. Incluye el objetivo en ambos lugares cuando sea posible y completa la descripción por si el nombre desaparece de la vista.

Hay una excepción: una herramienta que recibe una URI de recurso inmutable cuyo host ya fija el entorno. Incluso en ese caso, indica en la descripción el host o la clase de cuenta. Un UUID no le dice a una persona si identifica un registro de desarrollo o un cliente real.

Expresa el efecto secundario como un resultado completado

Una descripción segura dice al lector cómo queda el mundo después de una ejecución correcta. Esto obliga a quien la escribe a distinguir una observación de un cambio, un cambio reversible de uno permanente y una solicitud de su ejecución.

Compara el verbo vago «gestionar»:

Manages service deployments.

Oculta varios resultados muy diferentes. Una herramienta de despliegue podría crear una publicación, promover una publicación existente, reiniciar instancias, cambiar la distribución del tráfico, revertir el código o limitarse a consultar el estado. Cada operación merece su propia herramienta cuando tiene un modo de fallo o una regla de aprobación distintos.

Usa un resultado explícito:

Creates a deployment request for the Production catalog service. It does not change running instances. A release manager must approve the request in the deployment system.

O bien:

Changes Production catalog traffic so the specified release receives 100 percent of requests. Existing requests may finish on the prior release. Ask the user to confirm the release version before calling.

La diferencia entre crear una solicitud y ejecutarla importa más que la diferencia entre HTTP POST y PATCH. Un objeto de solicitud todavía puede crear trabajo, consumir una cuota o avisar a otras personas, así que describe también ese efecto secundario. Pero no lo presentes como un despliegue activo si solo abre un elemento de aprobación.

Evita los eufemismos. «Retirar» puede significar archivar, desactivar, eliminar o terminar la facturación. «Limpiar» puede significar borrar archivos temporales o eliminar la única copia conservada de una exportación de cliente. Escribe el verbo y el objeto reales: elimina, desactiva, rota, promueve, transfiere, envía, cobra o publica.

En las operaciones con efectos diferidos, indica el retraso. Un cambio de DNS puede propagarse después de que la API responda. Eliminar a un usuario puede impedir futuros accesos y conservar los registros de auditoría. Rotar una credencial puede invalidar a los clientes que todavía usan el secreto anterior. El agente necesita este contexto para decidir si debe inspeccionar antes los sistemas dependientes.

Las descripciones también deben mencionar el alcance relevante cuando una sola llamada afecta a muchos objetos. «Elimina el registro seleccionado» no es lo mismo que «Elimina todos los registros que coincidan con la consulta proporcionada». Un endpoint por lotes oculto detrás de un verbo singular causa problemas previsibles.

El lenguaje de confirmación debe describir un control real

Una frase de confirmación solo sirve si la implementación y el proceso operativo la respetan. Escribir «requiere confirmación» en una herramienta cuyo manejador se ejecuta de inmediato es puro teatro, y tarde o temprano los agentes lo dejarán en evidencia.

Hay tres patrones distintos, y las descripciones deben indicar cuál usas realmente.

1. El agente pregunta al usuario en su propia conversación y después llama a la acción. Esto depende de que el agente siga la descripción y no detiene a un cliente modificado o descuidado.
2. La herramienta crea una solicitud para que la apruebe otra persona o sistema. La llamada tiene un efecto secundario, pero el cambio de producción descrito espera a la aprobación.
3. Una puerta de enlace de ejecución pausa la acción y exige aprobación humana antes de enviar credenciales o contactar con el sistema objetivo.

No reduzcas esos patrones a «confirmación requerida». Ofrecen niveles de protección y evidencias de auditoría diferentes.

Usa verbos que identifiquen al actor y el momento:

Before calling, ask the user to confirm the repository name and release tag.

Calling this tool submits a change request. The deployment system requires a release manager to approve it before any production release begins.

This action gateway asks a human to approve every call before it sends the request to the Production payments API.

La última formulación describe un límite aplicado por el sistema. La primera describe una instrucción para el agente. Ambas pueden ser apropiadas, pero no son equivalentes.

Nunca le digas al agente que pida una confirmación vaga. Indica qué datos necesita la persona para aprobar. En una eliminación pueden ser el nombre del recurso, la cuenta y el estado de retención. En una transferencia pueden ser el origen, el destino, el importe y la divisa. En una publicación pueden ser el servicio, la versión y el alcance del tráfico. La descripción no debe exigir un ritual, sino pedir los datos que permiten detectar un objetivo equivocado.

Una regla de confirmación también necesita un alcance. «Obtén aprobación antes de los cambios de producción» es débil si una sesión puede ejecutar diez llamadas después de una sola aprobación. Si el control real aprueba un proceso durante toda su vida, explícalo en la documentación del producto y no afirmes que cada llamada recibe una pausa individual.

Las afirmaciones de solo lectura fallan cuando los manejadores hacen trabajo oculto

Llama a una herramienta de solo lectura únicamente cuando su manejador no cambie intencionadamente el sistema objetivo. La palabra describe el comportamiento, no el método HTTP, el nombre del permiso de la base de datos ni las expectativas de quien la escribió.

Una solicitud GET puede actualizar una sesión, modificar un campo de último acceso, generar una exportación, iniciar un trabajo de informes o activar una carga de caché con un coste relevante. Una solicitud POST puede ser inocua si evalúa una simulación y no persiste nada. Inspecciona el manejador y sus llamadas posteriores antes de elegir la etiqueta.

La anotación MCP readOnlyHint resulta útil para que un cliente reduzca la fricción al presentar herramientas de inspección. Sigue siendo una sugerencia, por lo que el servidor debe aplicar su propio límite. Más importante aún, la descripción debe indicar cualquier excepción que pueda sorprender al operador.

Esta descripción es engañosa:

Read-only tool for checking invoice status.

Falla si el endpoint crea un evento de visualización del documento, actualiza un token de terceros o inicia un cálculo remoto. Una formulación más honesta sería:

Retrieves the current status of one Production invoice. It does not edit the invoice or charge the customer. The billing provider records this request in its access log.

Un registro de acceso suele ser aceptable en una acción de inspección. Adquiere importancia si el objetivo tiene reglas de cumplimiento, un coste por consulta o un flujo de trabajo que reacciona a las lecturas. Indica esos efectos sin convertir cada descripción en un aviso legal.

Siempre que sea posible, separa las simulaciones de la ejecución. Una herramienta deploy con un booleano dry_run crea dos perfiles de seguridad dentro de una misma definición. Los agentes pueden omitir un valor predeterminado, interpretar mal si el servidor lo respeta o reutilizar una carga sin modificarla. plan_production_deployment y execute_production_deployment hacen visible la diferencia en la selección de herramientas, los registros y las revisiones.

La misma regla se aplica a las herramientas de validación. «Validar la configuración» parece seguro, pero algunos proveedores asignan un recurso o contactan con una dependencia activa durante la validación. Si lo hace, descríbelo como una acción y aplica la regla de confirmación correspondiente.

Una herramienta demasiado amplia provoca errores de aprobación

Las herramientas deben agrupar operaciones con una consecuencia y un límite de aprobación comunes, no operaciones reunidas por comodidad de un único cliente de API. Una herramienta general de administración convierte las descripciones en un catálogo de excepciones que ni un modelo ni una persona leerán de forma fiable.

Este es el patrón que conviene evitar:

{
  "name": "admin",
  "description": "Administer users, deployments, secrets, and configuration across environments.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation": { "type": "string" },
      "environment": { "type": "string" },
      "payload": { "type": "object" }
    },
    "required": ["operation", "environment", "payload"]
  }
}

Esta definición destruye la unidad útil de revisión. Quien revisa no puede saber por la tarjeta de la herramienta si la llamada consultará el estado, rotará credenciales o eliminará un usuario. El texto operation traslada la semántica importante a un argumento tardío que es fácil pasar por alto.

Divide por intención y riesgo:

get_production_deployment_status
plan_production_deployment
submit_production_deployment_request
rotate_production_service_credential
create_production_user_access_request

No necesitas una herramienta para cada endpoint. Necesitas herramientas separadas cuando cambian el objetivo, el efecto secundario o la confirmación. Una herramienta por lotes puede seguir siendo una herramienta por lotes si siempre actúa sobre el mismo tipo de recurso acotado y siempre requiere la misma aprobación. Su descripción debe indicar que puede afectar a varios objetos y mostrar cómo limita la selección quien realiza la llamada.

Los argumentos también necesitan descripciones. La descripción de la herramienta explica qué hace la operación; las descripciones de los argumentos limitan las decisiones peligrosas. Usa enumeraciones para los entornos y los tipos de acción cuando sea posible. Rechaza los valores no reconocidos en el servidor. No pongas «production» en una cadena libre y confíes en que la descripción te protegerá.

Una herramienta acotada también produce mejores registros de auditoría. Cuando el diario dice rotate_production_service_credential, quien investiga entiende la clase de acción antes de abrir los argumentos. Cuando dice admin, debe reconstruir la intención a partir de una carga.

Escribe la descripción antes que el manejador

Redactar el contrato operativo antes de implementar deja al descubierto los requisitos vagos mientras todavía resulta barato cambiar la interfaz. Si no puedes escribir una frase sencilla sobre el resultado completado, todavía no tienes un límite de herramienta estable.

Usa esta secuencia de revisión para cada herramienta de acción:

1. Escribe el objetivo tal como lo identificaría un operador, incluido el entorno, la cuenta o el tenant.
2. Escribe el resultado completado con un verbo literal e indica si el cambio puede revertirse.
3. Indica quién aprueba, en qué momento se produce la aprobación y si se aplica a cada llamada o a cada sesión.
4. Compara la frase con el comportamiento del manejador, los valores predeterminados, los reintentos y las APIs posteriores.
5. Añade descripciones de los argumentos para los identificadores, los controles de alcance y cualquier valor que cambie el objetivo.

El cuarto punto detecta fallos que una documentación pulida puede ocultar. Los reintentos pueden hacer que un cobro o un mensaje ocurra dos veces si la solicitud posterior no usa un mecanismo de idempotencia. Los valores predeterminados pueden convertir un environment omitido en producción. Un manejador puede resolver un nombre sencillo en varios recursos. La descripción no puede reparar esos errores de implementación, pero escribirla obliga a sacarlos a la luz.

Una prueba interna útil consiste en quitar el nombre de la herramienta y mostrar a otro ingeniero solo la descripción y el esquema de entrada. Pídele que prediga qué ocurrirá después de una llamada correcta y qué aprobación espera. Si su respuesta no coincide con el manejador, corrige el contrato o el código.

Prueba también con solicitudes en lenguaje cotidiano. «Borra los datos antiguos», «haz que la nueva versión esté activa» y «arregla la cuenta de Jordan» son exactamente el tipo de peticiones que hacen que una herramienta amplia parezca tentadora. Un agente seguro debe usar primero una herramienta de inspección, pedir el identificador que falta o presentar la acción concreta para su aprobación. Si puede saltar de esa petición a la eliminación en producción, el fallo empieza en el diseño de la interfaz mucho antes de que entre en juego el comportamiento del modelo.

Los mensajes de error y los resultados deben conservar el límite de seguridad

Una descripción cuidadosa pierde buena parte de su valor cuando el resultado de la herramienta oculta el objetivo ejecutado o cuando un error invita al agente a probar una acción más amplia. Devuelve pruebas suficientes para que el agente y el operador verifiquen qué ocurrió.

En un cambio de estado correcto, devuelve el identificador canónico del objetivo, la acción realizada y el estado resultante. No respondas únicamente con ok.

{
  "status": "completed",
  "target": {
    "environment": "production",
    "service": "catalog",
    "release": "2025.06.14-3"
  },
  "action": "traffic_promoted",
  "traffic_percent": 100,
  "request_id": "relreq_8a2f"
}

En una pausa de aprobación, indica que nada llegó al objetivo. Esta distinción evita que un agente intente compensar una llamada que simplemente está esperando a una persona.

{
  "status": "approval_required",
  "action": "rotate_production_service_credential",
  "target": "production/catalog-api",
  "executed": false,
  "approval_scope": "this call"
}

Los errores requieren el mismo cuidado. «Prohibido» puede ser técnicamente exacto y no servir para operar. Indica si se rechazó el objetivo, si el entorno no era válido, si faltaba la aprobación o si la solicitud falló después de llegar al sistema remoto. Nunca expongas un secreto en esa explicación ni aconsejes al agente repetir a ciegas una solicitud que cambia el estado.

La idempotencia debe aparecer en el resultado de las acciones relevantes externamente. Si se produce un tiempo de espera de red después de que un servicio remoto haya aceptado una transferencia o creado una publicación, el agente debe consultar el estado de la solicitud mediante un identificador estable. La ruta de reintento no debe adivinar. Las descripciones no pueden expresar todas las reglas de reintento, pero una herramienta que realiza llamadas irreversibles debe tener una herramienta de estado complementaria y una estructura de resultados que permita recuperarse.

Las descripciones necesitan controles que las respalden

El lenguaje claro reduce las malas selecciones, pero no puede detener un proceso que ya posee un token de producción sin restricciones. Coloca las credenciales y la acción de red final detrás de un límite capaz de rechazar, aprobar y registrar la llamada.

Sallyport utiliza esa configuración con agentes conectados a MCP: el agente usa el shim incluido sp mcp, mientras la aplicación conserva las credenciales API y SSH en su almacén cifrado y ejecuta las acciones aprobadas por sí misma. Su autorización por sesión y las aprobaciones opcionales por clave para cada llamada convierten la confirmación escrita en un comportamiento aplicable, no en una petición de buena conducta.

Eso no justifica un diseño deficiente de las herramientas. La puerta de enlace ve la llamada que recibe. Tu esquema de herramientas sigue determinando si la llamada dice «elimina esta copia de seguridad de producción» o esconde la eliminación detrás de una operación genérica admin. Aplica la validación de argumentos en el manejador, limita las credenciales al objetivo previsto cuando el sistema remoto lo permita y conserva un registro de auditoría que identifique el proceso y la acción.

Las directrices de autorización del Model Context Protocol señalan lo mismo en otra capa: la autorización pertenece a un flujo de protocolo con comprobaciones explícitas, no a una instrucción del modelo. Trata las descripciones como un contrato legible para las personas. Trata la autorización del servidor, la custodia de credenciales y la aprobación como los controles que hacen que ese contrato sea cierto.

Elige la herramienta más peligrosa que expongas hoy y reescribe su descripción sin mirar el nombre. Si no puedes indicar el objetivo de producción, el efecto secundario completado y el alcance de aprobación en dos o tres frases directas, todavía no ofrezcas esa herramienta a un agente autónomo.