Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, but the description adds far more: per-kind permission scopes (playlist.create, schedule.create, org-unit.create, integration.create), idempotency for locations ('a node whose externalId already exists is skipped, so re-running is safe'), and partial-failure semantics for celebrations ('one bad row is reported, not fatal'). It also clarifies that item refs must already exist, which is a real prerequisite not visible in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense paragraph, but it is front-loaded with the core verb and the 'exactly ONE of' rule before enumerating kinds, and each clause carries non-obvious information (limits, permissions, idempotency). The one nit is that the paragraph is long and scannable structure (per-kind bullets) would help an agent parse four variants quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shapes need not be described, and the description still covers everything else an agent needs: which arrays are mutually exclusive, size caps, required pre-existing references, permission scopes, per-kind error behaviour, and where to go for related write operations. Nothing material is left to inference for a four-variant bulk write tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the mutual exclusivity of the four arrays ('exactly ONE of') is not expressible in the schema, and it specifies that schedule block times are 'HH:MM 24-hour in the SCREEN's timezone', a detail the schema omits. It also reiterates the per-kind caps and parentExternalId ordering, which the schema also covers, so it is additive rather than redundant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create many records of one kind in one call') and then enumerates the four record kinds it accepts with their individual semantics. It also names the sibling it is not — update_playlist and create_creatives — so an agent can distinguish it from neighbouring write tools without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames itself as 'the migration and import tool' and states the cardinal rule 'Pass exactly ONE of' followed by per-kind conditions. It closes with an explicit exclusion and routing ('Only creates; to change an existing playlist use update_playlist, to design a screen use create_creatives'), giving both when-to-use and when-to-use-something-else.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.