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

The annotations already declare the write/safe/open-world profile, so the description only needs to add context. It does add one genuinely valuable trait — the ad is created PAUSED, i.e., it will not spend until activated — but says nothing about account/page permissions, whether dry_run performs validation only, or what gets returned on success.

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 front-loaded sentence that packs verb, resource, card count, card fields and initial status with no filler. Nothing here could be cut without losing information.

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 12-parameter, low-coverage mutation tool with no output schema, this is thin. An agent still cannot tell where image_hash values come from, what dry_run does, whether primary_text/call_to_action are required for a usable ad, or what the call returns.

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 only 33% (12 params), so the description carries a heavy burden. It helpfully defines card composition (image_hash, link, headline, optional description) and the 2–10 bound, but leaves name, adset, page_id, primary_text, call_to_action, language, account, folder, instagram_user_id and dry_run entirely unaddressed in both schema and description.

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?

Specific verb+resource ('Create a carousel ad') with the defining structural constraint (2–10 cards) and the resulting state (PAUSED). 'Carousel' implicitly separates it from meta_create_ad, but no sibling is named, so differentiation is inferred rather than stated.

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?

'in an ad set' implies the parent adset must already exist, which is real usage context. However, there is no explicit when-to-use-vs-alternative guidance (single-image ad via meta_create_ad, or a full campaign/adset build first), and no prerequisite noted for obtaining image_hash values via meta_upload_image.

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