google_ads_set_ad_group_url_suffix

Instructions

Implementation Reference

• tools/ad_groups/mcp_tools_ad_groups.py:552-601 (handler)

  MCP tool handler that sets the Final URL suffix for an ad group. Validates inputs, delegates to AdGroupManager.set_ad_group_url_suffix, logs the operation, invalidates cache, and returns a user-facing success/error message.

  @mcp.tool()
  def google_ads_set_ad_group_url_suffix(
      customer_id: str,
      ad_group_id: str,
      url_suffix: str
  ) -> str:
      """
      Set the Final URL suffix for an ad group. This overrides the campaign-level suffix for ads in this ad group.
  
      Args:
          customer_id: Customer ID (without hyphens)
          ad_group_id: Ad group ID to update
          url_suffix: URL parameters to append (e.g., 'utm_source=google&utm_medium=cpc&sm_kw=removable-bollards'). Pass empty string to clear and inherit campaign suffix.
  
      Returns:
          Success message with the applied suffix
      """
      with performance_logger.track_operation('set_ad_group_url_suffix', customer_id=customer_id):
          try:
              client = get_auth_manager().get_client()
              ad_group_manager = AdGroupManager(client)
  
              ad_group_manager.set_ad_group_url_suffix(
                  customer_id, ad_group_id, url_suffix
              )
  
              audit_logger.log_api_call(
                  customer_id=customer_id,
                  operation="set_ad_group_url_suffix",
                  resource_type="ad_group",
                  resource_id=ad_group_id,
                  action="update",
                  result="success",
                  details={'url_suffix': url_suffix}
              )
  
              get_cache_manager().invalidate(customer_id, ResourceType.AD_GROUP)
  
              if url_suffix:
                  return (
                      f"✅ Ad group {ad_group_id} Final URL suffix updated!\n\n"
                      f"**Suffix:** `?{url_suffix}`\n\n"
                      f"This overrides the campaign-level suffix for ads in this ad group."
                  )
              else:
                  return f"✅ Ad group {ad_group_id} Final URL suffix cleared. Will inherit campaign suffix."
  
          except Exception as e:
              error_msg = ErrorHandler.handle_error(e, context="set_ad_group_url_suffix")
              return f"❌ Failed to set ad group URL suffix: {error_msg}"

• managers/ad_group_manager.py:273-294 (helper)

  Helper method in AdGroupManager that delegates to update_ad_group with the final_url_suffix field.

  def set_ad_group_url_suffix(
      self,
      customer_id: str,
      ad_group_id: str,
      url_suffix: str
  ) -> Dict[str, Any]:
      """
      Set the Final URL suffix for an ad group.
  
      Args:
          customer_id: Customer ID
          ad_group_id: Ad group ID
          url_suffix: URL suffix string (e.g., 'sm_kw=removable-bollards')
  
      Returns:
          Operation result
      """
      return self.update_ad_group(
          customer_id,
          ad_group_id,
          {"final_url_suffix": url_suffix}
      )

• managers/ad_group_manager.py:146-221 (helper)

  Core update method in AdGroupManager that builds the Google Ads API AdGroupOperation, applies a field mask, and calls mutate_ad_groups. Handles final_url_suffix among other fields.

  def update_ad_group(
      self,
      customer_id: str,
      ad_group_id: str,
      updates: Dict[str, Any]
  ) -> Dict[str, Any]:
      """
      Update ad group settings.
  
      Args:
          customer_id: Customer ID
          ad_group_id: Ad group ID
          updates: Dictionary of fields to update (name, status, cpc_bid_micros, etc.)
  
      Returns:
          Operation result
      """
      ad_group_service = self.client.get_service("AdGroupService")
  
      ad_group_operation = self.client.get_type("AdGroupOperation")
      ad_group = ad_group_operation.update
  
      ad_group.resource_name = ad_group_service.ad_group_path(customer_id, ad_group_id)
  
      # Track updated fields for field mask
      update_mask_paths = []
  
      # Update name
      if "name" in updates:
          ad_group.name = updates["name"]
          update_mask_paths.append("name")
  
      # Update status
      if "status" in updates:
          ad_group.status = self.client.enums.AdGroupStatusEnum[updates["status"]]
          update_mask_paths.append("status")
  
      # Update CPC bid
      if "cpc_bid_micros" in updates:
          ad_group.cpc_bid_micros = updates["cpc_bid_micros"]
          update_mask_paths.append("cpc_bid_micros")
  
      # Update CPM bid
      if "cpm_bid_micros" in updates:
          ad_group.cpm_bid_micros = updates["cpm_bid_micros"]
          update_mask_paths.append("cpm_bid_micros")
  
      # Update CPV bid
      if "cpv_bid_micros" in updates:
          ad_group.cpv_bid_micros = updates["cpv_bid_micros"]
          update_mask_paths.append("cpv_bid_micros")
  
      # Update Final URL suffix
      if "final_url_suffix" in updates:
          ad_group.final_url_suffix = updates["final_url_suffix"]
          update_mask_paths.append("final_url_suffix")
  
      # Set field mask
      self.client.copy_from(
          ad_group_operation.update_mask,
          field_mask_pb2.FieldMask(paths=update_mask_paths)
      )
  
      # Update ad group
      response = ad_group_service.mutate_ad_groups(
          customer_id=customer_id,
          operations=[ad_group_operation]
      )
  
      logger.info(f"Updated ad group {ad_group_id}: {', '.join(update_mask_paths)}")
  
      return {
          "ad_group_id": ad_group_id,
          "updated_fields": update_mask_paths,
          "message": f"Ad group updated successfully"
      }

• tools/ad_groups/mcp_tools_ad_groups.py:24-26 (registration)

  Registration function that registers all ad group tools (including google_ads_set_ad_group_url_suffix) with the MCP server via @mcp.tool() decorators.

  def register_ad_group_tools(mcp: FastMCP):
      """Register ad group management tools with MCP server."""