Create or update entities in bulk

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

Well beyond the annotations, it discloses that the job is applied asynchronously in the background, that this server cannot verify every resulting change, that a confirm token of 'APPLY' (or 'ARCHIVE' when anything is archived) is mandatory, and that campaigns created without a status land PAUSED. It also states the return contract (a request_id) and the tool to poll it with. That is exactly the extra risk and side-effect context an agent needs for a destructive, non-idempotent write.

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?

Front-loaded with purpose, then payload shape, then safety/confirmation, then return value — a sensible progression with no filler sentences. The middle paragraph is dense and slightly run-on, but every clause carries information the caller could not get from the empty-parameter schema.

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?

For a 4-parameter bulk mutation with an output schema present, the description covers the async lifecycle, the confirmation gate, default status behavior, and the poll target, so an agent can call it correctly. Remaining holes are the unexplained ad_account_id and the absence of any statement about what happens when both create and update are omitted.

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 description coverage is 0%, so the description must carry parameter meaning — and it largely does: it explains the shape of 'create' and 'update' as objects keyed by entity family, gives concrete example payloads for product group promotions and keywords, and specifies the confirm values APPLY vs ARCHIVE. The gap is ad_account_id, which is never mentioned, and the fact that nothing says at least one of create/update is expected.

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?

The first sentence gives a specific verb pair (create and/or update), a specific resource (many ad entities), and a distinguishing mode (one asynchronous Pinterest bulk job). That 'bulk, many entities, one job' framing separates it cleanly from the single-entity siblings such as pinterest_ads_create_campaigns and pinterest_ads_update_ads.

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?

The description establishes clear context for use: it enumerates the entity families it can batch (campaigns, ad_groups, ads, product_groups, keywords, catalog_product_groups, labels, schedules) and tells the caller that each entry mirrors the matching create/update tool, with updates needing an id. It also names the required follow-up tool (pinterest_ads_get_bulk_request). What it lacks is an explicit 'use this instead of N single calls when...' statement or an exclusion, so the when-not side is left implicit.

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