{
  "contract": {
    "name": "mailagents-agent-compatibility",
    "version": "2026-03-17",
    "stability": "beta",
    "changelogPath": "/CHANGELOG.md"
  },
  "discovery": {
    "runtimeMetadataPath": "/v2/meta/runtime",
    "compatibilityPath": "/v2/meta/compatibility",
    "compatibilitySchemaPath": "/v2/meta/compatibility/schema",
    "adminMcpPath": "/admin/mcp",
    "mcpInitializeEmbedsRuntimeMetadata": true,
    "toolsListScopeFiltered": true
  },
  "evolution": {
    "versioningPolicy": {
      "patchSafeChanges": [
        "new optional metadata fields",
        "new non-breaking documentation fields",
        "new tool descriptions without schema changes"
      ],
      "compatibilityVersionBumpTriggers": [
        "removing a stable top-level contract field",
        "renaming a stable MCP error code",
        "changing the meaning of a stable tool annotation field",
        "removing a listed idempotent operation name"
      ]
    },
    "deprecationPolicy": {
      "announcedVia": [
        "compatibility contract",
        "CHANGELOG.md"
      ],
      "minimumNotice": "one compatibility version",
      "removalRule": "stable fields or stable error codes should not be removed without first appearing in deprecatedFields"
    },
    "deprecatedFields": []
  },
  "guarantees": {
    "stableRuntimeFields": [
      "server",
      "api",
      "mcp",
      "workflows",
      "idempotency",
      "routes",
      "delivery"
    ],
    "stableToolAnnotations": [
      "riskLevel",
      "sideEffecting",
      "humanReviewRequired",
      "composite",
      "supportsPartialAuthorization",
      "sendAdditionalScopes",
      "category",
      "recommendedForMailboxAgents"
    ],
    "stableErrorCodes": [
      "route_disabled",
      "auth_unauthorized",
      "auth_missing_scope",
      "access_tenant_denied",
      "access_agent_denied",
      "access_mailbox_denied",
      "invalid_arguments",
      "insufficient_credits",
      "daily_quota_exceeded",
      "hourly_quota_exceeded",
      "resource_agent_not_found",
      "resource_mailbox_not_found",
      "resource_message_not_found",
      "resource_thread_not_found",
      "resource_draft_not_found",
      "resource_outbound_job_not_found",
      "resource_suppression_not_found",
      "idempotency_conflict",
      "idempotency_in_progress",
      "tool_internal_error"
    ],
    "idempotentOperations": [
      "draft_send",
      "message_replay",
      "reply_to_inbound_email(send=true)",
      "operator_manual_send(send=true)"
    ]
  },
  "mcp": {
    "protocolVersion": "2025-03-26",
    "methods": [
      "initialize",
      "tools/list",
      "tools/call"
    ],
    "tools": [
      {
        "name": "create_agent",
        "requiredScopes": [
          "agent:create"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "provisioning",
        "recommendedForMailboxAgents": false,
        "riskLevel": "write",
        "sideEffecting": true,
        "humanReviewRequired": false
      },
      {
        "name": "bind_mailbox",
        "requiredScopes": [
          "agent:bind"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "provisioning",
        "recommendedForMailboxAgents": false,
        "riskLevel": "write",
        "sideEffecting": true,
        "humanReviewRequired": false
      },
      {
        "name": "upsert_agent_policy",
        "requiredScopes": [
          "agent:update"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "policy",
        "recommendedForMailboxAgents": false,
        "riskLevel": "privileged",
        "sideEffecting": true,
        "humanReviewRequired": true
      },
      {
        "name": "reply_to_inbound_email",
        "requiredScopes": [
          "mail:read",
          "draft:create"
        ],
        "sendAdditionalScopes": [
          "draft:send"
        ],
        "composite": true,
        "supportsPartialAuthorization": true,
        "category": "mail_reply",
        "recommendedForMailboxAgents": false,
        "riskLevel": "high_risk",
        "sideEffecting": true,
        "humanReviewRequired": true
      },
      {
        "name": "operator_manual_send",
        "requiredScopes": [
          "draft:create"
        ],
        "sendAdditionalScopes": [
          "draft:send"
        ],
        "composite": true,
        "supportsPartialAuthorization": true,
        "category": "mail_send",
        "recommendedForMailboxAgents": false,
        "riskLevel": "high_risk",
        "sideEffecting": true,
        "humanReviewRequired": true
      },
      {
        "name": "list_agent_tasks",
        "requiredScopes": [
          "task:read"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "task_read",
        "recommendedForMailboxAgents": false,
        "riskLevel": "read",
        "sideEffecting": false,
        "humanReviewRequired": false
      },
      {
        "name": "list_messages",
        "requiredScopes": [
          "mail:read"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "mail_read",
        "recommendedForMailboxAgents": true,
        "riskLevel": "read",
        "sideEffecting": false,
        "humanReviewRequired": false
      },
      {
        "name": "get_message",
        "requiredScopes": [
          "mail:read"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "mail_read",
        "recommendedForMailboxAgents": false,
        "riskLevel": "read",
        "sideEffecting": false,
        "humanReviewRequired": false
      },
      {
        "name": "get_message_content",
        "requiredScopes": [
          "mail:read"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "mail_read",
        "recommendedForMailboxAgents": false,
        "riskLevel": "read",
        "sideEffecting": false,
        "humanReviewRequired": false
      },
      {
        "name": "get_thread",
        "requiredScopes": [
          "mail:read"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "thread_read",
        "recommendedForMailboxAgents": false,
        "riskLevel": "read",
        "sideEffecting": false,
        "humanReviewRequired": false
      },
      {
        "name": "create_draft",
        "requiredScopes": [
          "draft:create"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "draft_control",
        "recommendedForMailboxAgents": false,
        "riskLevel": "write",
        "sideEffecting": true,
        "humanReviewRequired": false
      },
      {
        "name": "get_draft",
        "requiredScopes": [
          "draft:read"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "draft_control",
        "recommendedForMailboxAgents": false,
        "riskLevel": "read",
        "sideEffecting": false,
        "humanReviewRequired": false
      },
      {
        "name": "send_draft",
        "requiredScopes": [
          "draft:send"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "draft_control",
        "recommendedForMailboxAgents": false,
        "riskLevel": "high_risk",
        "sideEffecting": true,
        "humanReviewRequired": true
      },
      {
        "name": "cancel_draft",
        "requiredScopes": [
          "draft:create"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "draft_control",
        "recommendedForMailboxAgents": true,
        "riskLevel": "write",
        "sideEffecting": true,
        "humanReviewRequired": false
      },
      {
        "name": "send_email",
        "requiredScopes": [
          "draft:create",
          "draft:send"
        ],
        "sendAdditionalScopes": [],
        "composite": true,
        "supportsPartialAuthorization": false,
        "category": "mail_send",
        "recommendedForMailboxAgents": true,
        "riskLevel": "high_risk",
        "sideEffecting": true,
        "humanReviewRequired": true
      },
      {
        "name": "reply_to_message",
        "requiredScopes": [
          "mail:read",
          "draft:create",
          "draft:send"
        ],
        "sendAdditionalScopes": [],
        "composite": true,
        "supportsPartialAuthorization": false,
        "category": "mail_reply",
        "recommendedForMailboxAgents": true,
        "riskLevel": "high_risk",
        "sideEffecting": true,
        "humanReviewRequired": true
      },
      {
        "name": "replay_message",
        "requiredScopes": [
          "mail:replay"
        ],
        "sendAdditionalScopes": [],
        "composite": false,
        "supportsPartialAuthorization": false,
        "category": "recovery",
        "recommendedForMailboxAgents": false,
        "riskLevel": "high_risk",
        "sideEffecting": true,
        "humanReviewRequired": true
      }
    ]
  },
  "workflows": [
    {
      "name": "reply_to_inbound_email",
      "compositeTool": "reply_to_inbound_email",
      "sideEffects": [
        "create_draft",
        "send_draft_when_send_true"
      ]
    },
    {
      "name": "operator_manual_send",
      "compositeTool": "operator_manual_send",
      "sideEffects": [
        "create_draft",
        "send_draft"
      ]
    },
    {
      "name": "send_email",
      "compositeTool": "send_email",
      "sideEffects": [
        "create_draft",
        "send_draft"
      ]
    },
    {
      "name": "reply_to_message",
      "compositeTool": "reply_to_message",
      "sideEffects": [
        "create_draft",
        "send_draft"
      ]
    },
    {
      "name": "replay_and_recover_message",
      "compositeTool": null,
      "sideEffects": [
        "replay_message"
      ]
    }
  ],
  "admin": {
    "mcp": {
      "path": "/admin/mcp",
      "auth": {
        "type": "header",
        "header": "x-admin-secret"
      },
      "methods": [
        "initialize",
        "tools/list",
        "tools/call"
      ],
      "workflows": [
        {
          "name": "bootstrap_mailbox_agent",
          "description": "Mint a least-privilege mailbox bearer token, then hand the agent back to the normal mailbox workflow surface.",
          "goal": "Bootstrap a mailbox-scoped agent with the narrowest viable token and a clear next-step tool surface.",
          "compositeTool": "bootstrap_mailbox_agent_token",
          "categories": [
            "token_admin",
            "registry_admin"
          ],
          "recommendedToolSequence": [
            "get_mailbox",
            "get_agent",
            "bootstrap_mailbox_agent_token"
          ],
          "sideEffects": [
            "create_access_token"
          ],
          "stopConditions": [
            "mailbox identity or tenant ownership is unclear",
            "the requested token scope exceeds the mailbox workflow need",
            "the intended agent binding is ambiguous"
          ]
        },
        {
          "name": "review_tenant_outbound_access",
          "description": "Gather tenant billing and policy context before deciding whether outbound delivery should be approved, reset, or suspended.",
          "goal": "Support operator review of external-send eligibility with enough billing and policy context to make a safe decision.",
          "compositeTool": "get_tenant_review_context",
          "categories": [
            "policy_admin",
            "registry_admin"
          ],
          "recommendedToolSequence": [
            "get_tenant_send_policy",
            "list_mailboxes",
            "get_tenant_review_context",
            "apply_tenant_send_policy_review"
          ],
          "sideEffects": [
            "apply_tenant_send_policy_review",
            "upsert_tenant_send_policy"
          ],
          "stopConditions": [
            "the tenant identity or mailbox inventory is incomplete",
            "payment state is still ambiguous or disputed",
            "the review outcome would broaden outbound access without operator approval"
          ]
        },
        {
          "name": "forensic_delivery_inspection",
          "description": "Correlate message, draft, queue, delivery-event, and suppression state for a suspected delivery issue.",
          "goal": "Give an operator or forensic agent a single workflow for tracing delivery state before taking remediation steps.",
          "compositeTool": "inspect_delivery_case",
          "categories": [
            "debug",
            "suppression"
          ],
          "recommendedToolSequence": [
            "get_debug_message",
            "get_debug_draft",
            "get_debug_outbound_job",
            "get_suppression",
            "inspect_delivery_case"
          ],
          "sideEffects": [
            "add_suppression"
          ],
          "stopConditions": [
            "the lookup target does not uniquely identify the delivery case",
            "delivery evidence is incomplete and requires provider-side logs",
            "adding a suppression would materially change customer delivery behavior without human review"
          ]
        }
      ]
    }
  },
  "errors": [
    {
      "code": "route_disabled",
      "category": "availability",
      "retryable": false,
      "description": "The requested MCP surface is disabled in the current environment."
    },
    {
      "code": "auth_unauthorized",
      "category": "auth",
      "retryable": false,
      "description": "The request is missing a valid bearer token or the token could not be verified."
    },
    {
      "code": "auth_missing_scope",
      "category": "auth",
      "retryable": false,
      "description": "The bearer token is valid but lacks one or more required scopes."
    },
    {
      "code": "access_tenant_denied",
      "category": "access",
      "retryable": false,
      "description": "The token is not allowed to act on the requested tenant."
    },
    {
      "code": "access_agent_denied",
      "category": "access",
      "retryable": false,
      "description": "The token is not allowed to act on the requested agent."
    },
    {
      "code": "access_mailbox_denied",
      "category": "access",
      "retryable": false,
      "description": "The token is not allowed to act on the requested mailbox."
    },
    {
      "code": "invalid_arguments",
      "category": "input",
      "retryable": false,
      "description": "The tool call arguments failed validation or were malformed."
    },
    {
      "code": "insufficient_credits",
      "category": "billing",
      "retryable": false,
      "description": "The tenant does not have enough credits to send to external recipients."
    },
    {
      "code": "daily_quota_exceeded",
      "category": "policy",
      "retryable": true,
      "description": "The tenant has reached its rolling 24-hour outbound send limit."
    },
    {
      "code": "hourly_quota_exceeded",
      "category": "policy",
      "retryable": true,
      "description": "The tenant has reached its rolling 1-hour outbound send limit."
    },
    {
      "code": "resource_agent_not_found",
      "category": "resource",
      "retryable": false,
      "description": "The requested agent does not exist."
    },
    {
      "code": "resource_mailbox_not_found",
      "category": "resource",
      "retryable": false,
      "description": "The requested mailbox does not exist."
    },
    {
      "code": "resource_message_not_found",
      "category": "resource",
      "retryable": false,
      "description": "The requested message does not exist."
    },
    {
      "code": "resource_thread_not_found",
      "category": "resource",
      "retryable": false,
      "description": "The requested thread does not exist."
    },
    {
      "code": "resource_draft_not_found",
      "category": "resource",
      "retryable": false,
      "description": "The requested draft does not exist."
    },
    {
      "code": "resource_outbound_job_not_found",
      "category": "resource",
      "retryable": false,
      "description": "The requested outbound job does not exist."
    },
    {
      "code": "resource_suppression_not_found",
      "category": "resource",
      "retryable": false,
      "description": "The requested suppression record does not exist."
    },
    {
      "code": "idempotency_conflict",
      "category": "idempotency",
      "retryable": false,
      "description": "The provided idempotency key is already reserved for a different logical request."
    },
    {
      "code": "idempotency_in_progress",
      "category": "idempotency",
      "retryable": true,
      "description": "The provided idempotency key is already in progress for the same logical request."
    },
    {
      "code": "tool_internal_error",
      "category": "internal",
      "retryable": true,
      "description": "The runtime failed while processing the tool call."
    }
  ],
  "routes": {
    "adminEnabled": true,
    "debugEnabled": true
  },
  "delivery": {
    "outboundProvider": "ses"
  }
}