Guía de diseño de herramientas

Una herramienta MCP no es una llamada a función. Es un contrato. Describe qué puede hacer el sistema, quién puede invocarlo, qué ocurre en el proceso, y qué puede salir mal. Este contrato debe ser legible por máquina, tipado y completo antes de que un agente o un usuario invoque la herramienta.

El estándar Tool Contract

Cada herramienta MCP se describe según un esquema uniforme. El esquema incluye no solo los tipos de entrada y salida, sino también el nivel de riesgo, los permisos, los efectos secundarios, los Audit Events y los posibles casos de error. Solo quien conoce todos los campos puede usar una herramienta de forma segura, ya sea por un agente, una aplicación web o un flujo de trabajo automatizado.

Resumen de los campos:

• Name, identificador único y legible por máquina en formato dominio.verbo
• Description, descripción en lenguaje natural del propósito para agentes y desarrolladores
• Category, clasificación funcional (p. ej. communication, files, billing)
• Risk Level, clasificación según el modelo de riesgo (Low a Forbidden)
• Autonomous Execution, si un agente puede invocar la herramienta sin aprobación humana
• Confirmation, si se requiere confirmación explícita del usuario
• Step-up Auth, si se necesita autenticación adicional y cuándo
• Input Schema, parámetros tipados incluyendo campos opcionales
• Output Schema, valores de retorno tipados incluyendo códigos de estado
• Permissions, qué permisos requiere la herramienta
• Side Effects, todos los cambios de estado fuera del valor de retorno
• Audit Event, qué evento se escribe en el log de auditoría
• Failure Modes, lista completa de todos los códigos de error posibles

El siguiente ejemplo muestra el contrato completo de emails.send_external, una herramienta de riesgo crítico que desencadena comunicación externa:

Cada campo tiene una función en el sistema: permissions controla la Policy Engine, sideEffects informa a la UI de confirmación, failureModes se evalúan en el manejo de errores, auditEvent se escribe en el log de auditoría. El contrato no es solo documentación , es parte del tiempo de ejecución.

El modelo de riesgo

MCP-first clasifica cada herramienta en uno de cinco niveles de riesgo. El nivel determina si un agente puede invocar la herramienta de forma autónoma, si se requiere confirmación y si se exige Step-up Auth. La clasificación no es opcional, es parte del contrato.

Low

Las herramientas de este nivel son de solo lectura o no generan efectos permanentes. Pueden ser ejecutadas autónomamente por agentes, sin confirmación ni Step-up Auth. Son típicas las consultas de listas, las búsquedas y los recursos de ayuda.

Medium

Las herramientas de este nivel generan datos o estados, pero en un scope estrechamente limitado sin efecto externo. Pueden ejecutarse autónomamente cuando el scope y el contexto se derivan inequívocamente del flujo de trabajo. Con contexto poco claro, se recomienda confirmación.

High

Las herramientas de este nivel modifican estados relevantes del sistema o afectan a otros usuarios y recursos externos. Generalmente requieren una confirmación explícita. Un agente no puede ejecutarlas en silencio.

Critical

Las herramientas de este nivel desencadenan comunicación externa, pagos, eliminaciones de datos o cambios de permisos. Siempre requieren confirmación explícita y frecuentemente Step-up Auth. La ejecución autónoma no está permitida.

Forbidden for AI

Las herramientas de este nivel no pueden ser leídas ni ejecutadas por un agente de IA. Están completamente excluidas del descubrimiento de herramientas para agentes. La clasificación es un límite absoluto, no una decisión de política.

Idempotencia

Muchas herramientas se invocan varias veces en flujos de trabajo de agentes, por reintentos, ejecución paralela o planificación defectuosa. MCP-first recomienda diseñar las herramientas como idempotentes donde sea posible: la misma entrada produce el mismo resultado en múltiples invocaciones, sin duplicados ni efectos secundarios no deseados.

La herramienta create_download_link es un buen ejemplo. Si para un archivo con el mismo fileId y el mismo expiresAt ya existe un enlace válido, la herramienta lo devuelve en lugar de crear uno segundo:

create_download_link(fileId: "f_abc123", expiresAt: "2025-12-31T23:59:00Z")

→ Primera invocación: crea nuevo enlace, devuelve linkId + url
→ Segunda invocación (mismos parámetros, enlace aún válido): devuelve el mismo enlace
→ Tercera invocación (enlace caducado): crea nuevo enlace

La idempotencia debe implementarse explícitamente, no surge de forma automática. El campo sideEffects del Tool Contract debe describir el comportamiento en la repetición, para que agentes y clientes puedan planificarlo correctamente.

Dry Run

Las herramientas de riesgo, especialmente las de efectos masivos, deberían ofrecer un modo Dry Run. El Dry Run realiza todas las validaciones y comprobaciones, pero no genera efectos secundarios reales. El resultado muestra qué ocurriría, sin que nada suceda realmente.

emails.bulk_send con dryRun: true ofrece una vista previa completa:

// Request
{
  "tool": "emails.bulk_send",
  "params": {
    "templateId": "tmpl_newsletter_q3",
    "segmentId": "seg_active_customers",
    "dryRun": true
  }
}

// Response
{
  "dryRun": true,
  "recipientCount": 4821,
  "sampleMessages": [
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Liebe Anna, im dritten Quartal haben wir…"
    },
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Lieber Max, im dritten Quartal haben wir…"
    }
  ],
  "warnings": [
    "43 destinatarios no tienen nombre, se usará el fallback 'Hola'.",
    "12 direcciones de correo están marcadas como no entregables y se omitirán."
  ],
  "missingPermissions": [],
  "expectedSideEffects": [
    "Se enviarán 4821 correos electrónicos externos.",
    "Se generarán 4821 Audit Events del tipo email.external.sent.",
    "El estado de la campaña se establecerá en 'sent'."
  ],
  "estimatedDurationMs": 18400
}

Solo tras revisar el resultado del Dry Run y la confirmación explícita del usuario se realiza la invocación real sin dryRun. El agente no puede omitir el Dry Run si la herramienta lo declara como obligatorio.