---
title: library_placement_update
description: Change the name, the description, or the rules of a Placement of your organization.
---

Ask to change a slot of your own. The agent changes the name, the description, or the rules. A field that the call leaves out stays as it is. The new rules replace the stored list, so the agent sends the whole list.

> "Make the partner feed placement need 1080 pixels of width."

When a Variation names the Placement, the next read of that Variation shows its new broken rules. A global Placement is read-only, and a change of it answers `not_found`.

This tool is part of the job [Bring your own creative](/mcp/tools/bring-your-own-creative).

## Reference

Change the name, the description or the rules of a Placement of your organization. A field that the call leaves out stays as it is. The new `rules` replace the stored list: send the whole list. The rules can change while a Variation names the Placement: the next read of the Variation shows the new `brokenRules`. A Placement is the slot where a provider shows an ad, for example Meta Stories video. It holds rules that an Asset should hold to fit the slot. The rules are advice: they never block a write. `type` and `channel` never change after the create. A global row (`isGlobal` is true) is held by AdCrunch for each organization. You read it and use it. A change of a global row, and a delete of it, answer not_found.

### Input

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string or null | no | A free text. A blank text or `null` stores no description. On an update, leave it out to keep the description. |
| `name` | string | no | The name, 1 to 80 characters. AdCrunch trims it. It must be unique, ignoring case, among the ones that your organization sees: for a Placement, among the Placements of the same channel. |
| `placement_id` | string | yes | The id of a Placement (plm_…). library_placement_list gives it. A Placement of AdCrunch (`isGlobal`) and a Placement of your organization both work. |
| `rules` | array of object | no | The rules that an Asset should hold, 20 at most. All of them must hold, and there is no "or" between two rules. A rule is `{ type, operator: { condition, value } }`. `type` is one of `width`, `height`, `ratio`, `size`, `mime` and `duration`. `duration` is for a video Placement only. Units: `width` and `height` are pixels. `size` is bytes. `duration` is milliseconds. A `ratio` value is a pair `[width, height]` of whole numbers, for example `[9, 16]`. Two ratios are equal when they differ by 1 % at most. A `mime` value is a string such as `image/jpeg`. `condition` is one of `eq`, `ne`, `lt`, `lte`, `gt`, `gte` and `in`. `mime` takes `eq`, `ne` and `in` only. `in` takes a list of values: `[[4, 5], [1, 1]]` means "the ratio is 4:5 or 1:1". Example of three rules: `[{"type":"ratio","operator":{"condition":"in","value":[[4,5],[1,1]]}},{"type":"width","operator":{"condition":"gte","value":600}},{"type":"mime","operator":{"condition":"in","value":["image/jpeg","image/png"]}}]`. |
| `rules[].type` | `width` or `height` or `size` or `ratio` or `mime` or `duration` | yes |  |
| `rules[].operator` | object | yes | Only when `type` is `width`. |
| `rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `rules[].operator` | object | yes | Only when `type` is `height`. |
| `rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `rules[].operator` | object | yes | Only when `type` is `size`. |
| `rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `rules[].operator` | object | yes | Only when `type` is `ratio`. |
| `rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `eq`. |
| `rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `ne`. |
| `rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lt`. |
| `rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lte`. |
| `rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gt`. |
| `rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gte`. |
| `rules[].operator.value` | array of (array of any, 2 items), 1 to 50 items | yes | Only when `condition` is `in`. |
| `rules[].operator` | object | yes | Only when `type` is `mime`. |
| `rules[].operator.condition` | `eq` or `ne` or `in` | yes |  |
| `rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `eq`. |
| `rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `ne`. |
| `rules[].operator.value` | array of (string, 1 to 255 characters), 1 to 50 items | yes | Only when `condition` is `in`. |
| `rules[].operator` | object | yes | Only when `type` is `duration`. |
| `rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |

### Output

A successful call returns this object in `structuredContent`.

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `placement` | object | yes | The Placement with its new name, description or rules. |
| `placement.channel` | one of `meta`, `tiktok`, `snapchat`, `google_search`, `google_pmax`, `google_display`, `youtube`, `programmatic_display`, `linkedin`, `x` | yes | The channel of a Line Item that the Placement belongs to. It never changes. |
| `placement.createdAt` | number | yes | Milliseconds since the Unix epoch, UTC. |
| `placement.createdBy` | string or null | yes | The user who created the Placement. `null` on a global row. |
| `placement.deletedAt` | number or null | yes | Always `null` here. A deleted Placement is not answered. |
| `placement.description` | string or null | yes | A free text. `null` when the Placement has none. |
| `placement.id` | string | yes | The id of the Placement, `plm_…`. |
| `placement.isGlobal` | boolean | yes | `true` on a row that AdCrunch holds for every organization. You read it, and you cannot change or delete it. |
| `placement.name` | string | yes | The name, 1 to 80 characters. It is unique, ignoring case, among the Placements of the channel that the organization sees. |
| `placement.organizationId` | string or null | yes | The organization that owns the Placement. `null` on a global row. |
| `placement.params` | object | yes |  |
| `placement.params.type` | `image` or `video` | yes |  |
| `placement.params.rules` | array of object, at most 20 items | yes | Only when `type` is `image`. |
| `placement.params.rules[].type` | `width` or `height` or `size` or `ratio` or `mime` | yes |  |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `width`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placement.params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `height`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placement.params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `size`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placement.params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `ratio`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lt`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lte`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gt`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gte`. |
| `placement.params.rules[].operator.value` | array of (array of any, 2 items), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `mime`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `in` | yes |  |
| `placement.params.rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | array of (string, 1 to 255 characters), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules` | array of object, at most 20 items | yes | Only when `type` is `video`. |
| `placement.params.rules[].type` | `width` or `height` or `size` or `ratio` or `mime` or `duration` | yes |  |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `width`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placement.params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `height`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placement.params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `size`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placement.params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `ratio`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lt`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lte`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gt`. |
| `placement.params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gte`. |
| `placement.params.rules[].operator.value` | array of (array of any, 2 items), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `mime`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `in` | yes |  |
| `placement.params.rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | array of (string, 1 to 255 characters), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.params.rules[].operator` | object | yes | Only when `type` is `duration`. |
| `placement.params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placement.params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placement.params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placement.type` | one of `image`, `video` | yes | The kind of Asset that the slot takes. It never changes, and it equals `params.type`. |
| `placement.updatedAt` | number or null | yes | When the Placement last changed. `null` until its first update. |

### Failure codes

A failed call has `isError` set, and `structuredContent.error` holds one of these codes. [Errors](/mcp/errors) describes the shape of a failed call.

- `not_found`
- `invalid_name`
- `invalid_rules`
- `name_taken`
- `organization_unentitled`
- `forbidden`
- `invalid_request`
- `internal_error`

### Scope

The token must hold `library:write`. [Auth & scopes](/mcp/auth) lists each scope.

### Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

- **Writes.** The tool can change data.
- **Not destructive.** The tool makes only additive changes.
- **Idempotent.** A second call with the same arguments changes nothing more.
- **Closed world.** The tool reads and writes the data of AdCrunch only.

### Example

The arguments:

```json
{
  "name": "Reels short cut",
  "placement_id": "plm_4b8d27",
  "rules": [
    {
      "operator": {
        "condition": "eq",
        "value": [
          9,
          16
        ]
      },
      "type": "ratio"
    },
    {
      "operator": {
        "condition": "lte",
        "value": 30000
      },
      "type": "duration"
    }
  ]
}
```

The result, in `structuredContent`:

```json
{
  "placement": {
    "channel": "meta",
    "createdAt": 1790000500000,
    "createdBy": "usr_2e5b84",
    "deletedAt": null,
    "description": "Our own cut for Reels, never over 30 seconds.",
    "id": "plm_4b8d27",
    "isGlobal": false,
    "name": "Reels short cut",
    "organizationId": "org_3a7f10",
    "params": {
      "rules": [
        {
          "operator": {
            "condition": "eq",
            "value": [
              9,
              16
            ]
          },
          "type": "ratio"
        },
        {
          "operator": {
            "condition": "lte",
            "value": 30000
          },
          "type": "duration"
        }
      ],
      "type": "video"
    },
    "type": "video",
    "updatedAt": 1790000900000
  }
}
```
