# RevCent MCP Guide: `EditUrlParameterSet`

AI/MCP-focused guide for editing URL Parameter Sets in RevCent.

This document explains the `EditUrlParameterSet` operation, its partial-edit behavior, the special replacement behavior of `url_parameters`, and safe editing practices for attribution metadata.

---

## Related Documentation

| Operation / Overview | Link | Why It Matters |
|---|---|---|
| URL Parameter Set Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewUrlParameterSet.md` | Broad explanation of URL Parameter Sets and attribution metadata. |
| CreateUrlParameterSet | `https://revcent.com/documentation/markdown/mcp/operation/CreateUrlParameterSet.md` | Explains creating reusable URL Parameter Sets. |
| GetUrlParameterSet |  | Retrieve the current set before editing. |
| GetUrlParameterSets |  | Locate URL Parameter Sets when ID is unknown. |
| Tracking Domain Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrackingDomain.md` | Explains DNS tracking, metadata capture, and conversion attribution. |
| EditTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/EditTrackingDomain.md` | Associates URL Parameter Sets with Tracking Domains. |
| GetTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/GetTrackingDomain.md` | Verifies Tracking Domain associations. |

---

## Operation Summary

Operation:

```text
EditUrlParameterSet
```

Title:

```text
Edit A URL Parameter Set
```

Purpose:

```text
Edit a previously created URL Parameter Set using the URL Parameter Set ID.
```

Use `EditUrlParameterSet` to update:

- name,
- description,
- enabled state,
- URL parameter list.

Important:

```text
Only include the properties you wish to modify.
```

If only changing the name, include only:

```text
url_parameter_set_id
name
```

If only disabling the set, include only:

```text
url_parameter_set_id
enabled
```

---

## Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `url_parameter_set_id` | string | Yes | 20-character URL Parameter Set ID. |

Example minimal shape:

```json
{
  "url_parameter_set_id": "PPPPPPPPPPPPPPPPPPPP"
}
```

In practice, include at least one editable field.

---

## Editable Fields

| Field | Type | Description |
|---|---:|---|
| `name` | string | URL Parameter Set name. Must be unique from other sets. |
| `description` | string | URL Parameter Set description. |
| `enabled` | boolean | Whether the set is enabled. |
| `url_parameters` | array[object] | Complete list of URL parameters to associate with the set. Special replacement behavior applies. |

---

## Output Schema

Successful output can include:

| Field | Type | Description |
|---|---:|---|
| `api_call_id` | string | 20-character API call ID. |
| `api_call_unix` | integer | Unix timestamp when the API call was initiated. |
| `code` | integer | API response code. `1` indicates success. |
| `url_parameter_set_id` | string | 20-character URL Parameter Set ID. |
| `result` | string | Result message. |

---

## Critical Rule: `url_parameters` Is a Full Replacement

`EditUrlParameterSet` has special behavior for `url_parameters`.

Schema guidance:

```text
Only provide the url_parameters array if it contains all URL parameters you want in the set.
If the array is provided and is empty, then all URL parameters will be removed from the set.
If the array is not provided, then the URL parameters in the set will remain unchanged.
```

This is the most important rule for AI/MCP clients.

### Safe Interpretation

| Request Shape | Result |
|---|---|
| Omit `url_parameters` | Existing URL parameters remain unchanged. |
| Provide populated `url_parameters` array | Existing list is replaced with the provided complete list. |
| Provide empty `url_parameters: []` | All URL parameters are removed from the set. |

Do not send `url_parameters` unless you intend to replace the full list.

---

## Always Retrieve Before Editing URL Parameters

Before changing URL parameters, retrieve the current set:

```text
GetUrlParameterSet
```

Recommended workflow:

```text
GetUrlParameterSet
    ↓
Read current url_parameters
    ↓
Apply intended additions/removals/changes locally
    ↓
Send full final url_parameters array to EditUrlParameterSet
    ↓
GetUrlParameterSet again to verify
```

Never attempt to add one parameter by sending only that one parameter unless the intent is to replace the set with only that one parameter.

---

## Example: Rename Only

```json
{
  "url_parameter_set_id": "PPPPPPPPPPPPPPPPPPPP",
  "name": "Standard Ecommerce Attribution"
}
```

Because `url_parameters` is omitted, the existing parameter list remains unchanged.

---

## Example: Disable Only

```json
{
  "url_parameter_set_id": "PPPPPPPPPPPPPPPPPPPP",
  "enabled": false
}
```

Because `url_parameters` is omitted, the existing parameter list remains unchanged.

---

## Example: Update Description Only

```json
{
  "url_parameter_set_id": "PPPPPPPPPPPPPPPPPPPP",
  "description": "Captures UTM, ad click, affiliate, and campaign parameters for RevCent DNS tracking."
}
```

---

## Example: Replace Full URL Parameter List

Use this when the final desired list is known.

```json
{
  "url_parameter_set_id": "PPPPPPPPPPPPPPPPPPPP",
  "url_parameters": [
    {
      "url_parameter": "utm_source",
      "metadata_name": "utm_source",
      "days": 30
    },
    {
      "url_parameter": "utm_medium",
      "metadata_name": "utm_medium",
      "days": 30
    },
    {
      "url_parameter": "utm_campaign",
      "metadata_name": "utm_campaign",
      "days": 30
    },
    {
      "url_parameter": "gclid",
      "metadata_name": "gclid",
      "days": 30
    }
  ]
}
```

This replaces the entire existing list.

---

## Example: Add One Parameter Safely

Wrong:

```json
{
  "url_parameter_set_id": "PPPPPPPPPPPPPPPPPPPP",
  "url_parameters": [
    {
      "url_parameter": "fbclid",
      "metadata_name": "fbclid",
      "days": 30
    }
  ]
}
```

That would replace the whole set with only `fbclid`.

Correct:

```text
1. GetUrlParameterSet.
2. Copy existing url_parameters.
3. Append fbclid.
4. Send the complete final array.
```

Correct request shape:

```json
{
  "url_parameter_set_id": "PPPPPPPPPPPPPPPPPPPP",
  "url_parameters": [
    {
      "url_parameter": "utm_source",
      "metadata_name": "utm_source",
      "days": 30
    },
    {
      "url_parameter": "utm_campaign",
      "metadata_name": "utm_campaign",
      "days": 30
    },
    {
      "url_parameter": "fbclid",
      "metadata_name": "fbclid",
      "days": 30
    }
  ]
}
```

---

## Example: Remove All URL Parameters

Only do this with explicit user confirmation.

```json
{
  "url_parameter_set_id": "PPPPPPPPPPPPPPPPPPPP",
  "url_parameters": []
}
```

Important:

```text
An empty url_parameters array removes all URL parameters from the set.
```

This can stop future capture of attribution metadata for Tracking Domains using this set.

---

## `url_parameters` Item Schema

Each item can include:

| Field | Type | Purpose |
|---|---:|---|
| `url_parameter` | string | Query parameter to capture. |
| `metadata_name` | string | Metadata key to save value as. Recommended empty or same as `url_parameter`. |
| `default_value` | string | Optional fixed value to save instead of URL value. Recommended empty. |
| `days` | integer | Visitor persistence window. Defaults to 30. Recommended 30. |

---

## Editing Metadata Names

Be careful changing `metadata_name`.

Changing metadata names affects future metadata capture and can break consistency with:

- existing BigQuery reports,
- AI Assistant workflows,
- affiliate reporting,
- ad attribution reporting,
- refund/chargeback analysis,
- support workflows.

Recommended:

```text
Keep metadata_name empty or equal to url_parameter.
```

Use a different metadata name only when intentionally normalizing reporting keys.

---

## Editing `default_value`

Use `default_value` only when intentionally overriding the real URL parameter value.

Most attribution use cases should preserve real values.

Recommended:

```text
Leave default_value empty.
```

---

## Editing `days`

`days` controls how long the parameter value persists for a visitor.

Recommended:

```text
30
```

If changing `days`, confirm the attribution window with the user.

---

## Editing Enabled State

Use `enabled` to turn the set on/off.

Example:

```json
{
  "url_parameter_set_id": "PPPPPPPPPPPPPPPPPPPP",
  "enabled": false
}
```

Disabling a set can affect Tracking Domains that rely on it for future metadata capture.

Before disabling, consider:

- which Tracking Domains use the set,
- whether reports depend on its metadata,
- whether active campaigns rely on it,
- whether WooCommerce/User Shop attribution depends on it.

---

## Tracking Domain Impact

URL Parameter Sets are associated with Tracking Domains.

Editing a URL Parameter Set can affect every Tracking Domain using that set.

Before editing parameters, ask:

```text
Which Tracking Domains use this set?
Is this change intended to affect all of them?
```

Use `GetTrackingDomain` or related lookup/reporting to verify associations when needed.

If a change should apply only to one domain, consider creating a new URL Parameter Set and attaching it only to that domain.

---

## Historical Metadata

Editing a URL Parameter Set affects future capture behavior.

It does not rewrite historical metadata already captured on visitors, Sales, subscriptions, refunds, or other related records.

Correct expectation:

```text
Future visitors/conversions use the new parameter configuration.
Past metadata remains as it was captured.
```

Use BigQuery for historical analysis.

---

## Recommended Edit Workflow

```text
1. User asks to edit a URL Parameter Set.
2. Use GetUrlParameterSet to retrieve the current set.
3. Confirm what the user wants changed.
4. If changing url_parameters:
       a. Build the complete final url_parameters list.
       b. Confirm the final list with the user.
       c. Send the full array.
5. If only changing name/description/enabled, omit url_parameters.
6. Call EditUrlParameterSet.
7. Use GetUrlParameterSet to verify.
8. If Tracking Domain behavior should change, verify associations with GetTrackingDomain.
```

---

## Pre-Edit Checklist

Before calling `EditUrlParameterSet`, verify:

- URL Parameter Set ID is correct.
- Current set was retrieved with `GetUrlParameterSet`.
- User confirmed the intended edit.
- Only intended fields are included.
- If changing `url_parameters`, the array contains the complete desired final list.
- If sending `url_parameters: []`, user explicitly wants to remove all parameters.
- Metadata names are intentional.
- `default_value` usage is intentional.
- `days` values are intentional.
- User understands edits affect future metadata capture.
- User understands all Tracking Domains using the set may be affected.

---

## Best Practices

1. Retrieve before editing.
2. Omit `url_parameters` when not changing the parameter list.
3. Send a complete final `url_parameters` array when changing parameters.
4. Never send a partial parameter list unless replacement is intended.
5. Use `url_parameters: []` only with explicit confirmation.
6. Keep metadata names stable.
7. Avoid `default_value` unless intentionally overriding URL values.
8. Use `days = 30` unless the attribution window should differ.
9. Consider Tracking Domain impact before editing shared sets.
10. Verify after editing.

---

## Common Mistakes to Avoid

Do not:

- send only one new parameter when trying to append it,
- send an empty `url_parameters` array accidentally,
- change metadata names casually,
- use `default_value` unintentionally,
- disable a set without considering Tracking Domains using it,
- assume historical metadata is updated retroactively,
- forget to verify with `GetUrlParameterSet`,
- use URL Parameter Set operations for reporting.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Rename set | `EditUrlParameterSet` with `name` only. |
| Update description | `EditUrlParameterSet` with `description` only. |
| Enable/disable set | `EditUrlParameterSet` with `enabled` only. |
| Add one parameter | Retrieve current list, append parameter, send complete final array. |
| Remove one parameter | Retrieve current list, remove parameter, send complete final array. |
| Remove all parameters | Send `url_parameters: []` only after explicit confirmation. |
| Check current parameters | Use `GetUrlParameterSet`. |
| See attached Tracking Domains | Inspect Tracking Domains that reference the set. |
| Report on metadata values | Use `BigQueryRunQuery`. |

---

## Final AI/MCP Instruction

Use `EditUrlParameterSet` carefully.

It is a partial-edit operation for `name`, `description`, and `enabled`, but `url_parameters` has full-replacement behavior. If `url_parameters` is provided, it must contain the complete desired final list. If it is provided as an empty array, all URL parameters are removed. If it is omitted, existing URL parameters remain unchanged.

Always retrieve the current set before changing URL parameters, build the full final list, and verify after editing.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.