Google Ads - AdLoop

Overview Schema Source Related Servers Discussions Admin

Update a responsive search ad

update_responsive_search_ad

Update an existing responsive search ad's fields like final URL, paths, headlines, or descriptions in place. Note that changing headlines or descriptions resets ad learning and may require policy review; confirm the returned plan to apply.

Instructions

Update mutable fields on an existing RSA in place — returns a PREVIEW.

Edits an existing RSA without creating a new ad; the ad keeps its ID. Google Ads API v23 (AdService.MutateAds) permits in-place mutation of final_urls, path1, path2, headlines, and descriptions.

IMPORTANT: replacing headlines or descriptions is NOT a free in-place edit. Even though the ad ID is preserved, swapping the creative text RESETS the ad's asset-combination learning and performance history and sends the ad BACK THROUGH Google policy review — Google treats the creative as new for optimization. URL-only and path-only edits do not incur this. When headlines/descriptions change, the returned preview includes a warnings entry — surface it to the user before applying.

Headlines/descriptions are LIST-REPLACE — when provided, the supplied list fully swaps in for the existing one, and Google's RSA constraints apply (3-15 headlines, 2-4 descriptions, 30/90 char limits, pin-slot rules). Each entry may be a plain string (unpinned) or {"text": "...", "pinned_field": "HEADLINE_1"}.

Argument semantics: - headlines / descriptions: None or [] -> no change; non-empty list -> replaces the existing list in full - final_url: empty -> no change; non-empty -> replaces final URL - path1 / path2: empty -> no change; non-empty -> sets value - clear_path1 / clear_path2: True -> set to empty string

At least one mutation must be requested. Call confirm_and_apply with the returned plan_id to execute.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ad_id`	Yes
`path1`	No
`path2`	No
`final_url`	No
`headlines`	No
`clear_path1`	No
`clear_path2`	No
`customer_id`	No
`descriptions`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.13.3Sep 9, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Fully discloses that the tool returns a preview rather than directly applying changes, that creative replacements reset learning and trigger policy review, and that headlines/descriptions are list-replaced. These important side effects go well beyond the basic annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is detailed but well-organized with clear sections, warnings, and parameter semantics. Every sentence contributes necessary information, and the formatting makes important caveats easy to notice.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the tool's workflow (preview then confirm_and_apply), mutation constraints, Google's RSA limits, and the important distinction between URL/path edits and creative edits. It is sufficiently complete for an agent to use the tool correctly without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Thoroughly explains each parameter's semantics, including the empty-value/None no-op behavior, list-replacement behavior for headlines and descriptions, and the clear_path flags. Also documents the supported string and object formats for headline entries, which is essential for correct use.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool updates an existing responsive search ad in place and returns a preview, distinguishing it from creation-oriented siblings like draft_responsive_search_ad. The scope is specific and immediately understandable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides strong usage guidance including the need to call confirm_and_apply, the distinction between URL-only vs creative changes, and the requirement for at least one mutation. It does not explicitly contrast with draft_responsive_search_ad, but the 'existing RSA' language makes the intended use clear.

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

Deploy Server