MCP tool

set_campaign_conversion_goal

Bind one freshly read provider-owned conversion rule to a pending campaign line and its approved performance brief and destination. Requires the exact definition digest, connection revision and current binding ID from list_campaign_conversion_goals, plus governed action approval. The provider definition is reread before saving. Activated lines are immutable; stale evidence returns a conflict and must be reviewed again. TikTok and Meta require explicit click/view attribution windows and event counting; these have no defaults and become immutable after creation. This selection does not launch or enable spend.

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": {
    "campaignId": {
      "type": "string",
      "minLength": 1
    },
    "lineId": {
      "type": "string",
      "minLength": 1
    },
    "goalRef": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "expectedDefinitionDigest": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "expectedConnectionRevision": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "expectedBindingId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "tiktokSettings": {
      "type": "object",
      "properties": {
        "clickAttributionWindow": {
          "type": "string",
          "enum": [
            "ONE_DAY",
            "SEVEN_DAYS",
            "FOURTEEN_DAYS",
            "TWENTY_EIGHT_DAYS"
          ]
        },
        "viewAttributionWindow": {
          "type": "string",
          "enum": [
            "OFF",
            "ONE_DAY",
            "SEVEN_DAYS"
          ]
        },
        "attributionEventCount": {
          "type": "string",
          "enum": [
            "ONCE",
            "EVERY"
          ]
        }
      },
      "required": [
        "clickAttributionWindow",
        "viewAttributionWindow",
        "attributionEventCount"
      ],
      "additionalProperties": false
    },
    "metaSettings": {
      "type": "object",
      "properties": {
        "clickAttributionWindow": {
          "type": "string",
          "enum": [
            "ONE_DAY",
            "SEVEN_DAYS"
          ]
        },
        "viewAttributionWindow": {
          "type": "string",
          "enum": [
            "OFF",
            "ONE_DAY"
          ]
        },
        "attributionCountType": {
          "type": "string",
          "enum": [
            "ALL_CONVERSIONS",
            "FIRST_CONVERSION"
          ]
        }
      },
      "required": [
        "clickAttributionWindow",
        "viewAttributionWindow",
        "attributionCountType"
      ],
      "additionalProperties": false
    },
    "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"
    }
  },
  "required": [
    "campaignId",
    "lineId",
    "goalRef",
    "expectedDefinitionDigest",
    "expectedConnectionRevision",
    "expectedBindingId",
    "agentStepId",
    "expectedActionDigest"
  ]
}

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/campaigns/{campaignId}/lines/{lineId}/conversion-goal",
  "pathFields": [
    "campaignId",
    "lineId"
  ],
  "pathSchema": {
    "type": "object",
    "properties": {
      "campaignId": {
        "type": "string",
        "minLength": 1
      },
      "lineId": {
        "type": "string",
        "minLength": 1
      }
    },
    "additionalProperties": false,
    "required": [
      "campaignId",
      "lineId"
    ]
  },
  "pathEncoding": "encodeURIComponent for each path field",
  "governedAction": "campaign.conversion-goal.update",
  "headers": {
    "x-chorus-agent-step-id": "agentStepId",
    "x-chorus-agent-action-digest": "expectedActionDigest"
  },
  "bodySchema": {
    "type": "object",
    "properties": {
      "goalRef": {
        "type": "string",
        "minLength": 1,
        "maxLength": 500
      },
      "expectedDefinitionDigest": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$"
      },
      "expectedConnectionRevision": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      },
      "expectedBindingId": {
        "anyOf": [
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          {
            "type": "null"
          }
        ]
      },
      "tiktokSettings": {
        "type": "object",
        "properties": {
          "clickAttributionWindow": {
            "type": "string",
            "enum": [
              "ONE_DAY",
              "SEVEN_DAYS",
              "FOURTEEN_DAYS",
              "TWENTY_EIGHT_DAYS"
            ]
          },
          "viewAttributionWindow": {
            "type": "string",
            "enum": [
              "OFF",
              "ONE_DAY",
              "SEVEN_DAYS"
            ]
          },
          "attributionEventCount": {
            "type": "string",
            "enum": [
              "ONCE",
              "EVERY"
            ]
          }
        },
        "required": [
          "clickAttributionWindow",
          "viewAttributionWindow",
          "attributionEventCount"
        ],
        "additionalProperties": false
      },
      "metaSettings": {
        "type": "object",
        "properties": {
          "clickAttributionWindow": {
            "type": "string",
            "enum": [
              "ONE_DAY",
              "SEVEN_DAYS"
            ]
          },
          "viewAttributionWindow": {
            "type": "string",
            "enum": [
              "OFF",
              "ONE_DAY"
            ]
          },
          "attributionCountType": {
            "type": "string",
            "enum": [
              "ALL_CONVERSIONS",
              "FIRST_CONVERSION"
            ]
          }
        },
        "required": [
          "clickAttributionWindow",
          "viewAttributionWindow",
          "attributionCountType"
        ],
        "additionalProperties": false
      }
    },
    "additionalProperties": false,
    "required": [
      "goalRef",
      "expectedDefinitionDigest",
      "expectedConnectionRevision",
      "expectedBindingId"
    ]
  },
  "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": {},
  "additionalProperties": {}
}

Safety annotations

MCP annotations

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

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