Skip to content
AdCrunch
Esc
↑↓navigate↵open⌘Jpreview
On this page

library_placement_create

Create a Placement of your organization, with its rules, when no global Placement describes the slot.

Ask for a slot of your own. The agent creates a Placement with a name, a channel, a type, and rules.

“Create a placement for our partner feed: images, 4:5 or 1:1, at least 600 pixels wide.”

The agent first looks for a global Placement with library_placement_list. When none fits, it calls this tool. The name must be unique among the Placements of the same channel that your organization sees. The channel and the type never change after the create. Your organization can hold 200 Placements. The Placement stays in AdCrunch, and no ad account changes.

This tool is part of the job Bring your own creative.

Reference

Create a Placement in your Library: a slot of your own, with its rules. Use it when no global Placement of AdCrunch describes the slot. 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. The name must be unique, ignoring case, among the Placements of the same channel that your organization sees. Your organization can hold 200 Placements. type and channel never change after the create. The Placement stays in AdCrunch: this changes no ad account.

Input

Argument Type Required Description
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 slot belongs to. type and channel never change after the create.
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 yes 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.
rules array of object yes 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.
type one of image, video yes The kind of Asset that the slot takes. A slot that takes both has two Placements. type and channel never change after the create.

Output

A successful call returns this object in structuredContent.

Field Type Always present Description
placement object yes The new Placement of your organization. isGlobal is false.
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 describes the shape of a failed call.

  • invalid_name
  • invalid_rules
  • name_taken
  • placement_limit
  • organization_unentitled
  • forbidden
  • invalid_request
  • internal_error

Scope

The token must hold library:write. Auth & scopes 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.
  • Not idempotent. A second call with the same arguments can change more.
  • Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "channel": "meta",
  "description": "Our own cut for Reels, never over 30 seconds.",
  "name": "Reels short cut",
  "rules": [
    {
      "operator": {
        "condition": "eq",
        "value": [
          9,
          16
        ]
      },
      "type": "ratio"
    },
    {
      "operator": {
        "condition": "lte",
        "value": 30000
      },
      "type": "duration"
    }
  ],
  "type": "video"
}

The result, in structuredContent:

{
  "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": null
  }
}

Was this page helpful?