add_negative_keywords
Destructive
Block unwanted search terms by adding negative keywords to paid media campaigns, preventing irrelevant traffic and improving ad performance.
Instructions
Add negative keywords to block unwanted search terms.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | Campaign ID | |
| keywords | Yes | Negative keywords to add | |
| level | No | Level to apply negatives (default: CAMPAIGN) |
Implementation Reference
- src/index.ts:819-827 (handler)The argMapper function for add_negative_keywords tool that converts tool arguments (campaign_id, keywords array, and optional level) into CLI arguments for the google_ads_add_negative_keywords script
add_negative_keywords: { script: "google_ads_add_negative_keywords", platform: "google", argMapper: (a) => { const cliArgs: string[] = ["--campaign-id", a.campaign_id as string]; (a.keywords as string[] || []).forEach((k) => cliArgs.push("--keyword", k)); if (a.level) cliArgs.push("--level", a.level as string); return cliArgs; }, - src/index.ts:337-360 (schema)Tool schema definition with name, description, destructiveHint annotation, and inputSchema specifying campaign_id (required string), keywords (required array of strings), and level (optional enum: CAMPAIGN or AD_GROUP)
name: "add_negative_keywords", description: "Add negative keywords to block unwanted search terms.", annotations: { destructiveHint: true }, inputSchema: { type: "object" as const, properties: { campaign_id: { type: "string", description: "Campaign ID", }, keywords: { type: "array", items: { type: "string" }, description: "Negative keywords to add", }, level: { type: "string", enum: ["CAMPAIGN", "AD_GROUP"], description: "Level to apply negatives (default: CAMPAIGN)", }, }, required: ["campaign_id", "keywords"], }, }, - src/index.ts:701-956 (handler)Main handleTool function that orchestrates tool execution: looks up tool mappings, calls argMapper to convert args, and invokes callSynterAPI with script name and arguments
async function handleTool( name: string, args: ToolArgs ): Promise<Record<string, unknown>> { // Map tool names to script names and handle parameters const toolMappings: Record<string, { script: string; platform?: string; argMapper?: (args: ToolArgs) => string[] }> = { // Campaign management list_campaigns: { script: "google_ads_list_campaigns", platform: (args.platform as string) || "google", argMapper: (a) => { const cliArgs: string[] = []; if (a.status) cliArgs.push("--status", a.status as string); if (a.limit) cliArgs.push("--limit", String(a.limit)); return cliArgs; }, }, create_search_campaign: { script: "google_ads_create_search_campaign", platform: "google", argMapper: (a) => { const cliArgs: string[] = [ "--campaign-name", a.campaign_name as string, "--daily-budget", String(a.daily_budget), "--final-url", a.final_url as string, ]; (a.keywords as string[] || []).forEach((k) => cliArgs.push("--keyword", k)); (a.headlines as string[] || []).forEach((h) => cliArgs.push("--headline", h)); (a.descriptions as string[] || []).forEach((d) => cliArgs.push("--description", d)); (a.geo_targets as string[] || []).forEach((g) => cliArgs.push("--geo-targets", g)); return cliArgs; }, }, create_display_campaign: { script: "google_ads_create_display_campaign", platform: "google", argMapper: (a) => { const cliArgs: string[] = [ "--campaign-name", a.campaign_name as string, "--daily-budget", String(a.daily_budget), "--business-name", a.business_name as string, "--final-url", a.final_url as string, ]; if (a.landscape_image_url) cliArgs.push("--landscape-image", a.landscape_image_url as string); if (a.square_image_url) cliArgs.push("--square-image", a.square_image_url as string); (a.headlines as string[] || []).forEach((h) => cliArgs.push("--headline", h)); (a.descriptions as string[] || []).forEach((d) => cliArgs.push("--description", d)); (a.geo_targets as string[] || []).forEach((g) => cliArgs.push("--geo-targets", g)); return cliArgs; }, }, create_pmax_campaign: { script: "google_ads_create_pmax_campaign", platform: "google", argMapper: (a) => { const cliArgs: string[] = [ "--campaign-name", a.campaign_name as string, "--daily-budget", String(a.daily_budget), "--business-name", a.business_name as string, "--final-url", a.final_url as string, "--long-headline", a.long_headline as string, ]; if (a.landscape_image_url) cliArgs.push("--landscape-image-url", a.landscape_image_url as string); if (a.square_image_url) cliArgs.push("--square-image-url", a.square_image_url as string); if (a.logo_url) cliArgs.push("--logo-url", a.logo_url as string); if (a.target_cpa) cliArgs.push("--target-cpa", String(a.target_cpa)); (a.headlines as string[] || []).forEach((h) => cliArgs.push("--headline", h)); (a.descriptions as string[] || []).forEach((d) => cliArgs.push("--description", d)); (a.geo_targets as string[] || []).forEach((g) => cliArgs.push("--geo-targets", g)); return cliArgs; }, }, pause_campaign: { script: "pause_campaign", platform: "google", argMapper: (a) => ["--campaign-id", a.campaign_id as string], }, update_campaign_budget: { script: "update_campaign_budget", platform: "google", argMapper: (a) => [ "--campaign-id", a.campaign_id as string, "--budget", String(a.daily_budget), ], }, // Performance get_performance: { script: "pull_google_ads_data", platform: "google", argMapper: (a) => { const cliArgs: string[] = []; if (a.campaign_id) cliArgs.push("--campaign-id", a.campaign_id as string); if (a.date_range) cliArgs.push("--date-range", a.date_range as string); return cliArgs; }, }, get_daily_spend: { script: "get_account_daily_spend", platform: "google", argMapper: (a) => { const cliArgs: string[] = []; if (a.days) cliArgs.push("--days", String(a.days)); return cliArgs; }, }, // Keywords add_keywords: { script: "google_ads_add_keywords", platform: "google", argMapper: (a) => { const cliArgs: string[] = ["--ad-group-id", a.ad_group_id as string]; (a.keywords as string[] || []).forEach((k) => cliArgs.push("--keyword", k)); if (a.match_type) cliArgs.push("--match-type", a.match_type as string); return cliArgs; }, }, add_negative_keywords: { script: "google_ads_add_negative_keywords", platform: "google", argMapper: (a) => { const cliArgs: string[] = ["--campaign-id", a.campaign_id as string]; (a.keywords as string[] || []).forEach((k) => cliArgs.push("--keyword", k)); if (a.level) cliArgs.push("--level", a.level as string); return cliArgs; }, }, // Conversions create_conversion: { script: "google_ads_create_conversion", platform: "google", argMapper: (a) => { const cliArgs: string[] = ["--name", a.name as string]; if (a.value) cliArgs.push("--value", String(a.value)); if (a.category) cliArgs.push("--category", a.category as string); return cliArgs; }, }, list_conversions: { script: "google_ads_list_conversions", platform: "google", argMapper: () => [], }, diagnose_tracking: { script: "diagnose_conversion_tracking", argMapper: (a) => ["--url", a.url as string], }, // Creative generation generate_image: { script: "generate_image", argMapper: (a) => { const cliArgs: string[] = ["--prompt", a.prompt as string]; if (a.size) cliArgs.push("--size", a.size as string); if (a.provider) cliArgs.push("--provider", a.provider as string); if (a.name) cliArgs.push("--name", a.name as string); return cliArgs; }, }, generate_video: { script: "generate_video_ad", argMapper: (a) => { const cliArgs: string[] = [ "--product", a.product_name as string, "--benefit", a.key_benefit as string, ]; if (a.concept) cliArgs.push("--concept", a.concept as string); if (a.target_audience) cliArgs.push("--audience", a.target_audience as string); if (a.duration) cliArgs.push("--duration", String(a.duration)); if (a.provider) cliArgs.push("--provider", a.provider as string); return cliArgs; }, }, // Meta create_meta_campaign: { script: "meta_ads_create_campaign", platform: "meta", argMapper: (a) => [ "--name", a.name as string, "--objective", a.objective as string, "--daily-budget", String(a.daily_budget), ], }, // LinkedIn create_linkedin_campaign: { script: "linkedin_ads_create_campaign_complete", platform: "linkedin", argMapper: (a) => { const cliArgs: string[] = [ "--name", a.name as string, "--objective", a.objective as string, "--daily-budget", String(a.daily_budget), ]; (a.target_company_sizes as string[] || []).forEach((s) => cliArgs.push("--company-size", s)); (a.target_industries as string[] || []).forEach((i) => cliArgs.push("--industry", i)); (a.target_job_functions as string[] || []).forEach((j) => cliArgs.push("--job-function", j)); return cliArgs; }, }, // Reddit create_reddit_campaign: { script: "reddit_ads_create_campaign", platform: "reddit", argMapper: (a) => { const cliArgs: string[] = [ "--name", a.name as string, "--objective", a.objective as string, "--daily-budget", String(a.daily_budget), ]; (a.subreddits as string[] || []).forEach((s) => cliArgs.push("--subreddit", s)); (a.interests as string[] || []).forEach((i) => cliArgs.push("--interest", i)); return cliArgs; }, }, // Utility list_ad_accounts: { script: "google_ads_list_customers", platform: "google", argMapper: () => [], }, upload_image: { script: "google_ads_upload_image_asset", platform: "google", argMapper: (a) => [ "--image-url", a.image_url as string, "--asset-name", a.asset_name as string, ], }, run_tool: { script: args.script_name as string, platform: (args.platform as string) || undefined, argMapper: (a) => (a.args as string[]) || [], }, }; const mapping = toolMappings[name]; if (!mapping) { throw new Error(`Unknown tool: ${name}`); } const scriptArgs = mapping.argMapper ? mapping.argMapper(args) : []; return callSynterAPI("tools/run", { script_name: mapping.script, args: scriptArgs, platform: typeof mapping.platform === "function" ? mapping.platform : mapping.platform || (args.platform as string), }); } - src/index.ts:666-693 (helper)callSynterAPI helper function that makes HTTP POST requests to the Synter API endpoint with authentication, handling errors and returning JSON responses
async function callSynterAPI( endpoint: string, body: Record<string, unknown> ): Promise<Record<string, unknown>> { if (!SYNTER_API_KEY) { throw new Error( "SYNTER_API_KEY not set. Get your API key at https://syntermedia.ai/developer" ); } const response = await fetch(`${SYNTER_API_URL}/api/v1/${endpoint}`, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${SYNTER_API_KEY}`, }, body: JSON.stringify(body), }); const data = await response.json() as Record<string, unknown>; if (!response.ok) { const errorMsg = (data.error as string) || (data.message as string) || `API error: ${response.status}`; throw new Error(errorMsg); } return data; }