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

With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly warns the tool is DESTRUCTIVE, explains the immutable-creative mechanism (new creative_id, orphaned old creative), discloses side effects on live ads (reset social proof, restart learning phase), and details array/media handling semantics. This is exceptionally transparent and goes beyond what annotations would typically provide.

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?

The description is dense but every sentence earns its place: it front-loads the destructive warning, explains the immutable mechanism, lists side effects, covers text-array and media-swap rules, and gives the mandatory dry-run workflow. No fluff or repetition; the structure is logical and efficient for a tool with this complexity.

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?

The description covers the tricky behavioral aspects thoroughly and provides step-by-step usage for dry_run, which is critical for correct invocation. However, there is no output schema and the description does not explicitly state what the tool returns when dry_run: false (e.g., success indication, new creative_id). Given the complexity and lack of output schema, this is a minor but notable gap.

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?

The input schema already has 100% parameter description coverage, and the description reinforces key semantics (arrays must be complete sets, media slots like-for-like, dry_run importance). It adds value beyond the schema by explaining the dry-run process for retrieving media slots and the ordering requirement for the media array. This is above the baseline for high schema coverage.

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 states a specific action ('Edit the CONTENT of an existing Meta ad') and enumerates exactly which fields are affected (primary text, headline, description, CTA, links, media). It also distinguishes itself from sibling create tools by explaining the immutable-creative mechanism and that the ad id is preserved. This clearly differentiates it from adsap_create_ad and similar tools.

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 gives clear procedural guidance ('ALWAYS call with dry_run: true first') and explains when the tool is appropriate (editing existing ad content). However, it does not explicitly name alternatives for other ad modifications (e.g., budget changes via update_entity) or state when not to use this tool. The context is present but exclusions are implicit rather than stated.

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