MCP tool

finish_agent_run

Finish a non-terminal run as succeeded, failed or cancelled using optimistic expectedPhase and a durable summary. Success requires verify phase, a completed verify step with linked evidence, and no pending steps, approvals or exceptions. In verify, add_agent_step with kind verify, record_agent_evidence linked by stepId, then complete_agent_step before finishing. This terminal control record frees the mission for another run; it does not change campaigns or infer success from missing provider evidence.

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
    },
    "outcome": {
      "type": "string",
      "enum": [
        "succeeded",
        "failed",
        "cancelled"
      ]
    },
    "expectedPhase": {
      "type": "string",
      "enum": [
        "observe",
        "plan",
        "approve",
        "execute",
        "verify"
      ]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000
    }
  },
  "required": [
    "runId",
    "outcome",
    "expectedPhase",
    "summary"
  ]
}

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}/finish",
  "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": {
      "outcome": {
        "type": "string",
        "enum": [
          "succeeded",
          "failed",
          "cancelled"
        ]
      },
      "expectedPhase": {
        "type": "string",
        "enum": [
          "observe",
          "plan",
          "approve",
          "execute",
          "verify"
        ]
      },
      "summary": {
        "type": "string",
        "minLength": 1,
        "maxLength": 4000
      }
    },
    "additionalProperties": false,
    "required": [
      "outcome",
      "expectedPhase",
      "summary"
    ]
  },
  "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": {
    "run": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "run"
  ],
  "additionalProperties": {}
}

Safety annotations

MCP annotations

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

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