MCP tool

request_agent_approval

Create a pending approval and move an unblocked run to waiting_approval. An external_action can only be requested in approve phase and must fit the run’s active execute mandate, including its allowlisted action name and explicit budgetMinor/currency (use zero for non-spend actions). The response returns the canonical actionDigest. This requests authority; it does not grant or execute it. An MCP identity cannot approve its own request: direct the user to the Operator approval queue, then poll get_agent_run until the approval is approved or rejected.

Input

Pass fields from this schema as the tool arguments. Runtime ownership, product scope and readiness checks still apply.

Input JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "kind": {
      "type": "string",
      "enum": [
        "external_action",
        "policy",
        "creative",
        "measurement",
        "other"
      ]
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "action": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "pattern": "^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$"
        },
        "parameters": {
          "default": {},
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        "budgetMinor": {
          "type": "integer",
          "minimum": 0,
          "maximum": 1900000000
        },
        "currency": {
          "type": "string",
          "enum": [
            "GBP",
            "USD",
            "EUR"
          ]
        }
      },
      "required": [
        "name"
      ]
    },
    "stepId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "runId",
    "kind",
    "reason",
    "action"
  ]
}

REST mapping and authority

The tool wraps this REST endpoint. The mapping identifies path/query/body transformations and approval or idempotency headers.

Request contract

{
  "method": "POST",
  "path": "/api/v1/agent/runs/{runId}/approvals",
  "pathFields": [
    "runId"
  ],
  "pathSchema": {
    "type": "object",
    "properties": {
      "runId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      }
    },
    "additionalProperties": false,
    "required": [
      "runId"
    ]
  },
  "pathEncoding": "encodeURIComponent for each path field",
  "governedAction": null,
  "headers": {},
  "bodySchema": {
    "type": "object",
    "properties": {
      "kind": {
        "type": "string",
        "enum": [
          "external_action",
          "policy",
          "creative",
          "measurement",
          "other"
        ]
      },
      "reason": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2000
      },
      "action": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "pattern": "^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$"
          },
          "parameters": {
            "default": {},
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "budgetMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1900000000
          },
          "currency": {
            "type": "string",
            "enum": [
              "GBP",
              "USD",
              "EUR"
            ]
          }
        },
        "required": [
          "name"
        ]
      },
      "stepId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      },
      "expiresAt": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
      }
    },
    "additionalProperties": false,
    "required": [
      "kind",
      "reason",
      "action"
    ]
  },
  "responseMapping": "REST JSON is returned as MCP structuredContent and a compatibility text block; privacy-sensitive tools validate their output schema."
}

Output

This is the registered MCP output envelope. Nested fields are only modeled where the schema explicitly defines them.

Output JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "approval": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "approval"
  ],
  "additionalProperties": {}
}

Safety annotations

MCP annotations

{
  "readOnlyHint": false,
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false
}

Annotations help a client present the tool. The API independently enforces authorization and exact action approvals. Error and retry guidance →