google_ads_get_conversion_performance

Instructions

Implementation Reference

• tools/conversions/mcp_tools_conversions.py:459-523 (handler)

  The MCP tool handler that registers and implements the google_ads_get_conversion_performance tool. It calls conversion_manager.get_conversion_performance() and formats the results as a markdown string.

  @mcp.tool()
  def google_ads_get_conversion_performance(
      customer_id: str,
      conversion_action_id: Optional[str] = None,
      date_range: str = "LAST_30_DAYS"
  ) -> str:
      """
      Get conversion performance metrics.
  
      Args:
          customer_id: Customer ID (without hyphens)
          conversion_action_id: Optional specific conversion
          date_range: Date range
  
      Returns:
          Conversion performance data
  
      Example:
          google_ads_get_conversion_performance(
              customer_id="1234567890",
              date_range="LAST_30_DAYS"
          )
      """
      with performance_logger.track_operation('get_conversion_performance', customer_id=customer_id):
          try:
              client = get_auth_manager().get_client()
              conversion_manager = ConversionManager(client)
  
              conversions = conversion_manager.get_conversion_performance(
                  customer_id,
                  conversion_action_id,
                  date_range
              )
  
              # Audit log
              audit_logger.log_api_call(
                  customer_id=customer_id,
                  operation="get_conversion_performance",
                  resource_type="conversion_action",
                  action="read",
                  result="success",
                  details={'count': len(conversions)}
              )
  
              if not conversions:
                  return "No conversion data found for the specified period."
  
              output = f"# Conversion Performance\n\n"
              output += f"**Date Range**: {date_range}\n"
              output += f"**Conversions**: {len(conversions)}\n\n"
  
              for conv in conversions:
                  output += f"## {conv['name']} ({conv['category']})\n\n"
                  output += f"- **Conversions**: {conv['conversions']:.1f}\n"
                  output += f"- **Conversion Value**: ${conv['conversions_value']:,.2f}\n"
                  output += f"- **Cost per Conversion**: ${conv['cost_per_conversion']:.2f}\n"
                  output += f"- **Conversion Rate**: {conv['conversion_rate'] * 100:.2f}%\n"
                  output += f"- **Value per Conversion**: ${conv['value_per_conversion']:.2f}\n"
                  output += f"- **All Conversions**: {conv['all_conversions']:.1f}\n\n"
  
              return output
  
          except Exception as e:
              error_msg = ErrorHandler.handle_error(e, context="get_conversion_performance")
              return f"❌ Failed to get conversion performance: {error_msg}"

• managers/conversion_manager.py:316-370 (helper)

  The backend helper method on ConversionManager that runs the GAQL query against the Google Ads API to fetch conversion performance metrics (conversions, conversions_value, cost_per_conversion, conversion_rate, value_per_conversion, all_conversions).

  def get_conversion_performance(
      self,
      customer_id: str,
      conversion_action_id: Optional[str] = None,
      date_range: str = "LAST_30_DAYS"
  ) -> List[Dict[str, Any]]:
      """Get conversion performance metrics.
  
      Args:
          customer_id: Customer ID (without hyphens)
          conversion_action_id: Optional specific conversion action
          date_range: Date range
  
      Returns:
          List of conversion performance data
      """
      ga_service = self.client.get_service("GoogleAdsService")
  
      query = f"""
          SELECT
              conversion_action.id,
              conversion_action.name,
              conversion_action.category,
              metrics.conversions,
              metrics.conversions_value,
              metrics.cost_per_conversion,
              metrics.conversions_from_interactions_rate,
              metrics.value_per_conversion,
              metrics.all_conversions,
              metrics.all_conversions_value
          FROM conversion_action
          WHERE segments.date DURING {date_range}
      """
  
      if conversion_action_id:
          query += f" AND conversion_action.id = {conversion_action_id}"
  
      response = ga_service.search(customer_id=customer_id, query=query)
  
      conversions = []
      for row in response:
          conversions.append({
              'conversion_action_id': str(row.conversion_action.id),
              'name': row.conversion_action.name,
              'category': row.conversion_action.category.name,
              'conversions': row.metrics.conversions,
              'conversions_value': row.metrics.conversions_value,
              'cost_per_conversion': row.metrics.cost_per_conversion,
              'conversion_rate': row.metrics.conversions_from_interactions_rate,
              'value_per_conversion': row.metrics.value_per_conversion,
              'all_conversions': row.metrics.all_conversions,
              'all_conversions_value': row.metrics.all_conversions_value
          })
  
      return conversions

• google_ads_mcp.py:488-488 (registration)

  Registration entry in _TOOL_MODULES that maps the conversions module to its register_conversion_tools function, which gets called by _register_all_modular_tools().

  ("conversions",   "tools.conversions.mcp_tools_conversions",     "register_conversion_tools"),

• tools/conversions/mcp_tools_conversions.py:38-42 (schema)

  The registration function that decorates the handler with @mcp.tool(), defining the tool's input schema (customer_id, conversion_action_id, date_range) and output type (str).

  def register_conversion_tools(mcp):
      """Register all conversion tracking tools with the MCP server.
  
      Args:
          mcp: FastMCP server instance