create_negative_keywords_list

Create a new negative keywords list in the Metadata platform with Google Ads integration.

                PURPOSE:
                Batch create a negative keywords list that can be used in Google Ads campaigns to exclude specific search terms
                from triggering your ads. Use this tool to build negative keyword exclusion lists for campaign optimization
                and to prevent wasted ad spend on irrelevant searches.

                ACCOUNT LIMIT:
                ⚠️ MAXIMUM 20 NEGATIVE KEYWORDS LISTS PER ACCOUNT ⚠️
                Users can have a maximum of 20 negative keyword lists. The system will validate this limit
                before creating a new list and return an error if the limit has been reached.
                To create a new list, you must delete or archive existing lists to free up space.

                WHEN TO USE:
                - Create a new negative keywords list for Google Ads campaigns
                - Build competitor blocking lists (block competitor brand names)
                - Create category exclusions (block unwanted product categories)
                - Create seasonal exclusion lists (block irrelevant seasonal terms)
                - Build intent-based negative lists (block non-commercial searches)
                - Prevent wasted spend on irrelevant keywords
                - Manage brand protection by blocking misused terms

                KEY FEATURES:
                ✓ BATCH CREATION: Create one or more negative keywords in a single request
                ✓ MATCH TYPE CONTROL: Specify match type for all keywords (EXACT, PHRASE, BROAD)
                ✓ FLEXIBLE NAMING: Custom names for organizing negative keyword lists
                ✓ GOOGLE ADS INTEGRATION: Lists are created ready for use in Google Ads campaigns
                ✓ SIMPLE INTERFACE: Just provide keywords as strings, API handles formatting
                ✓ AUTOMATIC VALIDATION: System checks against 20-list limit before creation

                KEYWORD MATCH TYPES:
                The 'matchType' parameter controls how broadly the negative keyword blocks ads:

                1. EXACT ("Exact Match"):
                   - Blocks ads only for searches that exactly match the keyword
                   - Most restrictive and precise blocking
                   - Example: Keyword "free" with EXACT blocks only searches for "free", not "free shipping"
                   - Best for: High-value keyword protection, brand safety

                2. PHRASE ("Phrase Match"):
                   - Blocks ads when the keyword appears as a phrase within the search
                   - Moderate blocking scope
                   - Example: Keyword "vintage furniture" with PHRASE blocks "vintage furniture sale" but not "furniture vintage"
                   - Best for: Competitive category blocking

                3. BROAD ("Broad Match"):
                   - Blocks ads for searches containing any of the keyword terms
                   - Least restrictive and broadest blocking
                   - Example: Keyword "free" with BROAD blocks any search containing "free"
                   - Best for: General category exclusions

                MATCH TYPE SELECTION GUIDE:
                - Use EXACT for specific brand names or exact competitor terms
                - Use PHRASE for specific multi-word concepts or phrases
                - Use BROAD for general categories or very broad exclusions

                LIST NAMING CONVENTIONS:
                - Use descriptive names that indicate the list's purpose
                - Examples: "Competitor Brands", "Low Intent Keywords", "Seasonal Exclusions"
                - Avoid special characters - use hyphens or underscores for clarity
                - Keep names concise and meaningful

                BATCH SIZE RECOMMENDATIONS:
                - Small batches (1-10 keywords): For targeted blocking
                - Medium batches (10-50 keywords): For category-based lists
                - Large batches (50+ keywords): For comprehensive blocking lists
                - Maximum recommended: 100+ keywords per list

                NEGATIVE KEYWORDS VS POSITIVE KEYWORDS:
                - Positive keywords: Terms you WANT to show ads for (create_keywords)
                - Negative keywords: Terms you DON'T want to show ads for (create_negative_keywords_list)
                - Use together for optimal campaign performance

                COMMON USE CASES:
                1. Create competitor blocking list (EXACT match):
                   create_negative_keywords_list(
                     name="Competitor Brands",
                     keywords=["competitor a", "competitor b"],
                     match_type="EXACT"
                   )

                2. Create low-intent keyword list (BROAD match):
                   create_negative_keywords_list(
                     name="Low Intent Keywords",
                     keywords=["free", "how to", "tutorial"],
                     match_type="BROAD"
                   )

                3. Create job seeker exclusion list (PHRASE match):
                   create_negative_keywords_list(
                     name="Job Seekers",
                     keywords=["job search", "hiring", "career"],
                     match_type="PHRASE"
                   )

                4. Create seasonal exclusion list:
                   create_negative_keywords_list(
                     name="Summer Sale Exclusions",
                     keywords=["winter coats", "snow gear"],
                     match_type="PHRASE"
                   )

                5. Create product category exclusions:
                   create_negative_keywords_list(
                     name="Non-Ecommerce",
                     keywords=["news", "forum", "wikipedia"],
                     match_type="EXACT"
                   )

                PARAMETERS:
                - name: Required. Name of the negative keywords list (string)
                        Example: "Competitor Brands", "Low Intent Keywords"
                        Use descriptive, meaningful names for easy identification

                - keywords: Required. Array of keyword strings to block
                           Example: ["raichu", "blastoise", "charizard"]
                           - Minimum: 1 keyword
                           - Recommended maximum: 100+ keywords per request
                           - Each item is a simple string representing the keyword

                - matchType: Required. Match type for all keywords - EXACT, PHRASE, or BROAD
                            Example: "EXACT"
                            Options: EXACT (exact match), PHRASE (phrase match), BROAD (broad match)

                RESPONSE FORMAT:
                Returns a response containing:
                - Confirmation of the negative keywords list creation
                - List ID for future reference and management
                - Success/failure status
                - Details of keywords added to the list

                VALIDATION NOTES:
                - Name is required and must be a non-empty string
                - Keywords array must have at least 1 keyword
                - matchType must be exactly one of: EXACT, PHRASE, BROAD (case-sensitive)
                - Empty strings in keyword list are not allowed
                - Duplicate keywords in the batch will be handled by the API

                PERFORMANCE TIPS:
                - Create lists with related keywords for better organization
                - Group keywords by blocking strategy (competitor, seasonal, intent-based)
                - Use EXACT match for high-value keyword protection
                - Use BROAD match for general category exclusions
                - Review created lists regularly and update as needed
                - Can use list_negative_keywords_list() to verify creation

                INTEGRATION WITH OTHER TOOLS:
                - Use list_negative_keywords_list() to find and manage existing lists
                - Use create_keywords() for positive keyword lists
                - Combine with campaign creation for comprehensive keyword strategies

                EXAMPLES:
                - create_negative_keywords_list(name="Competitors", keywords=["competitor1"], matchType="EXACT")
                - create_negative_keywords_list(name="Free Content", keywords=["free", "no cost"], matchType="BROAD")
                - create_negative_keywords_list(name="Brand Safety", keywords=["controversial term"], matchType="PHRASE")

                CHANNEL SCOPE:
                BOTH search channels are supported: pass channel=MICROSOFT_ADS for Microsoft
                Ads (Bing) and channel=GOOGLE_ADS for Google. The two channels hold SEPARATE
                lists, so never substitute one channel for the other to get "close enough"
                results.