google_ads_add_callout_extension

Instructions

[
  {"callout_text": "Free Shipping"},
  {"callout_text": "24/7 Support"},
  {"callout_text": "Price Match Guarantee"}
]

Implementation Reference

• tools/extensions/mcp_tools_extensions.py:152-257 (handler)

  The MCP tool handler function 'google_ads_add_callout_extension' that accepts customer_id, campaign_id, and callouts_json, validates input, creates CalloutConfig objects, and delegates to ExtensionsManager.add_callout_extension.

  @mcp.tool()
  def google_ads_add_callout_extension(
      customer_id: str,
      campaign_id: str,
      callouts_json: str
  ) -> str:
      """Add callout extensions to a campaign.
  
      Callouts are short, descriptive snippets that highlight key benefits,
      features, or offerings. They appear below your ad text.
  
      Args:
          customer_id: Google Ads customer ID (10 digits, no hyphens)
          campaign_id: Campaign ID to add callouts
          callouts_json: JSON array of callout texts
  
      Callout Configuration Schema:
      ```json
      [
        {"callout_text": "Free Shipping"},
        {"callout_text": "24/7 Support"},
        {"callout_text": "Price Match Guarantee"}
      ]
      ```
  
      Requirements:
      - Callout text: 1-25 characters
      - Minimum 2 callouts recommended
      - Maximum 10 callouts per campaign
  
      Returns:
          Callout extension creation result
  
      Example:
          google_ads_add_callout_extension(
              customer_id="1234567890",
              campaign_id="12345678",
              callouts_json='[{"callout_text": "Free Shipping"}, {"callout_text": "24/7 Support"}]'
          )
      """
      with performance_logger.track_operation('add_callout_extension', customer_id=customer_id):
          try:
              client = get_auth_manager().get_client()
              extensions_manager = ExtensionsManager(client)
  
              # Parse callouts JSON
              try:
                  callouts_data = json.loads(callouts_json)
              except json.JSONDecodeError as e:
                  return f"❌ Invalid JSON format: {str(e)}"
  
              if not isinstance(callouts_data, list):
                  return "❌ callouts_json must be a JSON array"
  
              # Validate and create callout configs
              callouts = []
              for i, co in enumerate(callouts_data):
                  if 'callout_text' not in co:
                      return f"❌ Callout {i+1} missing callout_text field"
  
                  if len(co['callout_text']) > 25:
                      return f"❌ Callout {i+1} exceeds 25 characters: '{co['callout_text']}'"
  
                  callouts.append(CalloutConfig(callout_text=co['callout_text']))
  
              if len(callouts) > 10:
                  return "❌ Maximum 10 callouts per campaign"
  
              result = extensions_manager.add_callout_extension(
                  customer_id=customer_id,
                  campaign_id=campaign_id,
                  callouts=callouts
              )
  
              audit_logger.log_api_call(
                  customer_id=customer_id,
                  operation='add_callout_extension',
                  campaign_id=campaign_id,
                  status='success'
              )
  
              output = f"# 💬 Callout Extensions Added\n\n"
              output += f"**Campaign ID**: {result['campaign_id']}\n"
              output += f"**Callouts Added**: {result['callouts_added']}\n\n"
  
              output += "## Callouts\n\n"
              for co in result['callouts']:
                  output += f"- {co['callout_text']}\n"
  
              output += "\n## Why Use Callouts?\n\n"
              output += "✅ **Highlight Benefits** - Showcase what makes you unique\n"
              output += "✅ **Build Trust** - Display guarantees and certifications\n"
              output += "✅ **Save Space** - Concise messaging in 25 characters\n"
              output += "✅ **Increase Relevance** - Match user search intent\n\n"
  
              output += "💡 **Best Practices**:\n"
              output += "- Use action-oriented language\n"
              output += "- Focus on unique value propositions\n"
              output += "- Avoid redundancy with ad copy\n"
              output += "- Test different callout combinations\n"
  
              return output
  
          except Exception as e:
              error_msg = ErrorHandler.handle_error(e, context="add_callout_extension")
              return f"❌ Failed to add callout extensions: {error_msg}"

• managers/extensions_manager.py:54-57 (schema)

  The CalloutConfig dataclass defining the schema for a callout extension with a required callout_text field.

  @dataclass
  class CalloutConfig:
      """Configuration for callout extension."""
      callout_text: str

• managers/extensions_manager.py:145-205 (helper)

  The ExtensionsManager.add_callout_extension helper method that creates callout assets via the Google Ads API (AssetService) and links them to campaigns (CampaignAssetService).

  def add_callout_extension(
      self,
      customer_id: str,
      campaign_id: str,
      callouts: List[CalloutConfig]
  ) -> Dict[str, Any]:
      """Add callout extensions to a campaign.
  
      Args:
          customer_id: Customer ID (without hyphens)
          campaign_id: Campaign ID
          callouts: List of callout configurations
  
      Returns:
          Created callout extension details
      """
      asset_service = self.client.get_service("AssetService")
      campaign_asset_service = self.client.get_service("CampaignAssetService")
  
      created_callouts = []
  
      for callout in callouts:
          # Create callout asset
          asset_operation = self.client.get_type("AssetOperation")
          asset = asset_operation.create
  
          asset.type_ = self.client.enums.AssetTypeEnum.CALLOUT
          asset.callout_asset.callout_text = callout.callout_text
  
          # Create asset
          asset_response = asset_service.mutate_assets(
              customer_id=customer_id,
              operations=[asset_operation]
          )
          asset_resource_name = asset_response.results[0].resource_name
  
          # Link asset to campaign
          campaign_asset_operation = self.client.get_type("CampaignAssetOperation")
          campaign_asset = campaign_asset_operation.create
  
          campaign_asset.asset = asset_resource_name
          campaign_asset.campaign = self.client.get_service("CampaignService").campaign_path(
              customer_id, campaign_id
          )
          campaign_asset.field_type = self.client.enums.AssetFieldTypeEnum.CALLOUT
  
          campaign_asset_service.mutate_campaign_assets(
              customer_id=customer_id,
              operations=[campaign_asset_operation]
          )
  
          created_callouts.append({
              'callout_text': callout.callout_text,
              'asset_resource_name': asset_resource_name
          })
  
      return {
          'campaign_id': campaign_id,
          'callouts_added': len(created_callouts),
          'callouts': created_callouts
      }

• tools/extensions/mcp_tools_extensions.py:34-36 (registration)

  The register_extension_tools function that uses the @mcp.tool() decorator to register google_ads_add_callout_extension as an MCP tool.

  def register_extension_tools(mcp):
      """Register all ad extension MCP tools."""