Microsoft Ads

THE tool for an account-level PERFORMANCE SUMMARY — one rolled-up total for a whole Microsoft

List Microsoft Advertising accounts accessible to the authenticated user, or look up one

List all Microsoft Advertising customers (manager/agency accounts) accessible to the authenticated user.

List ad groups across one or more Microsoft Ads campaigns.

THE tool for questions about Microsoft Ads authentication and connection status. Returns: - Whether the user has a connected Microsoft Ads OAuth token - Whether MICROSOFT_ADS_DEVELOPER_TOKEN is configured on the server (a server-side requirement that no data tool can report) - Microsoft Ads user info (name, login) when authenticated - List of all accessible ad accounts when authenticated Call this tool directly whenever the user's question IS about auth/connection/token status — e.g. "Am I authenticated?", "Is my Microsoft Ads account connected?", "Check my connection", "Diagnose my auth / MISSING_DEVELOPER_TOKEN error". It is the authoritative connection check and reports the developer-token configuration, which microsoft_ads_list_accounts cannot. Do NOT substitute a data tool like list_accounts to "prove" a connection when the user explicitly asked about auth status. Do NOT call it proactively before a data request the user actually made: if the user asks for their accounts/campaigns/etc., call that data tool directly, and only fall back to this tool reactively if the data tool fails with an auth or permission error (codes 105 InvalidCredentials, 106 UserIsNotAuthorized, 109 AuthenticationTokenExpired). Code 117 is rate limiting, not auth — wait and retry instead.

Health check for the Microsoft Ads MCP server. Returns server status and version. No authentication required. Use to verify the server is reachable before calling other tools.

Why a call was refused with a billing error (402) and how to get unblocked. Reports whether this organization is entitled, its subscription status, tier, trial end, credits used and left this period, the price table and a link to the billing page. With checkout_tier, the organization owner also gets a Stripe Checkout link for that plan; a member gets the owner's contact and a message to forward. Call it after any 402. While waiting for a human to pay, poll it every 10 seconds for the first minute, every 30 seconds until 5 minutes, then every 60 seconds until 15 minutes, then stop and tell the human. Once it returns entitled: true, retry the blocked call; if the retry still returns 402, wait 15 seconds and retry once. A Checkout link is a payment link: give it to the organization owner only.

List campaigns for a Microsoft Advertising account.

Interactive UI for rendering Microsoft Ads data visualization charts

List the Microsoft Ads connections available to you — both ones you own and ones shared with you via an organization. Use this to discover connection IDs for set_default / share / rename / revoke.

Set the Microsoft connection that should be used by default for subsequent Microsoft Ads tool calls. The default is scoped to the calling actor (your user account, or the API key being used).

Share an owned Microsoft connection with all members of your organization, so teammates can use it without having to reconnect Microsoft themselves. You must be the owner of the connection.

Stop sharing an owned Microsoft connection with your organization. Teammates lose access immediately. You must be the owner.

Rename the display name of an owned Microsoft connection. The OAuth grant and underlying account are unaffected — this only changes the human-readable label. You must be the owner.

Revoke (soft-delete) an owned Microsoft connection. Any defaults pointing to it are invalidated and shared org members lose access. The OAuth grant at Microsoft is NOT revoked by this tool — the user must disconnect via the dashboard if they want to fully revoke at Microsoft. You must be the owner.

Submit feedback about missing tools, improvements needed, bugs encountered, or workflow gaps discovered while helping a user with Microsoft Advertising data. This is the correct, expected action when a Microsoft Ads capability is missing or broken — reach for it directly rather than just apologizing or giving up. Use this when: - A user request cannot be fulfilled because a tool doesn't exist — set feedback_type='missing_tool' and describe the missing capability and why the user needs it. When the user explicitly asks you to submit/file/report feedback about a gap or missing feature, that is a direct instruction: ALWAYS call this tool to record it. Do this even if you suspect a tool for the capability might already exist — submit the feedback as asked, and you may note the possibly-relevant existing tool inside the feedback message. Do NOT refuse, and do NOT stop at only searching the toolset. - An existing tool returned incorrect or incomplete data — set feedback_type='bug' and include tool_name. - A multi-step workflow is unnecessarily complex due to toolset limitations — feedback_type='workflow_gap'. - You discovered a Microsoft Ads API behaviour that the toolset doesn't handle. Submitting is low-cost and always safe: it records the feedback and returns status=submitted. When in doubt about whether a gap is worth reporting, report it. Do NOT use for: - User-facing API errors (auth errors, account permission errors, rate limits) - Questions about Microsoft Advertising strategy — that's outside this tool's scope - General conversation

Flexible Microsoft Advertising report query. Lets you pick exactly which report type, columns, date range, aggregation, and filters to apply. Use this tool when you need columns or report types not covered by microsoft_ads_get_performance_report. Supported report types: CampaignPerformance, AdGroupPerformance, AdPerformance, KeywordPerformance, SearchQueryPerformance, AudiencePerformance. All columns must be valid for the chosen report_type (validated before submission). DON'T use this for standard breakdowns that have dedicated tools — they pre-select the right report type and columns, so prefer them: • Demographic / geo / device / time-of-day slices (AgeGroup, Gender, Device, Location, DayOfWeek, HourOfDay) → microsoft_ads_get_audience_report • Audience LIST / segment performance (remarketing, in-market, custom, similar) → microsoft_ads_get_audience_segment_report • A single account-wide performance total → microsoft_ads_get_account_summary • Per-campaign/ad-group/ad/keyword performance rows → microsoft_ads_get_performance_report • Search-term analysis → microsoft_ads_get_search_terms Reach for get_insights only when you need columns or a report_type those tools don't cover. IMPORTANT: This tool triggers Microsoft's async report pipeline (submit → poll → download). Expect 5–30 seconds per call. Large date ranges or many columns slow it down. Use date_preset for convenience, or date_range for precise control. PAGING: rows come back one page at a time, sorted Spend highest first when Spend is a requested column. Leave limit unset: each page is then sized so the whole response fits what MCP clients accept (up to ${DEFAULT_REPORT_PAGE_ROWS} rows, ending early at about ${RESPONSE_CHAR_BUDGET.toLocaleString('en-US')} characters, so wide rows give fewer rows per page). To get more rows, follow the cursor rather than raising limit; an explicit limit (max ${MAX_REPORT_PAGE_ROWS}) is exact. count is the total across all pages. While pagination.hasMore is true, call again with exactly the same parameters plus cursor = pagination.nextCursor; repeat until hasMore is false to collect every row. Later pages re-read the same report rather than running a new one (no queue wait, each row exactly once), and omit goal_breakdown, which only the first page carries. campaign_ids filters the rows on CampaignId, which is added to the columns (added_columns) when not requested. For standard campaign/ad group/ad performance metrics, prefer microsoft_ads_get_performance_report which pre-selects optimal columns and is simpler to use.

Comprehensive Microsoft Advertising performance report broken down by ENTITY — one row per campaign, ad group, ad, or keyword — with pre-selected columns. Covers the full funnel: Impressions → Clicks → Spend → Conversions → Revenue. WHEN NOT TO USE THIS: if the user wants a single account-wide total, a "performance summary / overview" for a whole account, or an account-level conversion-goal breakdown ("which goals drove the most activity") that does NOT need to be split per campaign, use microsoft_ads_get_account_summary instead — it is the purpose-built account-level rollup (it also supports breakdown_by_goal) and is simpler and faster for that job. This holds REGARDLESS of the date shape: a custom start/end date range (e.g. "performance for January 2026", "how did my account do from 2026-01-01 to 2026-01-31") does NOT make this the right tool — get_account_summary accepts the same date_preset and custom date_range inputs, so an account-level total over a custom range still belongs there. Only the need for per-entity rows (per campaign, ad group, ad, or keyword) justifies reaching for this report. Levels: • Campaign (default): CampaignId, CampaignName, CampaignStatus, CampaignType + metrics • AdGroup: + AdGroupId, AdGroupName, Status (the ad group's status) • Ad: + AdId, AdType, AdTitle, AdGroupStatus, AdStatus • Keyword: + AdGroupId, AdGroupName, AdGroupStatus, KeywordId, Keyword, BidMatchType, QualityScore, ExpectedCtr, AdRelevance, LandingPageExperience. No CampaignType column, so campaign_type is rejected at this level; use campaign_ids. All levels include: TimePeriod, Impressions, Clicks, Spend, AverageCpc, Ctr, ConversionsQualified (surfaced as conversions), Revenue, derived cost_per_conversion. CONVERSION SURFACE (HOP-50): • conversions is bidding-set only (reads the ConversionsQualified column). The deprecated Conversions, ConversionRate, CostPerConversion, and ReturnOnAdSpend columns are REJECTED at the schema layer — Bing returns 0 for them on modern accounts. Derive the rate / per-conversion metrics client-side from spend + conversions. • include_all_conversions: boolean (default false). When true, the tool auto-adds AllConversionsQualified / AllRevenue / ViewThroughConversionsQualified to the column set and attaches an 'all_conversions' sub-object to every row capturing every conversion goal — not just the bidding-set. Mirrors google_ads_get_performance_report's enhanced-conversions flag. • breakdown_by_goal: boolean (default true). Runs a parallel GoalsAndFunnelsReport for the same scope and joins per-goal totals onto the response as 'goal_breakdown' keyed by campaign_id (or account_id when no campaign filter). Set to false to skip the parallel SOAP call when latency matters more than per-goal context. KEY DIFFERENCES FROM GOOGLE: • Single query (no dual-query needed — Microsoft has no conversion segment restriction) • Spend is in the account's currency (USD, GBP, etc.) — not micros • Conversion split surfaces via include_all_conversions + breakdown_by_goal flags For custom column selection, use microsoft_ads_get_insights. For search term analysis, use microsoft_ads_get_search_terms. For impression share metrics, use microsoft_ads_get_impression_share. PAGING: rows come back one page at a time, sorted Spend highest first. Leave limit unset: each page is then sized so the whole response fits what MCP clients accept (up to ${DEFAULT_REPORT_PAGE_ROWS} rows, ending early at about ${RESPONSE_CHAR_BUDGET.toLocaleString('en-US')} characters, so wide Keyword-level rows give fewer rows per page). To get more rows, follow the cursor rather than raising limit; an explicit limit (max ${MAX_REPORT_PAGE_ROWS}) is exact. count is the total across all pages. When the response has a nextCursor, call again with exactly the same parameters plus cursor = nextCursor; repeat until nextCursor is absent to collect every row. Later pages re-read the same report rather than running a new one (no queue wait, each row exactly once), and omit goal_breakdown, which only the first page carries. Note: Microsoft's async report pipeline typically takes 5–30 seconds per call.