ArmaVita Meta Ads MCP

Instructions

Implementation Reference

• src/armavita_meta_ads_mcp/core/targeting_tools.py:241-384 (handler)

  The handler function that implements the 'estimate_audience_size' tool.

  async def estimate_audience_size(
      meta_access_token: Optional[str] = None,
      ad_account_id: Optional[str] = None,
      targeting: Optional[Dict[str, Any]] = None,
      optimization_goal: str = "REACH",
      interest_list: Optional[List[str]] = None,
      interest_fbid_list: Optional[List[str]] = None,
  ) -> str:
      """Estimate audience size for targeting specs or validate deprecated interest-list mode."""
      deprecated_interest_mode = _deprecated_interest_validation_mode(
          ad_account_id=ad_account_id,
          targeting=targeting,
          interest_list=interest_list,
          interest_fbid_list=interest_fbid_list,
      )
  
      if deprecated_interest_mode and not targeting:
          if not (interest_list or interest_fbid_list):
              return _as_json({"error": "No interest list or FBID list provided"})
  
          deprecated_interest_payload: Dict[str, Any] = {"type": "adinterestvalid"}
          if interest_list:
              deprecated_interest_payload["interest_list"] = json.dumps(list(interest_list))
          if interest_fbid_list:
              deprecated_interest_payload["interest_fbid_list"] = json.dumps(list(interest_fbid_list))
          payload = await make_api_request(
              "search",
              meta_access_token,
              deprecated_interest_payload,
          )
          return _as_json(payload)
  
      if not ad_account_id:
          return _as_json(
              {
                  "error": "ad_account_id is required for comprehensive audience estimation",
                  "details": "For simple interest validation, use interest_list or interest_fbid_list parameters",
              }
          )
  
      if not targeting:
          return _as_json(
              {
                  "error": "targeting specification is required for comprehensive audience estimation",
                  "example": {
                      "age_min": 25,
                      "age_max": 65,
                      "geo_locations": {"countries": ["US"]},
                      "flexible_spec": [{"interests": [{"id": "6003371567474"}]}],
                  },
              }
          )
  
      if not _has_location_or_custom_audience(targeting):
          return _as_json(
              {
                  "error": "Missing target audience location",
                  "details": "Select at least one location in targeting.geo_locations or include a custom audience.",
                  "action_required": "Add geo_locations with countries/regions/cities/zips or include custom_audiences.",
                  "example": {
                      "geo_locations": {"countries": ["US"]},
                      "age_min": 25,
                      "age_max": 65,
                  },
              }
          )
  
      fallback_disabled = os.environ.get("META_MCP_DISABLE_DELIVERY_FALLBACK", "1") == "1"
  
      try:
          reach_payload = await make_api_request(
              f"{ad_account_id}/reachestimate",
              meta_access_token,
              {"targeting_spec": targeting},
              method="GET",
          )
  
          if isinstance(reach_payload, dict) and reach_payload.get("error"):
              graph_error = _extract_graph_error(reach_payload)
              missing_location = _missing_location_error_payload(graph_error, ad_account_id)
              if missing_location:
                  return _as_json(missing_location)
  
              if fallback_disabled:
                  return _as_json(
                      {
                          "error": "Graph API returned an error for reachestimate",
                          "details": reach_payload.get("error"),
                          "endpoint_used": f"{ad_account_id}/reachestimate",
                          "request_params": {"has_targeting_spec": bool(targeting)},
                          "note": "delivery_estimate fallback disabled via META_MCP_DISABLE_DELIVERY_FALLBACK",
                      }
                  )
  
              fallback_result = await _run_delivery_estimate_fallback(
                  ad_account_id=ad_account_id,
                  meta_access_token=meta_access_token,
                  targeting=targeting,
                  optimization_goal=optimization_goal,
              )
              if fallback_result.get("success"):
                  return _as_json(fallback_result)
  
              return _as_json(
                  {
                      "error": "Graph API returned an error for reachestimate; delivery_estimate fallback did not return usable data",
                      "reachestimate_error": reach_payload.get("error"),
                      "fallback_endpoint_used": "delivery_estimate",
                      "fallback_raw_response": fallback_result,
                      "endpoint_used": f"{ad_account_id}/reachestimate",
                  }
              )
  
          normalized = _normalize_reach_result(
              reach_payload,
              ad_account_id=ad_account_id,
              targeting=targeting,
              optimization_goal=optimization_goal,
          )
          return _as_json(normalized)
  
      except Exception as exc:  # noqa: BLE001
          if not fallback_disabled:
              try:
                  fallback_result = await _run_delivery_estimate_fallback(
                      ad_account_id=ad_account_id,
                      meta_access_token=meta_access_token,
                      targeting=targeting,
                      optimization_goal=optimization_goal,
                  )
                  if fallback_result.get("success"):
                      return _as_json(fallback_result)
              except Exception:  # noqa: BLE001
                  pass
  
          return _as_json(
              {
                  "error": f"Failed to get audience estimation from reachestimate endpoint: {exc}",
                  "details": "Check targeting parameters and account permissions",
                  "error_type": "general_api_error",
                  "endpoint_used": f"{ad_account_id}/reachestimate",
              }
          )