google_ads_search_impression_share

Instructions

Implementation Reference

• tools/reporting/mcp_tools_reporting.py:423-493 (handler)

  The MCP tool handler for 'google_ads_search_impression_share'. This is the @mcp.tool()-decorated function that receives a customer_id, campaign_id (optional), and date_range, calls the ReportingManager to get impression share data, formats the output as a markdown report, and returns it as a string.

  @mcp.tool()
  def google_ads_search_impression_share(
      customer_id: str,
      campaign_id: Optional[str] = None,
      date_range: str = "LAST_30_DAYS"
  ) -> str:
      """
      Get search impression share metrics showing visibility in auctions.
  
      Args:
          customer_id: Customer ID (without hyphens)
          campaign_id: Optional campaign ID filter
          date_range: Date range
  
      Returns:
          Impression share data
  
      Example:
          google_ads_search_impression_share(
              customer_id="1234567890",
              date_range="LAST_30_DAYS"
          )
      """
      with performance_logger.track_operation('search_impression_share', customer_id=customer_id):
          try:
              client = get_auth_manager().get_client()
              reporting_manager = ReportingManager(client)
  
              result = reporting_manager.get_search_impression_share(
                  customer_id, campaign_id, date_range
              )
  
              # Audit log
              audit_logger.log_api_call(
                  customer_id=customer_id,
                  operation="search_impression_share",
                  resource_type="campaign",
                  action="read",
                  result="success"
              )
  
              output = f"# Search Impression Share Report\n\n"
              output += f"**Period**: {date_range}\n\n"
  
              for camp in result['campaigns']:
                  output += f"## {camp['campaign_name']}\n\n"
                  output += f"**Campaign ID**: {camp['campaign_id']}\n\n"
  
                  output += f"### Impression Share Metrics\n\n"
                  output += f"- **Overall IS**: {camp['impression_share'] * 100:.1f}%\n"
                  output += f"- **Exact Match IS**: {camp['exact_match_is'] * 100:.1f}%\n"
                  output += f"- **Top of Page IS**: {camp['top_is'] * 100:.1f}%\n"
                  output += f"- **Absolute Top IS**: {camp['absolute_top_is'] * 100:.1f}%\n\n"
  
                  output += f"### Lost Impression Share\n\n"
                  output += f"- **Lost to Rank**: {camp['rank_lost_is'] * 100:.1f}%\n"
                  output += f"- **Lost to Budget**: {camp['budget_lost_is'] * 100:.1f}%\n\n"
  
                  total_lost = camp['rank_lost_is'] + camp['budget_lost_is']
                  if total_lost > 0.3:
                      output += f"⚠️ **Missing {total_lost * 100:.0f}% of eligible impressions**\n\n"
                      if camp['budget_lost_is'] > camp['rank_lost_is']:
                          output += f"**Primary Issue**: Budget - Increase daily budget to capture more traffic\n\n"
                      else:
                          output += f"**Primary Issue**: Rank - Increase bids or improve Quality Score\n\n"
  
              return output
  
          except Exception as e:
              error_msg = ErrorHandler.handle_error(e, context="search_impression_share")
              return f"❌ Failed to get impression share: {error_msg}"

• tools/reporting/mcp_tools_reporting.py:34-41 (registration)

  The registration function 'register_reporting_tools(mcp)' that uses @mcp.tool() decorator to register 'google_ads_search_impression_share' as an MCP tool.

  def register_reporting_tools(mcp):
      """Register all reporting tools with the MCP server.
  
      Args:
          mcp: FastMCP server instance
      """
  
      @mcp.tool()

• managers/reporting_manager.py:453-505 (helper)

  The 'get_search_impression_share' method in ReportingManager that executes the GAQL query to fetch impression share metrics (search_impression_share, search_rank_lost_impression_share, search_budget_lost_impression_share, search_exact_match_impression_share, search_top_impression_share, search_absolute_top_impression_share) from the Google Ads API and returns campaign-level data.

  def get_search_impression_share(
      self,
      customer_id: str,
      campaign_id: Optional[str] = None,
      date_range: str = "LAST_30_DAYS"
  ) -> Dict[str, Any]:
      """Get search impression share metrics.
  
      Args:
          customer_id: Customer ID (without hyphens)
          campaign_id: Optional campaign ID filter
          date_range: Date range
  
      Returns:
          Impression share data
      """
      ga_service = self.client.get_service("GoogleAdsService")
  
      query = f"""
          SELECT
              campaign.id,
              campaign.name,
              metrics.impressions,
              metrics.search_impression_share,
              metrics.search_rank_lost_impression_share,
              metrics.search_budget_lost_impression_share,
              metrics.search_exact_match_impression_share,
              metrics.search_top_impression_share,
              metrics.search_absolute_top_impression_share
          FROM campaign
          WHERE segments.date DURING {date_range}
      """
  
      if campaign_id:
          query += f" AND campaign.id = {campaign_id}"
  
      response = ga_service.search(customer_id=customer_id, query=query)
  
      campaigns = []
      for row in response:
          campaigns.append({
              'campaign_id': str(row.campaign.id),
              'campaign_name': row.campaign.name,
              'impressions': row.metrics.impressions,
              'impression_share': row.metrics.search_impression_share,
              'rank_lost_is': row.metrics.search_rank_lost_impression_share,
              'budget_lost_is': row.metrics.search_budget_lost_impression_share,
              'exact_match_is': row.metrics.search_exact_match_impression_share,
              'top_is': row.metrics.search_top_impression_share,
              'absolute_top_is': row.metrics.search_absolute_top_impression_share
          })
  
      return {'campaigns': campaigns}

• tools/reporting/mcp_tools_reporting.py:424-428 (schema)

  The function signature with parameter types: customer_id (str), campaign_id (Optional[str]), date_range (str). These serve as the input schema for the tool.

  def google_ads_search_impression_share(
      customer_id: str,
      campaign_id: Optional[str] = None,
      date_range: str = "LAST_30_DAYS"
  ) -> str: