google_ads_get_recommendation_history

Instructions

Implementation Reference

• tools/automation/mcp_tools_automation.py:678-751 (handler)

  The @mcp.tool() decorated handler function for google_ads_get_recommendation_history. Calls AutomationManager.get_recommendation_history() and formats the response with change event details (date, user, client, resource, action).

  @mcp.tool()
  def google_ads_get_recommendation_history(
      customer_id: str,
      start_date: str,
      end_date: str
  ) -> str:
      """
      Get history of applied and dismissed recommendations.
  
      This shows what recommendations were applied or dismissed in a given time period,
      along with who made the changes.
  
      Args:
          customer_id: Customer ID (without hyphens)
          start_date: Start date (YYYY-MM-DD)
          end_date: End date (YYYY-MM-DD)
  
      Returns:
          Recommendation change history
  
      Example:
          google_ads_get_recommendation_history(
              customer_id="1234567890",
              start_date="2025-11-01",
              end_date="2025-12-16"
          )
      """
      with performance_logger.track_operation('get_recommendation_history', customer_id=customer_id):
          try:
              client = get_auth_manager().get_client()
              automation_manager = AutomationManager(client)
  
              history = automation_manager.get_recommendation_history(
                  customer_id,
                  start_date,
                  end_date
              )
  
              # Audit log
              audit_logger.log_api_call(
                  customer_id=customer_id,
                  operation="get_recommendation_history",
                  resource_type="recommendation",
                  action="read",
                  result="success",
                  details={'count': len(history)}
              )
  
              if not history:
                  return f"No recommendation changes found between {start_date} and {end_date}."
  
              # Format response
              output = f"# Recommendation Change History\n\n"
              output += f"**Period**: {start_date} to {end_date}\n"
              output += f"**Total Changes**: {len(history)}\n\n"
  
              for i, event in enumerate(history, 1):
                  output += f"## {i}. {event['date_time']}\n\n"
                  output += f"- **User**: {event['user_email']}\n"
                  output += f"- **Client**: {event['client_type']}\n"
                  output += f"- **Resource**: {event['resource_name']}\n"
  
                  if event['old_type']:
                      output += f"- **Action**: Removed {event['old_type']} recommendation\n"
                  elif event['new_type']:
                      output += f"- **Action**: Applied {event['new_type']} recommendation\n"
  
                  output += "\n"
  
              return output
  
          except Exception as e:
              error_msg = ErrorHandler.handle_error(e, context="get_recommendation_history")
              return f"❌ Failed to get recommendation history: {error_msg}"

• managers/automation_manager.py:476-527 (helper)

  The AutomationManager.get_recommendation_history() helper method. Executes a GAQL query against the Google Ads API's change_event resource filtered by RECOMMENDATION type and date range, returning a list of history entries with details like user_email, client_type, old_type, and new_type.

  def get_recommendation_history(
      self,
      customer_id: str,
      start_date: str,
      end_date: str
  ) -> List[Dict[str, Any]]:
      """Get history of applied/dismissed recommendations.
  
      Args:
          customer_id: Customer ID (without hyphens)
          start_date: Start date (YYYY-MM-DD)
          end_date: End date (YYYY-MM-DD)
  
      Returns:
          List of recommendation history entries
      """
      ga_service = self.client.get_service("GoogleAdsService")
  
      query = f"""
          SELECT
              change_event.resource_name,
              change_event.change_date_time,
              change_event.change_resource_name,
              change_event.change_resource_type,
              change_event.user_email,
              change_event.client_type,
              change_event.old_resource.recommendation.type,
              change_event.new_resource.recommendation.type
          FROM change_event
          WHERE change_event.change_resource_type = 'RECOMMENDATION'
          AND change_event.change_date_time >= '{start_date}'
          AND change_event.change_date_time <= '{end_date}'
          ORDER BY change_event.change_date_time DESC
      """
  
      response = ga_service.search(customer_id=customer_id, query=query)
  
      history = []
      for row in response:
          event = row.change_event
  
          history.append({
              'date_time': event.change_date_time,
              'resource_name': event.change_resource_name,
              'resource_type': event.change_resource_type.name,
              'user_email': event.user_email,
              'client_type': event.client_type.name,
              'old_type': event.old_resource.recommendation.type.name if event.old_resource.recommendation else None,
              'new_type': event.new_resource.recommendation.type.name if event.new_resource.recommendation else None
          })
  
      return history

• google_ads_mcp.py:480-495 (registration)

  The registration entry for the automation module. The tuple ("automation", "tools.automation.mcp_tools_automation", "register_automation_tools") causes the tool to be loaded and registered with the MCP server.

  _TOOL_MODULES = [
      ("campaigns",     "tools.campaigns.mcp_tools_campaigns",         "register_campaign_tools"),
      ("ad_groups",     "tools.ad_groups.mcp_tools_ad_groups",         "register_ad_group_tools"),
      ("keywords",      "tools.keywords.mcp_tools_keywords",           "register_keyword_tools"),
      ("ads",           "tools.ads.mcp_tools_ads",                     "register_ad_tools"),
      ("bidding",       "tools.bidding.mcp_tools_bidding",             "register_bidding_tools"),
      ("automation",    "tools.automation.mcp_tools_automation",       "register_automation_tools"),
      ("audiences",     "tools.audiences.mcp_tools_audiences",         "register_audience_tools"),
      ("conversions",   "tools.conversions.mcp_tools_conversions",     "register_conversion_tools"),
      ("reporting",     "tools.reporting.mcp_tools_reporting",         "register_reporting_tools"),
      ("insights",      "tools.insights.mcp_tools_insights",           "register_insights_tools"),
      ("batch",         "tools.batch.mcp_tools_batch",                 "register_batch_tools"),
      ("shopping_pmax", "tools.shopping_pmax.mcp_tools_shopping_pmax", "register_shopping_pmax_tools"),
      ("extensions",    "tools.extensions.mcp_tools_extensions",       "register_extension_tools"),
      ("local_app",     "tools.local_app.mcp_tools_local_app",         "register_local_app_tools"),
  ]

• tools/automation/mcp_tools_automation.py:37-42 (registration)

  The register_automation_tools() function that is called to register all automation tools, including google_ads_get_recommendation_history via the @mcp.tool() decorator.

  def register_automation_tools(mcp):
      """Register all automation and optimization tools with the MCP server.
  
      Args:
          mcp: FastMCP server instance
      """