MCP tool

prepare_agent_action

Canonicalize one registered consequential action before requesting approval. Pass REST-level parameters from list_agent_actions and explicit integer-minor-unit authority. The API returns the exact privacy-safe action object plus its SHA-256 digest. Use that action unchanged with request_agent_approval, then as the execute-step input. Credentials and large outcome batches are represented by fingerprints rather than copied into the durable approval journal. This tool has no side effect.

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": {
    "name": {
      "type": "string",
      "enum": [
        "study.create",
        "study.update",
        "study.quote.request",
        "study.cancellation.request",
        "study.preview",
        "study.results.refresh",
        "study.draft",
        "study.launch",
        "data.identity.map",
        "data.identity.optout",
        "data.postcodes.classify",
        "plan.update",
        "plan.search-keywords.update",
        "plan.approve",
        "campaign.launch",
        "campaign.booking.request",
        "campaign.pause",
        "campaign.resume",
        "campaign.tracking.update",
        "campaign.conversion-goal.update",
        "outcome.import",
        "optimization.approve",
        "optimization.reject",
        "audience.sync",
        "campaign.creatives.update",
        "creative.submit",
        "asset.submit",
        "connection.update",
        "billing.topup"
      ],
      "description": "stable name from list_agent_actions"
    },
    "parameters": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "REST-level path ids and request body fields from the listed contract"
    },
    "budgetMinor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1900000000,
      "description": "exact authority in minor units; zero for non-spend actions"
    },
    "currency": {
      "type": "string",
      "enum": [
        "GBP",
        "USD",
        "EUR"
      ],
      "description": "authority currency; currently GBP for executable routes"
    }
  },
  "required": [
    "name",
    "parameters",
    "budgetMinor",
    "currency"
  ]
}

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/actions/prepare",
  "pathFields": [],
  "pathSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  },
  "pathEncoding": "encodeURIComponent for each path field",
  "governedAction": null,
  "headers": {},
  "bodySchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "enum": [
          "study.create",
          "study.update",
          "study.quote.request",
          "study.cancellation.request",
          "study.preview",
          "study.results.refresh",
          "study.draft",
          "study.launch",
          "data.identity.map",
          "data.identity.optout",
          "data.postcodes.classify",
          "plan.update",
          "plan.search-keywords.update",
          "plan.approve",
          "campaign.launch",
          "campaign.booking.request",
          "campaign.pause",
          "campaign.resume",
          "campaign.tracking.update",
          "campaign.conversion-goal.update",
          "outcome.import",
          "optimization.approve",
          "optimization.reject",
          "audience.sync",
          "campaign.creatives.update",
          "creative.submit",
          "asset.submit",
          "connection.update",
          "billing.topup"
        ],
        "description": "stable name from list_agent_actions"
      },
      "parameters": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {},
        "description": "REST-level path ids and request body fields from the listed contract"
      },
      "budgetMinor": {
        "type": "integer",
        "minimum": 0,
        "maximum": 1900000000,
        "description": "exact authority in minor units; zero for non-spend actions"
      },
      "currency": {
        "type": "string",
        "enum": [
          "GBP",
          "USD",
          "EUR"
        ],
        "description": "authority currency; currently GBP for executable routes"
      }
    },
    "additionalProperties": false,
    "required": [
      "name",
      "parameters",
      "budgetMinor",
      "currency"
    ]
  },
  "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": {
    "action": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "actionDigest": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "action",
    "actionDigest"
  ],
  "additionalProperties": {}
}

Safety annotations

MCP annotations

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

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