Colisiones de nombres de herramientas MCP y comportamiento más seguro de los agentes

Un agente no lee un catálogo de herramientas MCP como un ingeniero cuidadoso lee un SDK. Pasa de una instrucción comprimida a una acción probable. Si le das get_user, get_users, user_lookup y admin_get_user, y pretendes separarlas con un párrafo lleno de advertencias, has convertido la autoridad en un juego de adivinanzas.

Las colisiones de nombres de herramientas MCP no son solo identificadores duplicados que hacen que un cliente rechace un catálogo. La colisión más grave es semántica: dos acciones invocables parecen intercambiables, pero una llega a un sistema más amplio, usa una credencial más potente o cambia el estado. He visto equipos llamar a esto un problema de prompting después de que un agente eligiera la acción equivocada. La mayoría de las veces es un problema de interfaz que ellos mismos pusieron en producción.

La solución no es crear una taxonomía gigantesca ni un comité ceremonial de nombres. Dale a cada acción un nombre que diga qué hace, dónde lo hace y hasta dónde llega su autoridad. Después, escribe descripciones que definan el límite que el nombre no puede expresar. Haz visible la ambigüedad en las pruebas, antes de que se convierta en una tarjeta de aprobación, una llamada API inesperada o una revisión complicada de un incidente.

Una colisión es semántica antes que sintáctica

Hay una colisión sintáctica cuando dos servidores MCP publican una herramienta llamada search. Según el cliente, una entrada puede sobrescribir a la otra, el cliente puede exigir un espacio de nombres o el catálogo puede resultar confuso. Debes corregirlo porque el comportamiento puede variar entre clientes.

Una colisión semántica persiste aunque cada identificador sea técnicamente único. Considera estas herramientas:

search_customer
search_customer_records
lookup_customer
customer_admin_search

Las cuatro pueden parecer válidas para un compilador y comprensibles para el equipo que las creó. Para un agente al que se le pide «Busca el registro del cliente Maya Chen y actualiza su dirección», ofrecen señales de enrutamiento débiles. El agente debe inferir qué sistema contiene la información válida, si la acción es de solo lectura, si puede buscar en todo un tenant y si es aceptable usar una credencial administrativa.

Los esquemas de las herramientas no compensan un catálogo impreciso. El modelo puede inspeccionar los nombres de los argumentos, pero unos esquemas parecidos suelen empeorar la ambigüedad. Tanto una búsqueda de directorio de solo lectura como una búsqueda en el CRM de producción pueden aceptar query, limit y organization_id. El hecho de que una devuelva datos y la otra pueda iniciar un enriquecimiento o escribir un evento de auditoría quizá solo aparezca en una descripción que el modelo valore menos que la coincidencia aparente con la tarea.

Trata estos casos como defectos distintos:

• Colisión de identificadores: el cliente no puede presentar dos herramientas de forma coherente.
• Colisión de intención: dos herramientas parecen satisfacer la misma solicitud del usuario.
• Colisión de autoridad: una credencial amplia queda detrás de una herramienta que parece limitada.
• Colisión de entorno: etiquetas parecidas ocultan cuentas, regiones o estados de producción distintos.

Los tres últimos provocan los errores costosos. Un cliente puede rechazar nombres duplicados. No puede avisarte de forma fiable que sync_contact significa «modificar un registro del CRM de producción usando un token para toda la organización», mientras que update_contact significa «escribir en un recurso de prueba local».

Los nombres de las herramientas deben incluir los datos de enrutamiento

Un nombre útil ofrece al agente los datos que necesita para elegir antes de leer una descripción larga. Para acciones que tocan sistemas externos, uso este orden: sistema objetivo, objeto, verbo y, después, alcance cuando el alcance cambia la autoridad o las consecuencias.

crm_contact_update es mejor que update_contact porque identifica el sistema. crm_production_contact_update puede ser aún mejor si el mismo catálogo incluye un entorno sandbox. github_org_member_remove es más claro que manage_member porque indica qué recurso cambia y que el resultado es una eliminación.

No metas todos los detalles de implementación en el nombre. Los agentes no necesitan crm_v3_contacts_patch_with_bearer_auth. Necesitan las diferencias que cambian la elección. El versionado, el transporte y la autenticación suelen pertenecer a la implementación o a la descripción del servidor. La cuenta, el entorno, el efecto secundario y el límite de privilegios suelen pertenecer al nombre.

Un patrón práctico sería este:

<system>_<object>_<verb>[_<scope>]

Ejemplos:

billing_invoice_get
billing_invoice_send_customer
billing_production_refund_create
source_control_repo_issue_list
source_control_org_member_remove
warehouse_inventory_adjust
warehouse_inventory_adjust_dry_run

El patrón no es sagrado. Lo importante es que los nombres vecinos difieran justo en el punto donde cambia su efecto. Si billing_invoice_send_customer y billing_invoice_preview_email aparecen juntos, los verbos y los objetos indican al modelo cuál de las dos contacta realmente a una persona. Si la única diferencia está en un parámetro booleano enterrado en un esquema, el catálogo exige demasiado del enrutamiento.

Evita verbos vagos como process, manage, handle, run, execute, sync y apply, salvo que el propio objeto haga inequívoco el efecto. Son populares porque los equipos de producto los usan como paraguas para varias operaciones. Precisamente por eso son malos nombres de herramientas. Un modelo interpreta un paraguas como permiso para elegir la interpretación más amplia que complete la solicitud.

Las descripciones definen el límite, no el marketing

La especificación de herramientas de Model Context Protocol define una herramienta mediante un nombre, una descripción y un esquema de entrada. Es un contrato de interfaz, no un espacio para texto publicitario. La descripción debe responder a cuatro preguntas operativas: qué acción ocurre, qué objetivo externo la recibe, qué alcance se aplica y qué se niega a hacer la herramienta.

Compara estas dos descripciones:

{
  "name": "crm_contact_update",
  "description": "Updates customer contact information in the CRM.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "contact_id": {"type": "string"},
      "address": {"type": "string"}
    },
    "required": ["contact_id"]
  }
}

{
  "name": "crm_production_contact_update",
  "description": "Changes address, phone, or email fields for one existing contact in the production CRM. This writes immediately. Use crm_contact_search first when the caller supplies a name rather than a contact ID. It cannot create contacts, merge records, or update more than one contact per call.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "contact_id": {
        "type": "string",
        "description": "Stable production CRM contact ID, not an email address or display name."
      },
      "changes": {
        "type": "object",
        "properties": {
          "address": {"type": "string"},
          "phone": {"type": "string"},
          "email": {"type": "string"}
        },
        "minProperties": 1,
        "additionalProperties": false
      }
    },
    "required": ["contact_id", "changes"],
    "additionalProperties": false
  }
}

La segunda descripción da al agente una secuencia, nombra la consecuencia y descarta sustituciones tentadoras. También coloca los detalles que deshacen la ambigüedad cerca de la acción, en lugar de enterrarlos en un manual operativo separado que quizá el agente nunca vea.

Sé directo sobre los efectos secundarios. Escribe «envía el correo inmediatamente», «crea un cargo», «elimina la rama remota» o «escribe en producción». No escribas «persiste los cambios» o «realiza la operación solicitada». Esas frases permiten que un revisor parezca preciso mientras ocultan lo único que necesitan notar el agente y la persona.

Las descripciones de los campos de entrada importan por la misma razón. Si un campo acepta un ID de recurso, indica que un nombre visible no es válido. Si una fecha usa UTC por defecto, dilo. Los esquemas poco estrictos con cadenas opcionales trasladan el significado a la prosa y permiten que el agente improvise argumentos que casualmente se pueden analizar.

El acceso amplio nunca debe parecer una alternativa cómoda

El catálogo más peligroso contiene una herramienta limitada y otra más amplia que parecen resolver la misma solicitud. La herramienta amplia suele existir por buenos motivos: un administrador necesita acceso de emergencia, una migración necesita buscar entre cuentas o un flujo de soporte requiere una excepción. El error es exponerla como una herramienta equivalente con un nombre amigable.

Imagina estas entradas:

support_ticket_get
support_ticket_update
support_admin_query

Un agente quiere contexto para un ticket. support_admin_query puede buscar tickets, usuarios, historial de facturación, notas internas y registros eliminados. Si su descripción empieza por «Consulta la plataforma de soporte», el agente puede seleccionarla porque su cobertura amplia parece útil. La herramienta hizo lo que indicaba su nombre. El diseño falló antes de la llamada.

Cámbiale el nombre y limítala:

support_internal_cross_account_search

Su descripción debe indicar que busca datos internos de soporte entre cuentas, devuelve información que queda fuera del registro del ticket y exige una instrucción explícita que nombre el límite de cuenta. Si el flujo lo permite, exige un ID de cuenta en el esquema en lugar de aceptar solo una consulta de texto libre.

Estoy en contra de la recomendación habitual de exponer una única «herramienta de poder» por flexibilidad. Es popular porque reduce el código del servidor y permite que los operadores experimentados hagan más con menos llamadas. Para un agente autónomo, borra la diferencia entre el trabajo normal y la autoridad excepcional. Crea herramientas separadas para autoridades materialmente distintas. Más entradas en el catálogo cuestan menos que explicar por qué una búsqueda amplia reveló el historial del cliente equivocado.

Esto también se aplica a los entornos. No ofrezcas deploy con un argumento environment cuyo valor predeterminado sea producción. Usa nombres de acción separados cuando un valor equivocado tenga un radio de impacto distinto:

release_staging_deploy
release_production_deploy

Una enumeración en el esquema sigue siendo útil, pero los nombres distintos hacen visible producción durante la selección, la aprobación y la auditoría posterior.

Los parámetros no pueden contener todo el significado de seguridad

Un parámetro cambia una acción después de que el agente haya elegido la herramienta. El nombre y la descripción influyen en la elección misma. Los equipos mezclan estas funciones cuando construyen una herramienta universal con un objeto grande de argumentos.

Este diseño parece compacto:

{
  "name": "repository_action",
  "description": "Performs repository operations.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation": {"enum": ["read_file", "create_branch", "delete_branch", "open_pull_request"]},
      "repository": {"type": "string"},
      "branch": {"type": "string"}
    },
    "required": ["operation", "repository"]
  }
}

También coloca una operación de lectura, una de escritura y una destructiva detrás de la misma etiqueta de enrutamiento. Cuando un agente elige repository_action, ya ha cruzado el límite importante. El revisor ve una aprobación para una acción opaca y general, y debe examinar los argumentos bajo presión.

Sepárala cuando cambie la clase de acción:

repository_file_read
repository_branch_create
repository_branch_delete
repository_pull_request_create

Reserva los parámetros para los datos que varían dentro de una misma acción: ID del repositorio, nombre de rama, ruta del archivo, mensaje de commit o cursor de página. No hagas que un parámetro decida si la llamada lee, escribe, envía, cobra, elimina o llega a producción.

La misma regla se aplica al alcance. report_export con scope: all_accounts convierte una exportación aparentemente inofensiva en una extracción entre cuentas. Si el alcance cambia quién puede verse afectado o qué datos pueden salir, dale su propia herramienta o exige un proceso de autorización más sólido. El agente no debería descubrir la diferencia de autoridad después de rellenar un campo JSON.

La selección de herramientas necesita un conjunto de pruebas de ambigüedad

No puedes inspeccionar un catálogo una vez y declarar que se entiende. Pruébalo con las solicitudes que hacen los usuarios, sobre todo con las incompletas que obligan al agente a inferir el alcance.

Crea un pequeño conjunto de pruebas de selección para cada servidor. Puedes ejecutarlo manualmente con el cliente de agente que admitas o introducir el catálogo y las indicaciones en un sistema de evaluación controlado. Registra la herramienta elegida, los argumentos propuestos y si una persona aceptaría la llamada. No evalúes solo si la tarea terminó correctamente. Una herramienta amplia que devuelve la respuesta correcta sigue siendo una elección incorrecta cuando existía otra más limitada.

Usa solicitudes como estas:

1. «Busca la factura del pedido 1842». La opción esperada debería ser una consulta de facturación de solo lectura, no una búsqueda general del libro mayor.
2. «Actualiza el número de teléfono de Priya». Si falta un ID de contacto estable, el agente debería preguntar cuál de las personas llamadas Priya es la correcta, en lugar de buscar y modificar una coincidencia probable.
3. «Despliega la corrección». El agente debería preguntar por el entorno si el catálogo incluye acciones para staging y producción.
4. «Elimina a Alex del repositorio». El agente debería distinguir entre la pertenencia al repositorio y la pertenencia a la organización.
5. «Envía la factura». El agente debería seleccionar una acción de envío, no un generador de vista previa ni una llamada genérica para actualizar la factura.

Añade formulaciones adversarias que se parezcan a la descripción de la herramienta incorrecta. Si internal_cross_account_search gana cuando una solicitud dice «encuentra todo lo que tenemos sobre este cliente», tu descripción puede ser técnicamente honesta y aun así demasiado atractiva. El comportamiento correcto puede ser elegir una búsqueda limitada o pedir al usuario que identifique una cuenta.

Conserva la transcripción de las pruebas cuando cambies el nombre de las herramientas. Expone regresiones que un validador de esquemas no puede detectar. Un catálogo puede seguir siendo válido mientras un cambio aparentemente inocente convierte billing_invoice_get en get_invoice, que compite con los sistemas de compras, logística y asuntos legales.

Las pantallas de aprobación deben repetir la acción en lenguaje claro

La aprobación humana es el último punto de control, no un permiso para dejar descuidadas las etiquetas de las herramientas. Si la aprobación solo muestra una solicitud de bajo nivel como POST /v1/contacts/123, la persona debe reconstruir la intención a partir de un endpoint y un cuerpo. Es un mal momento para descubrir que el agente eligió el CRM de producción en lugar del entorno sandbox.

Conserva el mismo significado de negocio en todas las capas. El nombre de la herramienta dice crm_production_contact_update. La descripción dice que escribe inmediatamente en un único registro de producción existente. La aprobación debería indicar que el agente quiere cambiar un campo concreto de un contacto de producción, identificar la cuenta objetivo cuando sea posible y mostrar los valores que propone cambiar. El evento de auditoría debe conservar la identidad de la herramienta junto con el canal y el objetivo realmente utilizados.

No hagas que el texto de aprobación resulte más tranquilizador que la acción. «Permitir actualización del CRM» oculta la diferencia entre corregir un número de teléfono y sustituir el correo usado para recuperar una cuenta. Muestra los argumentos importantes, sin incluir secretos. Si un argumento contiene datos sensibles de clientes, presenta suficiente estructura para revisarlo respetando tus reglas de tratamiento de datos.

La autorización por sesión de Sallyport puede establecer que un proceso concreto del agente tiene permiso para actuar durante su ejecución, mientras que las claves por llamada pueden exigir una aprobación separada para credenciales que merecen revisión en cada uso. Esta división funciona mejor cuando las etiquetas de las acciones ofrecen a la persona que aprueba una explicación inmediata y exacta de lo que solicita el agente.

Las credenciales y la identidad de la herramienta resuelven problemas distintos

Mantener las credenciales fuera del agente evita un fallo habitual: el agente no puede copiar una clave API en un registro, archivo fuente, incidencia o respuesta de chat porque nunca recibe el secreto. Ese control no hace que todas las solicitudes sean seguras. El agente aún puede pedir a una puerta de enlace que ejecute la herramienta equivocada con una credencial legítima.

Separa estas preguntas durante el diseño:

• ¿Puede el agente obtener o exponer la credencial?
• ¿Puede solicitar una acción fuera del alcance previsto por el usuario?
• ¿Puede una persona ver qué proceso solicitó la acción?
• ¿Puede un investigador comprobar qué ocurrió después de la ejecución?

El catálogo de herramientas responde a la segunda pregunta. La identidad de sesión y las aprobaciones responden a la tercera. Un registro resistente a manipulaciones responde a la cuarta. Cada capa tiene su función y ninguna sustituye a las demás.

Sallyport guarda las credenciales HTTP y SSH en su bóveda cifrada y ejecuta la acción sin entregar esos secretos al agente. Eso reduce la exposición de credenciales, pero el agente sigue necesitando un catálogo cuyos nombres le impidan pedir una acción más amplia solo porque el nombre parecía suficientemente parecido.

Esta diferencia importa cuando los equipos dicen: «El agente no puede ver el token, así que la herramienta es segura». El token puede estar protegido mientras la acción sigue teniendo demasiado poder. Una credencial de informes de solo lectura y una credencial de reembolsos de producción no deberían aparecer detrás de entradas casi idénticas solo porque ambas están aisladas del modelo.

Los espacios de nombres ayudan a los operadores, pero no justifican acciones vagas

Muchos clientes muestran las herramientas con un prefijo derivado del servidor, como crm.search_contacts o billing.search_contacts. Usa un espacio de nombres cuando el cliente lo admita. Aporta al agente y al operador una pista más para el enrutamiento y reduce los nombres literalmente duplicados.

No dependas de él como única pista. Los clientes pueden acortar etiquetas, combinar catálogos de servidores o mostrar nombres de servidor que significan poco para quien lee una aprobación. Una herramienta llamada search_contacts sigue siendo vaga si un servidor llega a una base de datos de prueba y otro a datos reales de clientes.

Un par mejor sería:

crm_production_contact_search
marketing_audience_contact_search

Estos nombres siguen siendo comprensibles después de que un cliente añada o quite un prefijo. También hacen que los catálogos combinados sean más seguros cuando un agente se conecta con el tiempo a más servidores.

Usa los límites del servidor para agrupar autoridades relacionadas, no para ocultarlas. Un servidor llamado operations que expone reembolsos de facturación, despliegues de producción, exportaciones de clientes y cambios de personal puede resultar cómodo para el equipo responsable. También crea un catálogo saturado, con verbos sin relación y una superficie amplia de credenciales. Divide los servidores cuando los distintos dominios tengan responsables, credenciales, expectativas de aprobación o procesos de revisión diferentes.

Una revisión del catálogo detecta los fallos antes del despliegue

Revisa el catálogo de herramientas junto a una lista de tareas expresadas en lenguaje natural, no de forma aislada. Un nombre que parece obvio a su autor a menudo depende de un contexto que desaparece cuando treinta herramientas de seis servidores aparecen en una misma sesión del agente.

Haz esta breve revisión antes de publicar una acción nueva:

1. Lee solo el nombre. ¿Puede una persona identificar el sistema externo, el objeto, el efecto secundario y el alcance inusual?
2. Colócalo junto a todas las herramientas parecidas. ¿Algún nombre describe un acceso más amplio con un verbo más suave?
3. Imagina que eliminas la descripción. ¿El esquema oculta en un argumento la diferencia entre leer y escribir, sandbox y producción, o un solo registro y todas las cuentas?
4. Plantea una solicitud ambigua. ¿Debería el agente hacer una pregunta aclaratoria y has hecho que eso sea más seguro que adivinar?
5. Comprueba las etiquetas de aprobación y auditoría. ¿Conservan la misma distinción que el nombre de la herramienta?

A menudo, la respuesta correcta es rechazar una solicitud para crear una acción general que sirva para todo. Esa negativa molesta una vez, durante la implementación. Una herramienta ambigua molesta a quienes tendrán que investigar la llamada inesperada más adelante, cuando el contexto ya haya desaparecido.

Mantén el nombre específico, explica el límite con claridad y haz difícil seleccionar por accidente una autoridad amplia. Un agente no necesita más opciones plausibles. Necesita menos formas de confundir un permiso con otro.