MCP tool

add_agent_step

Record one pending step in the run’s current phase using optimistic expectedPhase. A non-other kind must match the phase. An EXECUTE step must carry the approved external action’s approvalId and exact actionDigest; recording it atomically consumes that approval so it cannot authorize a second action. CRITICAL: this tool only records the step and consumes authority. It does not call an AdBuyMCP execution tool or any provider. Call the governed tool separately with its agentAuthorization; the API claims and settles the execute step from the real route receipt.

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
    },
    "expectedPhase": {
      "type": "string",
      "enum": [
        "observe",
        "plan",
        "approve",
        "execute",
        "verify"
      ]
    },
    "kind": {
      "type": "string",
      "enum": [
        "observe",
        "plan",
        "approve",
        "execute",
        "verify",
        "other"
      ]
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240
    },
    "input": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "approvalId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "expectedActionDigest": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "runId",
    "expectedPhase",
    "kind",
    "label"
  ]
}

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}/steps",
  "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": {
      "expectedPhase": {
        "type": "string",
        "enum": [
          "observe",
          "plan",
          "approve",
          "execute",
          "verify"
        ]
      },
      "kind": {
        "type": "string",
        "enum": [
          "observe",
          "plan",
          "approve",
          "execute",
          "verify",
          "other"
        ]
      },
      "label": {
        "type": "string",
        "minLength": 1,
        "maxLength": 240
      },
      "input": {
        "default": {},
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "approvalId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      },
      "expectedActionDigest": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$"
      }
    },
    "additionalProperties": false,
    "required": [
      "expectedPhase",
      "kind",
      "label"
    ]
  },
  "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": {
    "step": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "step"
  ],
  "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 →