MCP tool

update_plan_allocations

Change one or more line budgets on a DRAFT plan and reforecast every changed line through its selected adapter. Use the allocationVersion returned by get_plan as expectedAllocationVersion; a concurrent change returns PLAN_VERSION_CONFLICT, in which case reload and ask the user to review the new state. Omitted lines keep their budgets. Amounts are pounds sterling and each line must remain above its channel/flight minimum. This changes money allocation and must be shown to the user before calling it.

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": {
    "planId": {
      "type": "string",
      "minLength": 1,
      "description": "draft plan id"
    },
    "agentStepId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "pending execute-step id that consumed the exact approved action"
    },
    "expectedActionDigest": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "SHA-256 digest returned for the exact approved action"
    },
    "expectedAllocationVersion": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "allocationVersion from the latest get_plan response"
    },
    "lines": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lineItemId": {
            "type": "string",
            "minLength": 1,
            "description": "line id from get_plan"
          },
          "budgetPounds": {
            "type": "number",
            "minimum": 0,
            "maximum": 19000000,
            "description": "replacement line budget in GBP pounds"
          }
        },
        "required": [
          "lineItemId",
          "budgetPounds"
        ]
      }
    }
  },
  "required": [
    "planId",
    "agentStepId",
    "expectedActionDigest",
    "expectedAllocationVersion",
    "lines"
  ]
}

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": "PATCH",
  "path": "/api/v1/plans/{planId}",
  "pathFields": [
    "planId"
  ],
  "pathSchema": {
    "type": "object",
    "properties": {
      "planId": {
        "type": "string",
        "minLength": 1,
        "description": "draft plan id"
      }
    },
    "additionalProperties": false,
    "required": [
      "planId"
    ]
  },
  "pathEncoding": "encodeURIComponent for each path field",
  "governedAction": "plan.update",
  "headers": {
    "x-chorus-agent-step-id": "agentStepId",
    "x-chorus-agent-action-digest": "expectedActionDigest"
  },
  "bodySchema": {
    "type": "object",
    "properties": {
      "expectedAllocationVersion": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$",
        "description": "allocationVersion from the latest get_plan response"
      },
      "lines": {
        "minItems": 1,
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "id",
            "budgetMinor"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "budgetMinor": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1900000000
            }
          }
        }
      }
    },
    "additionalProperties": false,
    "required": [
      "expectedAllocationVersion",
      "lines"
    ]
  },
  "bodyMapping": {
    "expectedAllocationVersion": "expectedAllocationVersion",
    "lines[].id": "lines[].lineItemId",
    "lines[].budgetMinor": {
      "from": "lines[].budgetPounds",
      "transform": "Math.round(value * 100)"
    }
  },
  "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": {
    "plan": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "plan"
  ],
  "additionalProperties": {}
}

Safety annotations

MCP annotations

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

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