Change catalog items in a batch

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

Annotations already flag destructive and non-idempotent, and the description adds materially: the 1000-item cap, the confirm='DELETE' requirement for deletions, the confirm='APPLY' requirement above PINTEREST_ADS_BULK_THRESHOLD, and that the call is asynchronous, returning a batch_id to poll with pinterest_ads_get_catalog_items_batch. That is real behavioral context an agent cannot get from the 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?

Dense and front-loaded — verbs and cap first, then the item shape, then the feed caveat, then the confirm gates, then the return value. Nothing is filler, though the trailing fragment about the return value reads as tacked on rather than integrated.

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 an eight-parameter, destructive, non-idempotent batch mutation with no output schema and 0% schema description coverage, key gaps remain: the roles of catalog_id vs ad_account_id, what catalog_type defaults to and affects, and what country/language constrain. The operational and confirmation story is complete; the parameter story is not.

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 the load. It does well on operation, items (with a concrete example object and the note that DELETE needs only item_id) and confirm, but country, language, catalog_id, catalog_type and ad_account_id get no explanation at all, leaving five of eight parameters undocumented anywhere.

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 description opens with a specific verb set and resource: create/update/upsert/delete catalog items in a batch, with a size ceiling of 1000. That distinguishes it from list/get siblings such as pinterest_ads_get_catalog_items and from the feed-based pinterest_ads_ingest_catalog_feed path.

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?

It spells out the four operations and what each means in practice (UPDATE changes some attributes, UPSERT sends every attribute), and it names an explicit alternative: if a feed manages the catalog, change items through the feed instead. The confirm gates tell the agent the exact conditions required before a destructive or bulk apply proceeds.

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