hypd_search_help
ChatGPTSearches HYPD's help center for articles that answer a question about HYPD itself: connecting or reconnecting ad accounts, plans, billing and credits, privacy and data access, what HYPD can do, and setting HYPD up in Claude, ChatGPT or other AI clients. Returns the matching articles' text and links; answer from them and cite them. Not for advertising advice or the user's account data; use the platform tools for those.
init
ChatGPTReturns the Microsoft Ads guide — call it first in a new conversation. Covers what each msads_* tool reads, the workflow (list accounts, walk campaign structure, then run performance reports), what to do when no accounts are connected, and starter prompts.
msads_apply_change_draft
ChatGPTApplies one approved Change Draft once HYPD has checked the account again, stopping on its own if the account changed since the approval: it runs at once and returns what landed. Each draft applies once; never retry a failed or uncertain one, check the account first.
msads_approve_change_draft
ChatGPTRecords the user's explicit approval of one Change Draft, or with draft_ids of several from one request given one yes (all or none; an enable on its own), in their own words, after you showed them a short summary, the reasoning and every warning. Only an approved draft can be applied. Never paraphrase the confirmation or supply it on the user's behalf.
msads_draft_ad_changes
ChatGPTStep 1 of 3 for changing ads. Operations, each naming campaign_id: edit_ad changes a responsive search ad in place (headlines and descriptions as the whole new list, final_url, path1, path2; only what you send changes; a pin left out stays); create_ad adds one to an existing ad group; create_ad_group adds an ad group with its keywords and 1-3 ads to an existing Search campaign. Everything new lands PAUSED; enabling it is a separate status draft. 3-15 headlines of up to 30 characters, 2-4 descriptions of up to 90, paths up to 15, no text twice. Nothing changes yet. A new ad group is built in steps: if one fails, what landed stays paused and the result says what did not. validated: show the user the diff and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_asset_group_changes
ChatGPTStep 1 of 3 for changing Performance Max asset groups. create_asset_group adds one to an existing Performance Max campaign: name, final_url, 3-15 headlines, 1-5 long headlines, 2-5 descriptions, business_name, call_to_action, optional paths, and library image ids by role from msads_list_images (at least one landscape and one square). It lands PAUSED. edit_asset_group (ids from msads_list_asset_groups) changes only what it names: name, final_url, business_name, call_to_action, paths (empty clears), status (enabled or paused), headlines, long_headlines or descriptions (each the whole new set), add_images and remove_images by role. Nothing changes yet. Checks image shapes, sizes and Microsoft's image limits. validated: show the user the diff and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_bidding_changes
ChatGPTStep 1 of 3 for changing bids. Operations: target campaign sets the campaign's whole strategy (enhanced_cpc; manual_cpc, Audience only; max_clicks with optional cpc_bid_ceiling; maximize_conversions with optional target_cpa; maximize_conversion_value with optional target_roas as a ratio), moving it off any portfolio; target portfolio changes one target on a shared strategy (ids from msads_list_bid_strategies); target ad_group sets its default max CPC (with campaign_id). Money in account currency, never micros. Nothing changes yet. A portfolio moves every campaign on it: blocked names them; show the user every one, then draft again with acknowledged_campaign_ids. validated: show the user the diff and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_budget_changes
ChatGPTStep 1 of 3 for setting campaign budgets. Pass campaign_id and the new DAILY amount in the account's currency, never micros; the draft finds the budget, the campaign's own or the shared one it draws on. Reads each budget now and runs HYPD's guardrails (spend share, budget utilization, step size); nothing changes yet. A shared budget moves every campaign on it: blocked names them; show the user every one, then draft again with acknowledged_campaign_ids. validated: show the user the diff, spend_impact and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_campaign_build
ChatGPTStep 1 of 3 for building a new campaign: its own daily budget, ad languages (or All), locations by id from msads_find_locations. type search: a bid strategy and ad groups with keywords and 1-3 responsive search ads. type performance_max: maximize_conversions or maximize_conversion_value only, and asset groups with headlines, long headlines, descriptions, business name, call to action and image ids from msads_list_images (never uploaded). The campaign lands PAUSED; its ad groups, ads and asset groups are ACTIVE inside it, so the status draft that enables the campaign starts them. Defaults: search partners off, presence targeting, Performance Max URL expansion and text and image automation off. Checks name, locations, image shapes, budget. Nothing changes yet; built in steps, so if one fails what landed stays in the paused campaign. validated: show the user the tree, budget, targeting and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_extension_changes
ChatGPTStep 1 of 3 for changing sitelinks, callouts and structured snippets. Operations: create (a new one, linked where it serves via link_to), edit (fields of one in the library; it changes everywhere it serves), link and unlink (by extension_id from msads_list_ad_extensions). Places: account, campaign (campaign_id) or ad_group (campaign_id + ad_group_id). Unlinking keeps it in the library; nothing is deleted. Sitelink text up to 35 characters (25 with both descriptions), descriptions 35, callouts 25, snippets 3-10 values of 25. Up to 20 of a type per place; callouts show only in twos or more. An edit to one serving from several places is blocked until acknowledged_links covers every place it named. validated: show the user the diff and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_keyword_changes
ChatGPTStep 1 of 3 for changing keywords. Reads each keyword's current state and runs HYPD's guardrails; nothing changes yet. Operations, each naming campaign_id: create (keywords at ad_group level; negative keywords with negative true at ad_group or campaign level, EXACT or PHRASE only), update (ad_group level, keyword_id: status and/or cpc_bid in the account's currency), remove (negative keywords only, by negative_keyword_id: a keyword is paused, never removed). Ids from msads_list_keywords and msads_list_negative_keywords. A draft that enables keywords holds only enables. blocked: HYPD refused it; fix and draft again with supersedes_draft_id. validated: show the user the diff, the reasoning and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_negative_keyword_list_changes
ChatGPTStep 1 of 3 for changing shared negative keyword lists. Reads each list now and runs HYPD's guardrails; nothing changes yet. Operations: create_list (list_temp_id, e.g. -1, and name; needs at least one add_item naming it), add_item and remove_item (negative keywords, EXACT or PHRASE; remove by item_id), attach and detach (a list to or from a campaign). Name a list by list_id, or a new one by list_temp_id; ids from msads_list_negative_keyword_lists and msads_get_negative_keyword_lists. Lists are never deleted: detach one instead. A list moves every campaign it is attached to: blocked names them; show the user every one, then draft again with acknowledged_campaign_ids. validated: show the user the diff and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_revert
ChatGPTStep 1 of 3 for undoing an applied Change Draft. Pass its draft_id from msads_list_changes. Builds an ordinary new draft from what the original stored: a pause or enable, a budget or a keyword goes back to what it was before; a new keyword is paused, a new negative keyword removed and a removed one added back, a list attachment or extension link undone the other way, a bid back to what it was; a list or extension HYPD created stays in the library, and nothing else is ever deleted. Reads the account now, so the diff shows current → before. Enabling is still its own approval. When part of a draft cannot be undone in one go, the tool says which operations to pass, in turn. validated: show the user the diff and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_settings_changes
ChatGPTStep 1 of 3 for changing Microsoft Ads campaign and ad group settings. edit_campaign (ids from msads_list_campaigns): name, languages (the whole new set, or ["All"]), audience_network_bid_adjustment (Search; -100 keeps ads off the Audience Network), and search_partners or ad_rotation for every ad group of a Search campaign (Microsoft keeps them per ad group; each changed ad group is listed). edit_ad_group (Search; ids from msads_list_ad_groups): name, start_date (only before it starts), end_date (YYYY-MM-DD; empty removes it), ad_rotation (optimize or rotate_evenly), search_partners. Only what an operation names changes. Status, budget, bidding, targeting and URLs have their own tools. Nothing changes yet. validated: show the user the diff and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_status_changes
ChatGPTStep 1 of 3 for pausing or enabling campaigns, ad groups or ads. Reads each target's current state and runs HYPD's guardrails; nothing changes yet. Operations: level campaign (campaign_id), ad_group (campaign_id + ad_group_id) or ad (campaign_id + ad_group_id + ad_id), each with status ENABLED or PAUSED, ids from msads_list_campaigns, msads_list_ad_groups and msads_list_ads. Deleting is not offered: pause instead. A draft that enables holds only enables, and a campaign enable is alone in its draft. blocked: HYPD refused it; fix and draft again with supersedes_draft_id. validated: show the user the diff, the reasoning and every warning, get an explicit yes, then msads_approve_change_draft.
msads_draft_targeting_changes
ChatGPTStep 1 of 3 for changing a campaign's targeting. Operations, each naming campaign_id: add_location (target or exclude, ids from msads_find_locations, optional bid_adjustment), remove_location, set_location_bid, set_location_match (presence or presence_or_interest), set_device_bid (computers, smartphones or tablets; -100 stops ads on the device; Search only), add_schedule, remove_schedule, set_schedule_bid (day, from and to as HH:MM in quarter hours, the account's time zone). Bid adjustments are whole percents, -90 to 900. Removing a location or window is undone by adding it back; nothing else is deleted. Nothing changes yet. Warns when the last targeted location or window goes, or a first window limits serving. validated: show the user the diff and every warning, get an explicit yes, then msads_approve_change_draft.
msads_find_locations
ChatGPTThe location ids a campaign targets, from Microsoft's own locations file. Pass queries (names, each looked up on its own: "Germany", "Berlin", or with broader places, "Paris, France") or location_ids to read them back. Each match has its id, full name, type (Country, State, MetroArea, City, County, PostalCode) and status: target Active ones; PendingDeprecation ones stop within 30 days, and Microsoft refuses Deprecated ones. Use the ids in msads_draft_campaign_build.
msads_get_asset_group_performance
ChatGPTPerformance Max asset-group performance for one account over a date window — the PMax counterpart to campaign performance. Rows are CSV records (every value a string), columns lists the header order, and truncated flags a cut-off result — narrow the window when it is true.
msads_get_campaign_performance
ChatGPTCampaign-level performance for one account over a date window: impressions, clicks, spend, conversions, and revenue per campaign. Rows are CSV records (every value a string), columns lists the header order, and truncated flags a cut-off result — narrow the window when it is true.
msads_get_enable_changes_link
ChatGPTBuilds the HYPD app link where the account's owner turns on Actions — the way out of a 'changes not enabled' refusal from a msads_draft_* tool. Nothing is changed by calling it: give the user the link, stop, and retry the draft once they say it is done.
msads_get_keyword_performance
ChatGPTKeyword-level performance for one account over a date window: impressions, clicks, spend, conversions, and quality signals per keyword. Rows are CSV records (every value a string), columns lists the header order, and truncated flags a cut-off result — narrow the window when it is true.
msads_get_negative_keyword_lists
ChatGPTShared negative keyword lists' negative keywords (item_id, text, match_type) and the campaigns each is attached to. Pass up to 20 list_ids from msads_list_negative_keyword_lists; the item ids are what msads_draft_negative_keyword_list_changes removes.
msads_get_search_terms
ChatGPTThe actual search queries that triggered the account's ads over a date window, with per-term performance — the raw material for negative keywords and match-type decisions. Rows are CSV records (every value a string), columns lists the header order, and truncated flags a cut-off result — narrow the window when it is true.
msads_list_accounts
ChatGPTThe user's connected Microsoft Advertising accounts — each row carries the numeric account_id every other msads_ tool takes. Every other msads_ tool takes an account_id from this list. An empty list means no Microsoft Ads connection yet (the user can reconnect this connector from their MCP client's settings and complete its connect step), and plan_notice explains accounts held back by the user's plan.
msads_list_ad_extensions
ChatGPTThe account's sitelinks, callouts and structured snippets: each one's id, type, text (sitelink display_text, descriptions and final_url; callout text; snippet header and values), whether it runs on its own schedule, and where it serves (serves_from: account, campaign:<id>; serves_from_ad_groups when it is also linked to ad groups, not listed one by one). Pass types or extension_ids for fewer. Change them with msads_draft_extension_changes.
msads_list_ad_groups
ChatGPTThe ad groups inside one campaign — ids, names, statuses, and bid settings. Takes the campaign_id from msads_list_campaigns; the ad group ids feed msads_list_ads and msads_list_keywords.
msads_list_ads
ChatGPTThe ads inside one ad group — creative text, final URLs, types, and statuses as Microsoft returns them. Takes the ad_group_id from msads_list_ad_groups.
msads_list_asset_groups
ChatGPTThe asset groups of one Performance Max campaign — headlines, descriptions, images, and their statuses. Only meaningful for PMax campaigns; partial_errors reports asset groups Microsoft could not return.
msads_list_audiences
ChatGPTThe audiences defined in one account (remarketing lists, in-market, custom) with their sizes and statuses; partial_errors reports entries Microsoft could not return.
msads_list_bid_strategies
ChatGPTThe account's portfolio bid strategies: each one's id, name, scheme (e.g. MaxConversions), target CPA, target ROAS (a ratio, 4 is 400%) or max CPC, and the campaigns on it. Pass bid_strategy_ids (up to 100) for just those; a campaign's own strategy is on msads_list_campaigns rows.
msads_list_budgets
ChatGPTThe account's shared budgets — amounts, types, and which campaigns draw on them; partial_errors reports budgets Microsoft could not return. Campaign-level budgets appear on msads_list_campaigns rows instead.
msads_list_campaigns
ChatGPTEvery campaign in one account, with its id, name, type, status, and budget settings as Microsoft returns them (PascalCase vendor fields). The ids here feed msads_list_ad_groups and msads_list_asset_groups.
msads_list_changes
ChatGPTThe Change Drafts made through HYPD on the user's Microsoft Advertising accounts, newest first: what was proposed (diff), the reasoning, the user's approval in their own words, and what landed. Use it before proposing a change, to answer what HYPD changed, and to find a draft_id for msads_draft_revert. With account_id and history_days (max 90) it also reads Microsoft's change history for that account: every change, made through HYPD or not, with who made it and with which tool, about an hour behind. That takes up to a minute; ask for it when the user wants to know what changed or who changed it.
msads_list_conversion_goals
ChatGPTThe account's conversion goals — types, counting settings, revenue values, and statuses. Relevant when conversion columns in reports look empty or double-counted; partial_errors reports goals Microsoft could not return.
msads_list_images
ChatGPTThe images in the account's media library: each one's id, width and height in pixels, and a URL to view it. Pass image_ids for just those. Performance Max asset groups link them by id, by shape: landscape 1.91:1 (at least 703x368), square 1:1 (470x470), portrait 1:2 (470x940), wide 4:1 (608x152), logos 1:1 (128x128), landscape logos 4:1 (512x128). Nothing is uploaded; pick ids here for msads_draft_campaign_build.
msads_list_keywords
ChatGPTThe keywords of one ad group — text, match type, bid, and status. Takes the ad_group_id from msads_list_ad_groups; for what actually got searched, use msads_get_search_terms instead.
msads_list_negative_keyword_lists
ChatGPTThe account's shared negative keyword lists — ids, names and item counts: what the account is deliberately NOT bidding on. Useful when search terms leak through despite negatives; a list's negative keywords and campaigns are on msads_get_negative_keyword_lists.
msads_list_negative_keywords
ChatGPTThe negative keywords set on ad groups or campaigns themselves, with their ids, text and match type: what msads_draft_keyword_changes removes by id. Pass entity_type (ad_group or campaign) and up to 50 entity_ids; for ad groups also campaign_id, the campaign they are all in. Shared lists are on msads_list_negative_keyword_lists instead; partial_errors names an entity Microsoft could not read.
msads_list_uet_tags
ChatGPTThe account's UET (Universal Event Tracking) tags with their tracking statuses — the measurement plumbing conversion goals depend on. A goal without a verified tag records nothing; partial_errors reports tags Microsoft could not return.