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

Annotations already declare destructiveHint=true and openWorldHint=true, so the bar is lower. The description still adds real value by distinguishing replacement semantics (headlines/descriptions are replaced) from additive semantics (images/videos are added) and by stating that clear_images/clear_videos remove all media. It omits error modes, asset-limit enforcement, and whether add_* appends to existing assets.

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?

One compact sentence plus a short clause, front-loaded with the mutation and scoped to the ad type. The trailing 'Runs directly' is vague and could be cut or rewritten, but overall there is little waste.

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 destructive 9-parameter mutation with no output schema, the definition covers the core edit semantics but says nothing about prerequisites (ad must be an App campaign ad), confirmation/permission requirements, or what is returned after the update. It is adequate but leaves gaps an agent would want filled before a destructive write.

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 only 22%, and ad_id, headlines, add_images, add_videos, clear_images, clear_videos and descriptions have no schema descriptions at all. The description compensates by explaining what these parameters do semantically: headlines/descriptions replace existing values while media is added, and clear_* flags wipe all media. account and dry_run remain unexplained in prose but carry schema descriptions.

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 names a specific verb and resource ('Replace headlines/descriptions and add images or YouTube videos on an App campaign ad'), which separates this from the generic google_ads_update_ad and google_ads_add_assets siblings. It does not name those siblings explicitly, so differentiation relies on the agent inferring from scope.

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?

There is no when-to-use versus when-not guidance and no alternative tools named; the agent must guess whether to use this or google_ads_update_ad / google_ads_add_assets for the same edit. The parenthetical about clear_images/clear_videos describes a capability, not a selection condition.

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