library_placement_get
Read one Placement of your Library, with its rules.
Ask what a slot needs. The agent reads one Placement with its rules.
“What are the rules of Meta Stories video?”
The agent finds the Placement with library_placement_list, and calls this tool. You see the type, the channel, and each rule with its unit: pixels, bytes, milliseconds, or a ratio as a pair of numbers. The rules are advice, and they never block a write.
This tool is part of the job Bring your own creative.
Reference
Read one Placement of your Library, with its rules, that is a global Placement of AdCrunch or a Placement of your organization. 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. 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 |
|---|---|---|---|
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. |
Output
A successful call returns this object in structuredContent.
| Field | Type | Always present | Description |
|---|---|---|---|
placement |
object | yes | The Placement, with its rules in params and isGlobal. |
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.
not_foundorganization_unentitledforbiddeninvalid_requestinternal_error
Scope
The token must hold library:read. 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.
- Read-only. The tool changes nothing.
- Closed world. The tool reads and writes the data of AdCrunch only.
Example
The arguments:
{
"placement_id": "plm_meta_stories_video"
}
The result, in structuredContent:
{
"placement": {
"channel": "meta",
"createdAt": 1789000000000,
"createdBy": null,
"deletedAt": null,
"description": null,
"id": "plm_meta_stories_video",
"isGlobal": true,
"name": "Meta Stories video",
"organizationId": null,
"params": {
"rules": [
{
"operator": {
"condition": "eq",
"value": [
9,
16
]
},
"type": "ratio"
},
{
"operator": {
"condition": "gte",
"value": 250
},
"type": "width"
},
{
"operator": {
"condition": "in",
"value": [
"video/mp4",
"video/quicktime"
]
},
"type": "mime"
},
{
"operator": {
"condition": "gte",
"value": 1000
},
"type": "duration"
}
],
"type": "video"
},
"type": "video",
"updatedAt": null
}
}