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_nameinvalid_rulesname_takenplacement_limitorganization_unentitledforbiddeninvalid_requestinternal_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
}
}